Packages

@xtaskjs/testing

Testing runtime and module builder for isolated DI containers and provider overrides.

npm install -D @xtaskjs/testing vitest reflect-metadata Package path: packages/testing

Overview

What this package owns in the runtime

Testing provides a focused testing module API for xtaskjs services and controllers. It builds isolated DI containers, supports provider overrides, and helps teams write unit and integration tests without booting a full HTTP runtime.

What it provides

Test.createTestingModule() starts an isolated module graph from metadata or module classes.
overrideProvider(token) supports useValue, useClass, and useFactory override strategies.
moduleRef.get() and moduleRef.resolve() expose sync or async-friendly provider lookup.
moduleRef.close() triggers teardown hooks and clears test container state.

How it fits

Used by xtask-cli test generators (controller-test, service-test, resource-tests) for starter scaffolds.
Demonstrated by the 25-testing_app sample with DI overrides and lifecycle assertions.
Pairs with Node test runner or Vitest in CI pipelines to keep service-level tests fast and deterministic.

Usage Chart

How strongly this package shapes the runtime

Bootstrap

4/5

Dependency Injection

5/5

Testing

5/5

Operations

4/5

Integrations

4/5

Package Flow

How this package moves through xtaskjs runtime phases

Before startup

Build test module metadata and provider overrides so each test can compile an isolated container graph.

During compile()

The testing runtime resolves providers through xtask DI semantics, applies overrides, and returns a scoped module reference.

During moduleRef.close()

Lifecycle hooks run and container state is disposed so tests remain isolated between runs.

API Surface

Representative exports from the upstream package

Usage

Typical adoption flow

1. Create a testing module

Use Test.createTestingModule() with providers or module metadata matching the unit under test.

2. Override dependencies

Replace repositories, services, or transport clients via overrideProvider() to isolate behavior.

3. Resolve and cleanup

Resolve providers with moduleRef.get() or moduleRef.resolve(), then call moduleRef.close() in teardown.

Example

Reference snippet

Create a testing module with provider overrides

import "reflect-metadata";
import { Test } from "@xtaskjs/testing";
import { UsersService } from "./users.service";
import { UsersRepository } from "./users.repository";

const repositoryMock = {
  findAll: () => [{ id: "1", name: "Ada" }],
};

const moduleRef = await Test.createTestingModule({
  providers: [UsersService, UsersRepository],
})
  .overrideProvider(UsersRepository)
  .useValue(repositoryMock)
  .compile();

const service = moduleRef.get(UsersService);
service.findAll();

await moduleRef.close();

Samples

Official samples to inspect next

Reference samples: 25-testing_app