Testing

Talos applications are tested with Bun’s test runner. There is no separate test framework to install or configure. Tests import from bun:test, live in a tests/ directory next to the code they cover, and follow the *.spec.ts naming convention. Because every service, middleware, and controller is a plain class resolved through the dependency injection container, you test units in isolation: construct them directly (or resolve them from a fresh Container) and hand them a mock context.

What testing looks like here

bun test discovers and runs specs with no config file. The API is Jest-compatible (describe/test/expect) and runs at native speed. Since middleware, controllers, and services are constructor-injected classes, you can new them with fakes or resolve them from a container without booting the app. The DI container is the lever for isolation. Register test doubles in place of real services and the unit under test sees a fake DB, cache, or mailer instead of the real thing. A dedicated testing environment (APP_ENV=testing) keeps configuration and behavior separate from local, staging, and production. And because every CLI generator scaffolds a matching test file next to the artifact it creates, new code starts with a spec already in place.

How it works

Convention	Detail
Test runner	Bun’s runner: `bun test`, no config file needed.
Location	A `tests/` directory inside each package or module.
File naming	`*.spec.ts` (e.g. `CorsMiddleware.spec.ts`).
Test API	`import { describe, expect, test, beforeEach, afterEach } from "bun:test"`.
Imports	Use the `@/` path alias for the unit under test, `@talosjs/*` for framework packages.
Isolation	A fresh `new Container()` and/or mock `context` per test; reset env in `afterEach`.

Running tests

Run the whole suite from the repository or package root:

# Run every *.spec.ts in the project
bun test

# Re-run on file changes
bun test --watch

# Run a single file
bun test packages/middleware/tests/CorsMiddleware.spec.ts

# Filter by test name (substring or pattern)
bun test --test-name-pattern "CORS_ORIGINS"

# Only run tests under a directory
bun test packages/middleware

bun test automatically loads .env files, so the same configuration loading your app uses is available to tests. Set APP_ENV=testing to run against the testing environment (see Using the testing environment).

Test file conventions

A spec imports the helpers it needs from bun:test, the unit under test through the @/ alias, and any framework packages it depends on:

import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { CorsMiddleware } from "@/CorsMiddleware";

Group related cases in a describe block, write one assertion-focused test per behavior, and use beforeEach/afterEach to set up and tear down shared state:

describe("CorsMiddleware", () => {
  afterEach(() => {
    // Clean up any env vars a test set, so the next test starts clean
    delete Bun.env.CORS_ORIGINS;
  });

  test("defaults to wildcard origin when CORS_ORIGINS is unset", async () => {
    // ...
  });
});

Unit testing a middleware

Middleware and controllers receive a context object. In a unit test you don’t boot the HTTP server. Instead you build a minimal mock context exposing only the fields the unit reads (method, header.get, response.header.*, response.json, and so on) and assert on what the handler wrote back. This pattern is adapted from the real CorsMiddleware spec. A small factory builds the mock context and records the headers the middleware sets:

import { afterEach, describe, expect, test } from "bun:test";
import { AppEnv } from "@talosjs/app-env";
import { CorsMiddleware } from "@/CorsMiddleware";

function createMockContext(options: { origin?: string; method?: string } = {}) {
  const responseHeaders = new Map<string, string>();

  return {
    method: options.method ?? "GET",
    header: {
      get: (name: string) => (name === "Origin" ? (options.origin ?? null) : null),
    },
    response: {
      header: {
        setAccessControlAllowOrigin(origin: string) {
          responseHeaders.set("Access-Control-Allow-Origin", origin);
          return this;
        },
        set(name: string, value: string) {
          responseHeaders.set(name, value);
          return this;
        },
      },
      // biome-ignore lint/suspicious/noExplicitAny: mock
      json(_data: any, _status?: number) {},
    },
    _responseHeaders: responseHeaders,
    // biome-ignore lint/suspicious/noExplicitAny: mock
  } as any;
}

describe("CorsMiddleware", () => {
  afterEach(() => {
    delete Bun.env.CORS_ORIGINS;
  });

  test("defaults to wildcard origin when CORS_ORIGINS is unset", async () => {
    const middleware = new CorsMiddleware(new AppEnv());
    const context = createMockContext({ origin: "https://anything.com" });

    await middleware.handler(context);

    expect(context._responseHeaders.get("Access-Control-Allow-Origin")).toBe("*");
  });

  test("restricts to configured origins", async () => {
    Bun.env.CORS_ORIGINS = "https://example.com";
    const middleware = new CorsMiddleware(new AppEnv());

    const disallowed = createMockContext({ origin: "https://evil.com" });
    await middleware.handler(disallowed);

    expect(disallowed._responseHeaders.size).toBe(0);
  });
});

The same shape works for controllers: build a mock context with the request fields the handler reads, call the handler, and assert on the response it produced. See Middleware and Controllers for the real context interface.

Testing with the container

When a class is registered through dependency injection, resolve it from a fresh container per test so registrations from one test never leak into another. Create the container in beforeEach, register the class, and get it back:

import { beforeEach, describe, expect, test } from "bun:test";
import { Container, EContainerScope } from "@talosjs/container";

describe("container resolution", () => {
  let container: Container;

  beforeEach(() => {
    container = new Container();
  });

  test("resolves a transient class as a new instance each time", () => {
    class ReportService {}

    container.add(ReportService, EContainerScope.Transient);

    expect(container.get(ReportService)).not.toBe(container.get(ReportService));
  });
});

Registering test doubles

To isolate a unit from external systems (database, cache, mailer), register a fake under the same key the real binding uses. container.add(...) rebinds a class, and container.addConstant(key, value) binds a ready-made value:

import { beforeEach, describe, expect, test } from "bun:test";
import { Container } from "@talosjs/container";
import { UserService } from "@/UserService";

class FakeMailer {
  public readonly sent: string[] = [];
  public async send(to: string) {
    this.sent.push(to);
  }
}

describe("UserService", () => {
  let container: Container;
  let mailer: FakeMailer;

  beforeEach(() => {
    container = new Container();
    mailer = new FakeMailer();
    // Bind the fake in place of the real mailer
    container.addConstant("Mailer", mailer);
    container.add(UserService);
  });

  test("emails the user on registration", async () => {
    const service = container.get(UserService);

    await service.register("apps@talos.com");

    expect(mailer.sent).toContain("apps@talos.com");
  });
});

For the full container API (scopes, constants, and injection) see Dependency injection.

Using the testing environment

Talos recognizes a dedicated testing environment alongside local, development, staging, and production. It is selected by the APP_ENV variable:

APP_ENV=testing bun test

With APP_ENV=testing, an AppEnv instance reports isTesting === true, and any environment-specific configuration loads its testing values. Drive a code path that checks the environment by setting APP_ENV before constructing AppEnv:

import { afterEach, expect, test } from "bun:test";
import { AppEnv } from "@talosjs/app-env";

afterEach(() => {
  delete Bun.env.APP_ENV;
});

test("AppEnv reports the testing environment", () => {
  Bun.env.APP_ENV = "testing";
  const env = new AppEnv();

  expect(env.isTesting).toBe(true);
  expect(env.APP_ENV).toBe("testing");
});

Config and env load in tests exactly as they do at runtime, since Bun reads .env files automatically, so prefer a dedicated .env.testing (or test-only values) over hardcoding secrets in specs. See Configuration for how environment values are resolved.

Generated test stubs

Every CLI generator scaffolds a matching test next to the artifact it creates. For example, talos middleware:create --name=Auth writes the middleware class and a companion spec in the module’s tests/ directory, pre-wired with the bun:test imports and a describe block. New code starts testable, so you fill in the cases rather than setting up the file from scratch.

talos middleware:create --name=Auth
# -> src/middlewares/AuthMiddleware.ts
# -> tests/AuthMiddleware.spec.ts

Keeping the suite trustworthy

Isolation is the thing to protect. Build fresh state in beforeEach, tear it down in afterEach, and never let one test’s env vars or container bindings reach the next. A new Container() per test keeps registrations from leaking across cases. Replace the database, cache, mailer, and HTTP clients with fakes registered in the container so a test never hits a real system. Mock the context narrowly: build only the fields the unit reads, and record what it writes so the assertions stay focused. Run with APP_ENV=testing and a test-only env file rather than reusing local or production configuration. Write one behavior per test, name it for what it proves, and remove redundant or trivial cases so the suite stays a fast, trustworthy signal.

Getting Started

AI

Framework

Command Line

What testing looks like here

How it works

Running tests

Test file conventions

Unit testing a middleware

Testing with the container

Registering test doubles

Using the testing environment

Generated test stubs

Keeping the suite trustworthy

​What testing looks like here

​How it works

​Running tests

​Test file conventions

​Unit testing a middleware

​Testing with the container

​Registering test doubles

​Using the testing environment

​Generated test stubs

​Keeping the suite trustworthy

What testing looks like here

How it works

Running tests

Test file conventions

Unit testing a middleware

Testing with the container

Registering test doubles

Using the testing environment

Generated test stubs

Keeping the suite trustworthy