Installation
Setup Suites in a New or Existing Project
Suites is compatible with a wide range of testing and dependency injection frameworks. This section provides instructions for installing Suites and highlights important compatibility and configuration details.
First, install Suites' core 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
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.
{
"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:
-
Create a
global.d.ts
file: Place this file in your project'srootDir
(as specified in yourtsconfig.json
). -
Add the reference type: Inside
global.d.ts
, include the reference type for your chosen mocking library:
/// <reference types="@suites/doubles.<YOUR_MOCKING_LIBRARY>/unit" />
- Example: If you’re using Jest, the content of the
global.d.ts
should be:
/// <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.
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
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.