Testing NestJS applications

This chapter follows Authorization in NestJS.

Because no class in a Nest app creates its own dependencies, a test can decide what every dependency is. @nestjs/testing builds a small module graph containing only what the test needs, with fakes in place of databases and external APIs, and resolves it exactly as the application would. Projects created with the Nest CLI already have Jest and supertest set up. The same tests run under Vitest with minor changes. For Jest itself, see Testing TypeScript with Jest.

The testing module

Test.createTestingModule() takes the same metadata as @Module(). compile() builds it, and get() returns any provider from it:

1
import { Test } from '@nestjs/testing';
2
import { CatsController } from './cats.controller';
3
import { CatsService } from './cats.service';
4

5
describe('CatsController', () => {
6
  let controller: CatsController;
7
  const catsService = { findAll: jest.fn(), findOne: jest.fn() };
8

9
  beforeEach(async () => {
10
    const moduleRef = await Test.createTestingModule({
11
      controllers: [CatsController],
12
      providers: [{ provide: CatsService, useValue: catsService }],
13
    }).compile();
14

15
    controller = moduleRef.get(CatsController);
16
  });
17

18
  it('returns the cats from the service', async () => {
19
    catsService.findAll.mockResolvedValue([{ name: 'Tom' }]);
20
    await expect(controller.findAll()).resolves.toEqual([{ name: 'Tom' }]);
21
  });
22
});

The useValue provider from Providers and dependency injection is the whole trick: the controller asks for CatsService and receives the mock. A missing provider fails compile() with the same “can’t resolve dependencies” error as the real app, which is a quick way to see what a class depends on.

Unit tests for services

A service is usually tested with its own collaborators faked. Often the simplest test does not need Nest at all:

1
import * as argon2 from 'argon2';
2
import { AuthService } from './auth.service';
3

4
it('rejects a wrong password', async () => {
5
  const users = { findByEmail: jest.fn().mockResolvedValue({ passwordHash: await argon2.hash('right') }) };
6
  const auth = new AuthService(users as never, {} as never);
7

8
  await expect(auth.validateUser('tom@example.com', 'wrong')).resolves.toBeNull();
9
});

Constructing the class directly is fine for a provider with one or two dependencies. Use the testing module once dependencies are injected by token, such as a Mongoose model under getModelToken(Cat.name), or when the test should prove that the module wiring is correct.

Overriding parts of a real module

A test can also start from a real module and replace only what it must. overrideProvider(), overrideGuard(), overrideInterceptor(), overridePipe(), and overrideFilter() swap one piece before compilation:

1
const moduleRef = await Test.createTestingModule({
2
  imports: [AppModule],
3
})
4
  .overrideProvider(CatsService)
5
  .useValue(catsService)
6
  .overrideGuard(ApiKeyGuard)
7
  .useValue({ canActivate: () => true })
8
  .compile();

overrideGuard() replaces guards bound with @UseGuards(). A global guard registered with { provide: APP_GUARD, useClass: JwtAuthGuard } cannot be reached that way, because the guard is not a provider of its own. Register it as { provide: APP_GUARD, useExisting: JwtAuthGuard } next to a plain JwtAuthGuard provider, and the test can call .overrideProvider(JwtAuthGuard). Faking authentication is convenient, but a few tests should still go through the real guard with a real token, so that the protection itself is tested.

End-to-end tests

An end-to-end test starts the whole application in memory and sends HTTP requests to it with supertest. Nothing listens on a port:

1
import { INestApplication } from '@nestjs/common';
2
import { JwtService } from '@nestjs/jwt';
3
import { Test } from '@nestjs/testing';
4
import request from 'supertest';
5
import { AppModule } from '../src/app.module';
6

7
describe('Cats (e2e)', () => {
8
  let app: INestApplication;
9
  let token: string;
10

11
  beforeAll(async () => {
12
    const moduleRef = await Test.createTestingModule({ imports: [AppModule] }).compile();
13
    app = moduleRef.createNestApplication();
14
    await app.init();
15
    token = app.get(JwtService).sign({ sub: 'user-1', email: 'tom@example.com', roles: ['user'] });
16
  });
17

18
  afterAll(() => app.close());
19

20
  it('rejects an invalid cat', () =>
21
    request(app.getHttpServer())
22
      .post('/cats')
23
      .set('Authorization', `Bearer ${token}`)
24
      .send({ name: 'Tom', age: -1 })
25
      .expect(400));
26
});

app.init() runs the lifecycle hooks, and app.close() runs the shutdown hooks, which closes database connections so that Jest can exit. The database should be a test instance, for example mongodb-memory-server, configured through the same environment variables the app already reads.

What main.ts does not give a test

The test builds the app from AppModule, not from main.ts. Anything main.ts adds to the application object is missing in the test: app.useGlobalPipes(), app.setGlobalPrefix(), app.enableCors(), app.use(helmet()). The validation test above would pass a negative age straight through if ValidationPipe were only registered in main.ts.

There are two fixes. Register global components as providers (APP_PIPE, APP_GUARD, APP_INTERCEPTOR, APP_FILTER) so they are part of the module graph, as recommended in Pipes and validation in NestJS. For settings that only exist on the application object, move them into a configureApp(app) function that both main.ts and the test setup call.

Running the tests

The CLI template defines the scripts:

1
pnpm test
2
pnpm test:watch
3
pnpm test:cov
4
pnpm test:e2e

Unit tests sit next to the code as *.spec.ts. End-to-end tests live in test/ as *.e2e-spec.ts with their own Jest configuration, test/jest-e2e.json. Keep the two apart: unit tests should run in seconds on every save, while end-to-end tests start the app and a database and belong in CI and before a merge.

Next: NestJS glossary.