NestJS Testing
NestJS has a first-class testing module. The pattern: build a synthetic IoC container with the providers you want, override what you need, and exercise the system.
Test framework
Default in Nest CLI is Jest. If the project uses Vitest, the patterns translate 1:1 — the imports change (@nestjs/testing works with both).
Test scripts in package.json:
{
"scripts": {
"test": "jest",
"test:watch": "jest --watch",
"test:cov": "jest --coverage",
"test:e2e": "jest --config ./test/jest-e2e.json"
}
}
E2E tests live in test/ (or apps/<app>/test/ in monorepo) and use a separate Jest config that picks up *.e2e-spec.ts.
Unit test — service with mocked deps
// src/users/users.service.spec.ts
import { Test, TestingModule } from '@nestjs/testing';
import { getRepositoryToken } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { UsersService } from './users.service';
import { User } from './entities/user.entity';
describe('UsersService', () => {
let service: UsersService;
let repo: jest.Mocked<Repository<User>>;
beforeEach(async () => {
const module: TestingModule = await Test.createTestingModule({
providers: [
UsersService,
{
provide: getRepositoryToken(User),
useValue: {
findOne: jest.fn(),
find: jest.fn(),
save: jest.fn(),
create: jest.fn(),
delete: jest.fn(),
},
},
],
}).compile();
service = module.get(UsersService);
repo = module.get(getRepositoryToken(User));
});
it('finds a user by email', async () => {
const user = { id: '1', email: 'a@b.c' } as User;
repo.findOne.mockResolvedValue(user);
expect(await service.findByEmail('a@b.c')).toBe(user);
expect(repo.findOne).toHaveBeenCalledWith({ where: { email: 'a@b.c' } });
});
it('returns null when not found', async () => {
repo.findOne.mockResolvedValue(null);
expect(await service.findByEmail('missing@b.c')).toBeNull();
});
});
Key points:
- Use
getRepositoryToken(Entity) as the provider token — TypeORM's @InjectRepository resolves to this.
- Type the mock as
jest.Mocked<Repository<User>> for autocomplete and type safety on mockResolvedValue / mockRejectedValue.
Mocking Prisma
import { mockDeep, DeepMockProxy } from 'jest-mock-extended';
import { PrismaClient } from '@prisma/client';
let prisma: DeepMockProxy<PrismaClient>;
beforeEach(async () => {
prisma = mockDeep<PrismaClient>();
const module = await Test.createTestingModule({
providers: [
UsersService,
{ provide: PrismaService, useValue: prisma },
],
}).compile();
service = module.get(UsersService);
});
it('creates a user', async () => {
const created = { id: '1', email: 'a@b.c' };
prisma.user.create.mockResolvedValue(created as any);
const result = await service.create({ email: 'a@b.c', password: 'secret' });
expect(result).toEqual(created);
});
jest-mock-extended (pnpm add -D jest-mock-extended) provides typed deep mocks — Prisma's nested API (prisma.user.create, prisma.user.findMany) gets full type info.
Mocking Mongoose
import { getModelToken } from '@nestjs/mongoose';
const userModelMock = {
findOne: jest.fn().mockReturnValue({ exec: jest.fn() }),
create: jest.fn(),
// ...
};
beforeEach(async () => {
const module = await Test.createTestingModule({
providers: [
UsersService,
{ provide: getModelToken(User.name), useValue: userModelMock },
],
}).compile();
});
Mongoose's chained API (.findOne().exec()) makes mocks fiddly — return { exec: jest.fn() } from each query method.
Integration test — real container, mocked external services
For controllers with services, often you want real DI through the controller-service-repository chain but mock the database:
const module = await Test.createTestingModule({
controllers: [UsersController],
providers: [
UsersService,
{ provide: getRepositoryToken(User), useValue: repoMock },
{ provide: MailerService, useValue: { send: jest.fn().mockResolvedValue(undefined) } },
],
})
.overrideGuard(JwtAuthGuard)
.useValue({ canActivate: () => true })
.compile();
.overrideGuard(...).useValue(...) is the cleanest way to bypass auth in tests.
E2E test
// test/users.e2e-spec.ts
import { Test, TestingModule } from '@nestjs/testing';
import { INestApplication, ValidationPipe } from '@nestjs/common';
import * as request from 'supertest';
import { AppModule } from '../src/app.module';
describe('UsersController (e2e)', () => {
let app: INestApplication;
beforeAll(async () => {
const module: TestingModule = await Test.createTestingModule({
imports: [AppModule],
})
.overrideProvider(MailerService).useValue({ send: jest.fn() })
.compile();
app = module.createNestApplication();
app.useGlobalPipes(new ValidationPipe({ whitelist: true, forbidNonWhitelisted: true }));
await app.init();
});
afterAll(async () => {
await app.close();
});
it('POST /users → 201', async () => {
const res = await request(app.getHttpServer())
.post('/users')
.send({ email: 'new@user.com', password: 'longenough' })
.expect(201);
expect(res.body).toMatchObject({ email: 'new@user.com' });
expect(res.body).not.toHaveProperty('passwordHash');
});
it('POST /users with extra field → 400', async () => {
await request(app.getHttpServer())
.post('/users')
.send({ email: 'a@b.c', password: 'longenough', isAdmin: true })
.expect(400); // forbidNonWhitelisted catches this
});
});
Use app.getHttpServer() (not app.listen()) — supertest binds to a random port itself.
For database, prefer:
- A test container (Postgres/Mongo via Testcontainers) per suite.
- Or a separate test database with migrations applied in
beforeAll.
- Or in-memory (sqlite-memory for TypeORM, mongo-memory-server) for speed — caveat: subtle differences from real DB.
E2E test database setup pattern
beforeAll(async () => {
const module = await Test.createTestingModule({
imports: [AppModule],
})
.overrideProvider(getDataSourceToken())
.useFactory({
factory: async () => {
const ds = new DataSource({
type: 'sqlite',
database: ':memory:',
entities: [User, Order],
synchronize: true, // OK in tests
});
await ds.initialize();
return ds;
},
})
.compile();
// ...
});
Test fixtures
For repeated entities, factory functions:
// test/factories/user.factory.ts
import { faker } from '@faker-js/faker';
import { User } from '../../src/users/entities/user.entity';
export const userFactory = (overrides: Partial<User> = {}): User => ({
id: faker.string.uuid(),
email: faker.internet.email(),
passwordHash: '$argon2id$...',
metadata: {},
createdAt: new Date(),
updatedAt: new Date(),
...overrides,
} as User);
Use userFactory({ email: 'specific@x.com' }) in tests to override what matters and get reasonable defaults for the rest.
Coverage discipline
Target ≥80% for services and controllers. These hold business logic.
Don't measure coverage on:
- Modules (
*.module.ts) — pure configuration.
- Decorator definitions — DSL, not logic.
- DTOs/entities — schemas, not logic.
main.ts — bootstrap.
Configure Jest to exclude:
// package.json
{
"jest": {
"collectCoverageFrom": [
"src/**/*.{ts,js}",
"!src/**/*.module.ts",
"!src/**/*.dto.ts",
"!src/**/*.entity.ts",
"!src/main.ts"
]
}
}
Iteration cap (from QA agent)
The qa-engineer agent has a hard 3-attempt cap on fixing failing tests. If a test is fundamentally fragile after 3 attempts, mark it it.skip(...) with a comment explaining why and report in the QA summary. Don't iterate past the cap.
Anti-patterns
- ❌ Sharing mock state between tests without
beforeEach reset.
- ❌ Real database calls in unit tests (slow, flaky).
- ❌ E2E tests against
localhost:3000 — use app.getHttpServer() so each test creates its own port.
- ❌ Asserting on
body.passwordHash not being there as the only protection — also test that the endpoint excludes it via DTO/serializer.
- ❌
expect(spy).toHaveBeenCalled() without .toHaveBeenCalledWith(...) — half a test.
- ❌ Long e2e tests that exercise dozens of routes — split per resource.
- ❌ Mocking the SUT (test the real thing; mock its deps).