Install Suites for NestJS, Inversify, or InjectionJS with Jest or Vitest

Install @suites/unit, one dependency injection adapter, and one test-double adapter. Follow these steps to reach your first test:

1. Install packages for your stack.
2. Add type references and include them in your test tsconfig.
3. Configure your runner to emit decorator metadata.
4. Choose your Quick Start framework.

Prerequisites

These requirements apply to Suites 4:

Use a supported Node major: 22, 24, or 26. Suites supports both CommonJS and ESM. Your framework and test runner may impose additional requirements.

For TestBed, enable TypeScript decorators and choose NestJS, InversifyJS, or InjectionJS. InjectionJS support requires Suites 4.1 or later and supports constructor injection, not contextual inject() calls. For plain TypeScript without a DI framework, use the standalone mock utilities.

Install Suites and adapters

Choose the command for your stack. These commands use pnpm; npm install --save-dev and yarn add --dev are equivalent. You do not need to change your application’s package manager.

pnpm add -D @suites/unit @suites/di.nestjs @suites/doubles.jest
pnpm add -D jest @jest/globals @types/jest @swc/jest @swc/core typescript

pnpm add -D @suites/unit @suites/di.nestjs @suites/doubles.vitest
pnpm add -D vitest @vitest/spy unplugin-swc @swc/core typescript

pnpm add -D @suites/unit @suites/di.inversify @suites/doubles.jest
pnpm add -D jest @jest/globals @types/jest @swc/jest @swc/core typescript

pnpm add -D @suites/unit @suites/di.inversify @suites/doubles.vitest
pnpm add -D vitest @vitest/spy unplugin-swc @swc/core typescript

pnpm add -D @suites/unit @suites/di.injectionjs @suites/doubles.jest
pnpm add -D jest @jest/globals @types/jest @swc/jest @swc/core typescript

pnpm add -D @suites/unit @suites/di.injectionjs @suites/doubles.vitest
pnpm add -D vitest @vitest/spy unplugin-swc @swc/core typescript

Keep your existing NestJS, Inversify, or InjectionJS version if it is in the supported range. For a new project, also install the framework and its runtime dependencies:

# NestJS
pnpm add @nestjs/common @nestjs/core reflect-metadata rxjs

# OR Inversify
pnpm add inversify reflect-metadata

# OR InjectionJS
pnpm add injection-js reflect-metadata

Install only one DI adapter and one doubles adapter in each test workspace. Keep the Suites packages on matching release versions. Suites discovers the adapters at runtime.

Type Reference Configuration

Suites 4 does not run a postinstall script to modify declarations. Create suites.d.ts and include exactly one doubles /unit reference and one DI /metadata reference in each test TypeScript project.

NestJS + Jest:

/// <reference types="@suites/doubles.jest/unit" />
/// <reference types="@suites/di.nestjs/metadata" />

For Vitest, replace the first line with @suites/doubles.vitest/unit. For Inversify, replace the second line with @suites/di.inversify/metadata; for InjectionJS, use @suites/di.injectionjs/metadata. For example, Inversify + Vitest uses:

/// <reference types="@suites/doubles.vitest/unit" />
/// <reference types="@suites/di.inversify/metadata" />

The doubles reference supplies module augmentations for Mocked, Stub, and mock builder methods. The DI reference selects the metadata argument type for mock() and unitRef.get(). Continue importing TestBed and these types from @suites/unit:

import { TestBed, type Mocked } from '@suites/unit';

Setting Up tsconfig.json

Enable decorator metadata and include the declaration file you just created. Merge these settings into the tsconfig used by your tests:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  },
  "include": ["src/**/*.ts", "tests/**/*.ts", "suites.d.ts"]
}

Preserve your project’s module, moduleResolution, and existing include paths. CommonJS and ESM projects are both supported; ESM projects must also use their test runner’s ESM configuration.

Import reflect-metadata before loading decorated classes, for example in your test setup file or at the top of your test entry point.

Configure the test runner

Your TypeScript transform must emit legacy decorator metadata. The following configurations use SWC, which supports it.

Jest with CommonJS tests

module.exports = {
  testEnvironment: 'node',
  testMatch: ['<rootDir>/**/*.spec.ts'],
  transform: {
    '^.+\\.m?js$': ['@swc/jest', { module: { type: 'commonjs' } }],
    '^.+\\.ts$': ['@swc/jest', {
      jsc: {
        target: 'es2022',
        parser: { syntax: 'typescript', decorators: true },
        transform: { legacyDecorator: true, decoratorMetadata: true },
      },
      module: { type: 'commonjs' },
    }],
  },
  transformIgnorePatterns: [
    '/node_modules/(?!(?:\\.pnpm/)?(?:@suites[+/]|inversify|@inversifyjs[+/]|@nestjs[+/]|uuid))',
  ],
};

The JavaScript transform handles ESM dependencies used by current framework versions in CommonJS tests. See ESM projects below if your tests also use ESM.

Run the tests:

pnpm exec jest

Vitest: decorator metadata setup

import swc from 'unplugin-swc';
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: { globals: true, include: ['**/*.spec.ts'] },
  plugins: [swc.vite({
    module: { type: 'es6' },
    jsc: {
      parser: { syntax: 'typescript', decorators: true },
      transform: { legacyDecorator: true, decoratorMetadata: true },
    },
  })],
});

For InjectionJS + Vitest, also add server.deps.external inside the existing test object. This keeps the adapter and your tests using the same InjectionJS module and token identities:

server: { deps: { external: ['injection-js'] } },

Keep the decorator metadata plugin and your other test settings.

Run the tests:

pnpm exec vitest run

SWC transforms TypeScript but does not type-check it. Run your project’s TypeScript check separately, for example pnpm exec tsc --noEmit -p tsconfig.json.

Next Step: Run Your First Test

Continue to Quick Start and choose NestJS, InversifyJS, or InjectionJS. Each path includes application code and a complete unit test. A passing first test confirms that your adapters, declarations, and decorator transform work together.

Troubleshooting

Missing Mocked or mock methods

Check that your test tsconfig includes suites.d.ts and that the file references the installed doubles adapter’s /unit entry point. Reinstalling packages does not add the references for you.

Dependencies are not discovered

Import reflect-metadata before decorated classes and check both your tsconfig and runner transform. The transform must emit legacy decorator metadata; enabling the TypeScript options alone does not configure SWC.

ESM projects

Suites supports ESM as well as CommonJS. For Jest ESM tests, follow the Jest ESM setup, emit ESM from your transform, and import test globals from @jest/globals. Keep your project’s module format and resolution settings consistent.

Monorepo Support

Install Suites and its adapters in each workspace that runs tests. Include that workspace’s suites.d.ts in its test tsconfig. Keep Jest and Vitest augmentations in separate TypeScript projects when a monorepo uses both.

Supported Libraries (Adapters)

Related References

• NestJS guide for service tests and custom injection tokens
• InversifyJS guide for symbol tokens and named dependencies
• InjectionJS guide for a complete test, token overrides, and support boundaries
• Types for module augmentation and DI metadata
• Suites 3 to 4 for existing projects

Edit this page on GitHub