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.

First, install Suites' main package:

$ npm i -D @suites/unit

Then, to fully integrate Suites into your mocking and dependency injection frameworks, install the corresponding di framework and mocking library 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
  }
}

For Yarn v1.x Users​

Due to a known issue with Yarn v1.x's postinstall script handling (see details), an extra step is required to set up reference types for your project when using Suites.

Follow these instructions to manually add the necessary type references:

  1. Create a global.d.ts file: Place this file in your project's rootDir (as specified in your tsconfig.json).

  2. Add the reference type: Inside global.d.ts, include the reference type for your chosen mocking library:

global.d.ts
/// <reference types="@suites/doubles.<YOUR_MOCKING_LIBRARY>/unit" />
  1. Example: If you’re using Jest, the content of the global.d.ts should be:
global.d.ts
/// <reference types="@suites/doubles.jest/unit" />

By adding this reference manually, you ensure that your project correctly recognizes the types from the Suites framework, allowing for a smooth development experience.

Monorepo Support​

Suites is fully compatible with Monorepo, accommodating projects that use different mocking or di frameworks.

Recommended Setups (for Monorepo / Non-Monorepo)​

If you are using Suites in a Monorepo, consider the following setups:

Using one 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 config the hoisting of the node_modules to enable Suites to detect the adapter in the workspace.

note

Unfortunately, NPM workspaces do not support the hoisting of dependencies, which means that working with different DI or mocking libraries with npm workspaces is not supported at the moment. We recommend using Yarn workspaces for this purpose.

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.