DEV Community: Maximiliano Ezequiel Carrizo

Decorator-based Nest.js 12 tests with Jest in ESM mode

Maximiliano Ezequiel Carrizo — Fri, 30 Oct 2026 23:26:08 +0000

Nest.js 12 packages are ESM only, and Jest can only load them in its native ESM mode. So a Nest.js 12 test suite on Jest needs some setup before it runs at all.

nestjs-jest-decorators works in that setup, and it also lets you write tests as classes. Suites and tests are plain classes and methods, and test classes are Nest providers, so you use @Inject() instead of app.get(Component).

@TestSuite('Demo Test Suite')
export class DemoTest {
  @Inject()
  private readonly httpService!: HttpService;

  @Test('Get Test')
  async testGet(): Promise<void> {
    const { data } = await firstValueFrom(this.httpService.get('http://localhost:4343/demo'));
    expect(data).toBe('Hello, Test world !');
  }
}

@TestSuite is a Jest describe and @Test is a Jest it.

Installation

You need Nest.js 12, Jest 30 and Node.js ^20.19.0, ^22.12.0 or >=24.0.0. To use ts-jest, stay on TypeScript 6.0 or lower.

npm i --save-dev nestjs-jest-decorators jest @jest/globals ts-jest typescript@~6.0.0 @nestjs/testing @types/node

Your tsconfig.json needs these options:

{
  "compilerOptions": {
    "module": "esnext",
    "moduleResolution": "bundler",
    "types": ["node"],
    "esModuleInterop": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

Turn on Jest's ESM mode

Add jest.config.mjs:

export default {
  testEnvironment: 'node',
  extensionsToTreatAsEsm: ['.ts'],
  moduleNameMapper: { '^(\\.{1,2}/.*)\\.js$': '$1' },
  transform: { '^.+\\.ts$': ['ts-jest', { useESM: true }] },
  testMatch: ['<rootDir>/test/test.entrypoint.ts'],
  verbose: true,
};

Then add the test script to your package.json:

{
  "scripts": {
    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js"
  }
}

ESM mode is still experimental in Jest, so it needs the --experimental-vm-modules flag, and Node.js prints an ExperimentalWarning when it runs.

Boot the app and declare the tests

Create test/test.entrypoint.ts:

import { afterAll, beforeAll } from '@jest/globals';
import { HttpModule } from '@nestjs/axios';
import { INestApplication } from '@nestjs/common';
import { Test } from '@nestjs/testing';
import { declareTests, JestTestModule } from 'nestjs-jest-decorators';
import { DemoTest } from './tests/demo.test.js';
import { YourAppModule } from './your-app/your-app.module.js';

const tests = [DemoTest];

let app: INestApplication;

beforeAll(async () => {
  const testingModule = await Test.createTestingModule({
    imports: [
      YourAppModule, // The app to test
      JestTestModule.registerTests(tests, [HttpModule]), // Your tests, and the modules they need
    ],
  }).compile();

  app = testingModule.createNestApplication();
  await app.listen(4343);
});

afterAll(async () => {
  await app.close();
});

declareTests(tests, () => app);

Jest collects tests synchronously, before any beforeAll runs, and it has no way to delay that. That's why declareTests receives a function: tests are declared right away, and the app is only asked for each instance when a test runs.

Share tests with inheritance

Tests declared in a base class run in each subclass decorated with @TestSuite, and a subclass can override a test method:

abstract class CrudTest {
  @Test('Lists items')
  async list(): Promise<void> {
    // ...
  }
}

@TestSuite('Users')
export class UsersTest extends CrudTest {}

@TestSuite('Orders')
export class OrdersTest extends CrudTest {}

Run code around every test

Create a class with @TestEventsSuite() and add it to your list of tests. Its hooks run around every test of every suite:

import { TestEvent, TestEventsEnum, TestEventsSuite } from 'nestjs-jest-decorators';

@TestEventsSuite()
export class Events {
  @TestEvent(TestEventsEnum.BEFORE_EACH)
  async beforeEach(): Promise<void> {
    // Runs before each test
  }

  @TestEvent(TestEventsEnum.AFTER_EACH)
  async afterEach(): Promise<void> {
    // Runs after each test
  }
}

Run a single suite or test

Pick one with an environment variable. Names must match exactly, and Jest fails if no test matches, so a typo won't look like a successful run:

SUITETORUN="Demo Test Suite" npm test
TESTTORUN="Get Test" npm test

Try it

The library is MIT licensed. You can find it on npm and GitHub, where issues and suggestions are welcome.

Write your Nest.js 12 tests as decorated classes with Mocha

Maximiliano Ezequiel Carrizo — Fri, 30 Oct 2026 23:24:43 +0000

Nest.js applications are built from classes, decorators and dependency injection. Tests usually aren't: they are anonymous functions that fetch what they need with app.get(Component).

nestjs-mocha-decorators lets you write tests the same way you write the rest of your app. Suites and tests are plain classes and methods, and test classes are Nest providers.

@TestSuite('Demo Test Suite')
export class DemoTest {
  @Inject()
  private readonly httpService!: HttpService;

  @Test('Get Test')
  async testGet(): Promise<void> {
    const { data } = await firstValueFrom(this.httpService.get('http://localhost:4343/demo'));
    expect(data).toBe('Hello, Test world !');
  }
}

@TestSuite is a Mocha describe, @Test is a Mocha it, and @Inject() works as it does anywhere else in Nest.

Installation

You need Nest.js 12, Mocha 12 and Node.js ^20.19.0 or >=22.12.0. TypeScript 7 does not work with ts-node, so this setup uses TypeScript 6.0.

npm i --save-dev nestjs-mocha-decorators mocha ts-node typescript@~6.0.0 @nestjs/testing @types/mocha @types/node

Your tsconfig.json needs these options:

{
  "compilerOptions": {
    "module": "node20",
    "types": ["node", "mocha"],
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

Boot the app, then run Mocha

Create test/test.entrypoint.ts. It boots your app, declares the tests and starts Mocha:

import { HttpModule } from '@nestjs/axios';
import { Test } from '@nestjs/testing';
import { run } from 'mocha';
import { MochaTestModule, MochaTestService } from 'nestjs-mocha-decorators';
import { DemoTest } from './tests/demo.test';
import { YourAppModule } from './your-app/your-app.module';

async function bootstrap(): Promise<void> {
  try {
    const testingModule = await Test.createTestingModule({
      imports: [
        YourAppModule, // The app to test
        MochaTestModule.registerTests([DemoTest], [HttpModule]), // Your tests, and the modules they need
      ],
    }).compile();

    const app = testingModule.createNestApplication();
    await app.listen(4343);

    app.get(MochaTestService).declareTests();
    run();
  } catch (error) {
    console.error(error);
    process.exit(1);
  }
}

bootstrap();

Then add the test script to your package.json:

{
  "scripts": {
    "test": "mocha --delay --exit --require ts-node/register test/test.entrypoint.ts"
  }
}

--delay makes Mocha wait until run() is called, once Nest.js has started.

Share tests with inheritance

Because tests are classes, a base class can hold the tests that several suites have in common. Each subclass decorated with @TestSuite runs them, and can override a test method:

abstract class CrudTest {
  @Test('Lists items')
  async list(): Promise<void> {
    // ...
  }
}

@TestSuite('Users')
export class UsersTest extends CrudTest {}

@TestSuite('Orders')
export class OrdersTest extends CrudTest {}

Run code around every test

Hooks live in their own class, which you register like any other test class. They run around every test of every suite:

import { TestEvent, TestEventsEnum, TestEventsSuite } from 'nestjs-mocha-decorators';

@TestEventsSuite()
export class Events {
  @TestEvent(TestEventsEnum.BEFORE_EACH)
  async beforeEach(): Promise<void> {
    // Runs before each test
  }

  @TestEvent(TestEventsEnum.AFTER_EACH)
  async afterEach(): Promise<void> {
    // Runs after each test
  }
}

Run a single suite or test

Pick one with an environment variable. Names must match exactly:

SUITETORUN="Demo Test Suite" npm test
TESTTORUN="Get Test" npm test

Try it

The library is MIT licensed. You can find it on npm and GitHub, where issues and suggestions are welcome.