Installation

Prerequisites

• Node 16 or higher
• TypeScript project with decorators enabled
• A framework implementing IoC (NestJS, InversifyJS), or plain TypeScript classes (manually)
• A testing library (Jest, Vitest, or Sinon)

Installation

Install the core package:

npm install -D @suites/unit

Install the adapters for your framework and testing library:

npm

# Install NestJS dependencies
npm install @nestjs/common @nestjs/core reflect-metadata

# Install Suites core and adapters
npm install --save-dev @suites/unit @suites/di.nestjs @suites/doubles.jest

# Install TypeScript and Jest
npm install --save-dev ts-jest @types/jest jest typescript

pnpm

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

# Install Suites core and adapters
pnpm add -D @suites/unit @suites/di.nestjs @suites/doubles.jest

# Install TypeScript and Jest
pnpm add -D ts-jest @types/jest jest typescript

yarn

# Install NestJS dependencies
yarn add @nestjs/common @nestjs/core reflect-metadata

# Install Suites core and adapters
yarn add -D @suites/unit @suites/di.nestjs @suites/doubles.jest

# Install TypeScript and Jest
yarn add -D ts-jest @types/jest jest typescript

This installs three packages:

• @suites/unit - Core TestBed API
• @suites/di.nestjs - NestJS adapter for reading DI metadata
• @suites/doubles.jest - Jest integration for creating type-safe mocks

Suites will automatically detect the installed adapters and configure itself accordingly.

Why reflect-metadata?

reflect-metadata is required as a runtime dependency (not dev dependency) because TypeScript's decorator metadata is only emitted at compile time. Learn more in the TypeScript Handbook.

Supported Libraries (Adapters)

Framework Adapters:

• @suites/di.nestjs - NestJS dependency injection
• @suites/di.inversify - InversifyJS dependency injection

Coming Soon

TestBed.manual for functional composition and other IoC implementations beyond dependency injection

Available Mocking Libraries:

• @suites/doubles.jest
• @suites/doubles.sinon
• @suites/doubles.vitest

After installation, no additional configuration for the test runner is needed.

Setting Up tsconfig.json

To use Suites, enable the emitDecoratorMetadata and experimentalDecorators options in the tsconfig.json file. This configuration is necessary for Suites to reflect class dependencies and constructor metadata.

tsconfig.json

{
  "compilerOptions": {
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true
  }
}

Type Reference Configuration

To ensure type safety and maintain a clean API, Suites requires setting up type references for your mocking library. This approach enables importing all utilities from @suites/unit while maintaining proper type information.

Setting Up Type References

1. Create a global.d.ts file in the project root directory (or the location specified as rootDir in the tsconfig.json).

2. Add reference types for the mocking library and dependency injection framework:

global.d.ts

// Mocking library (choose one)
/// <reference types='@suites/doubles.jest/unit' />
/// <reference types='@suites/di.nestjs/types' />
// OR
/// <reference types='@suites/doubles.sinon/unit' />
/// <reference types='@suites/di.inversify/types' />
// OR
/// <reference types='@suites/doubles.vitest/unit' />
/// <reference types='@suites/di.nestjs/types' />

Example for Jest + NestJS:

global.d.ts

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

This configuration ensures the project correctly recognizes the types provided by Suites (like the Mocked<T> type) without needing to import them from library-specific modules.

Monorepo Support

Suites is fully compatible with monorepo setups, accommodating projects that use different testing frameworks.

Recommended Setups

When using Suites in a monorepo, consider the following setups:

Using the same mocking and dependency injection framework across all workspaces
Install the corresponding adapter under the root directory of your monorepo. Suites will automatically detect the adapter and configure itself accordingly.

Using different frameworks across workspaces
Install the corresponding adapter in each workspace separately. Configure the package manager's hoisting settings to enable Suites to detect the adapter in each workspace.

note

Some package managers may have limitations with dependency hoisting that can affect using different DI or mocking libraries across workspaces. Refer to the package manager's documentation for specific guidance on dependency hoisting.

For Vitest Users

When integrating Suites with Vitest, additional configuration is required. Vitest typically uses esbuild for TypeScript interpretation, which does not support emitDecoratorMetadata - a feature extensively used by Suites for reflecting class dependencies. To overcome this, switch to using @swc/core via a plugin, which supports emitDecoratorMetadata. For detailed guidance, see the Vitest documentation.

Here is an example of how to configure Suites with Vitest:

First, install the unplugin-swc and @swc/core packages and add it to the vitest.config.ts file as a plugin. This will enable @swc/core to interpret TypeScript files and support emitDecoratorMetadata.

$ npm install --save-dev unplugin-swc @swc/core

vitest.config.ts

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

export default defineConfig({
  test: { globals: true, root: './' },
  plugins: [swc.vite({ module: { type: 'es6' } })],
});

What's Next?

After installing Suites, the first test can be written. Check out the Quick Start guide to write the first test, or explore the Guides section for testing patterns.