Tsed Testing

Test a Ts.ED Application

Build every tested class through the Ts.ED test injector. Never instantiate a DI-managed class (service, controller, middleware, interceptor, module) with new in a test: it bypasses injection, scopes, hooks and mocks.

Read the testing recipes for middleware, interceptor, request-context and stubbing examples. Depth: https://tsed.dev/docs/testing.md, https://tsed.dev/tutorials/vitest.md.

1. Configure Vitest

Install vitest unplugin-swc @swc/core @vitest/coverage-v8 (and supertest @types/supertest for integration tests). A project generated by tsed-cli already has this.

// vitest.config.mts
import swc from "unplugin-swc";
import {defineConfig} from "vitest/config";

export default defineConfig({
  test: {globals: true, root: "./"},
  plugins: [
    swc.vite({
      jsc: {
        target: "es2022",
        keepClassNames: true,
        parser: {syntax: "typescript", decorators: true},
        transform: {useDefineForClassFields: false, legacyDecorator: true, decoratorMetadata: true}
      }
    })
  ]
});

• Do not rely on Vitest's default esbuild transform: it does not emit decorator metadata, so constructor and @Inject() property injection resolve to undefined.
• Do not remove useDefineForClassFields: false; class fields would overwrite injected properties.
• Jest: use ts-jest per https://tsed.dev/tutorials/jest.md. It is unstable with ESM; prefer Vitest for new projects.

2. Choose the test type

1. Logic of one provider with mocked collaborators: unit test with PlatformTest.create() (steps 3-4). Fast, no HTTP server.
2. Routing, validation, serialization, middlewares chain, exception filters: integration test with PlatformTest.bootstrap(Server) + SuperTest (step 5).
3. Real database or broker: add a testcontainers package (step 6).

3. Unit test a provider

import {inject} from "@tsed/di";
import {PlatformTest} from "@tsed/platform-http/testing";
import {afterEach, beforeEach, describe, expect, it} from "vitest";
import {UsersService} from "./UsersService.js";

describe("UsersService", () => {
  beforeEach(() => PlatformTest.create());
  afterEach(() => PlatformTest.reset());

  it("should return the user", async () => {
    const service = inject(UsersService);

    expect(await service.findById("1")).toEqual({id: "1"});
  });
});

• PlatformTest.create(settings?) accepts any configuration key: PlatformTest.create({features: {beta: true}}) then read it with constant("features.beta").
• PlatformTest.get(Token) and inject(Token) return the shared instance. PlatformTest.injector is the InjectorService.
• Import inject from @tsed/di. @tsed/platform-http/testing only exports PlatformTest and FakeAdapter.
• For code without HTTP dependencies, DITest from @tsed/di offers the same create, invoke, get, reset.

4. Mock dependencies

const repository = {findById: vi.fn().mockResolvedValue({id: "1"})};

const service = await PlatformTest.invoke<UsersService>(UsersService, [{token: UsersRepository, use: repository}]);

expect(await service.findById("1")).toEqual({id: "1"});
expect(repository.findById).toHaveBeenCalledWith("1");

• PlatformTest.invoke(Token, [{token, use}]) builds a fresh instance with local mocks and runs $onInit. Always await it.
• Mock for the whole describe: PlatformTest.create({imports: [{token: UsersRepository, use: repository}]}), then inject(UsersService).
• imports entries accept use, useClass, useFactory or useAsyncFactory. useValue is ignored there.
• Symbol or factory tokens are mocked the same way: {token: DbConnection, use: fakeDb}.
• Controllers are providers: await PlatformTest.invoke<UsersController>(UsersController, [...]) and call the handler method directly with plain arguments.
• Mock only direct collaborators. Do not vi.mock() a class file that the injector must still register.

5. Integration test with SuperTest

import {PlatformTest} from "@tsed/platform-http/testing";
import SuperTest from "supertest";
import {afterAll, beforeAll, describe, expect, it} from "vitest";
import {Server} from "../Server.js";
import {UsersController} from "./UsersController.js";

describe("UsersController", () => {
  beforeAll(PlatformTest.bootstrap(Server, {mount: {"/rest": [UsersController]}}));
  afterAll(PlatformTest.reset);

  it("should call GET /rest/users/:id", async () => {
    const request = SuperTest(PlatformTest.callback());
    const response = await request.get("/rest/users/1").expect(200);

    expect(response.body).toEqual({id: "1"});
  });
});

• PlatformTest.bootstrap() returns a function; pass it to beforeAll, or call it: await PlatformTest.bootstrap(Server)().
• The platform adapter must be registered: import @tsed/platform-express (or -koa, -fastify) in Server.ts or in the spec, or pass {adapter: PlatformExpress}.
• No port is opened unless listen: true is passed. The environment is test and the logger level is off by default.
• Settings passed as second argument replace the same @Configuration keys (only mount, scopes, logger are merged). Passing imports drops the Server's own imports.
• Stub after bootstrap: vi.spyOn(PlatformTest.get(UsersService), "findById").mockResolvedValue(...).