Skip to main content

Installation

Setup Suites in a New or Existing Project​

This section provides instructions for installing Suites and highlights important compatibility and configuration details for setting up unit testing with your DI framework.

info

💡 You can find complete setup examples in the Suites Examples repository

First, install Suites' main package:

$ npm i -D @suites/unit

Then, to integrate Suites with your dependency injection framework and preferred testing library, install the corresponding adapters for your project.

For example, to use Suites with Jest and NestJS you would run (alongside @suites/unit core package):

$ npm i -D @suites/doubles.jest @suites/di.nestjs

Lastly, make sure reflect-metadata is also installed in your project, not as a dev dependency (Why?):

$ npm i reflect-metadata

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

Supported Libraries​

Available Dependency Injection Adapters:​

  • @suites/di.nestjs
  • @suites/di.inversify
  • @suites/di.tsyringe (WIP)

Available Mocking Libraries Adapters:​

  • @suites/doubles.jest
  • @suites/doubles.sinon
  • @suites/doubles.vitest
  • @suites/doubles.bun (WIP)
  • @suites/doubles.deno (WIP)
  • @suites/doubles.node Vanilla (WIP)

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

Setting Up tsconfig.json​

In order to use Suites, you need to enable the emitDecoratorMetadata and experimentalDecorators options in your tsconfig.json file. This configuration is necessary for Suites to reflect class dependencies and to work with dependency injection frameworks.

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 your project's root directory (or the location specified as rootDir in your tsconfig.json).

  2. Add the reference type for your chosen mocking library:

global.d.ts
/// <reference types="@suites/doubles.jest/unit" />  // For Jest
// OR
/// <reference types="@suites/doubles.sinon/unit" /> // For Sinon
// OR
/// <reference types="@suites/doubles.vitest/unit" /> // For Vitest

This configuration ensures your project correctly recognizes the types provided by Suites (like the Mocked<T> type) without needing to import them from library-specific modules. It aligns with Suites' philosophy of reducing coupling and providing a unified API.

Monorepo Support​

Suites is fully compatible with monorepo setups, accommodating projects that use different mocking or DI frameworks.

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

Using the same mocking and DI 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. Make sure to configure your 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. Please refer to your 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 doesn't 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 your 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, you can start writing your first test. Check out the Developer Guide to learn how to write your first test using Suites.