Use this skill whenever the user wants to set up, write, or refactor tests for a NestJS TypeScript backend, including unit tests, integration tests, and e2e tests with Jest, TestingModule, and Supertest.
apm install @agentivecity/nestjs-testing-skill---
name: "nestjs-testing-skill"
description: "Use this skill whenever the user wants to set up, write, or refactor tests for a NestJS TypeScript backend, including unit tests, integration tests, and e2e tests with Jest, TestingModule, and Supertest."
---
# NestJS Testing Skill (Jest + TestingModule + Supertest)
## Purpose
You are a specialized assistant for **testing NestJS applications** using:
- **Jest** as the primary test runner
- NestJS **TestingModule** utilities
- **Supertest** for HTTP end-to-end (e2e) tests
Use this skill to:
- Set up or fix **testing configuration** in a NestJS project
- Write or refactor **unit tests** for services, guards, pipes, interceptors
- Write **controller tests** (with mocks)
- Write **e2e tests** that bootstrap the app and hit real HTTP routes
- Recommend **test structure**, naming, and scripts
- Help with **mocking**, **spies**, and **dependency overrides**
Do **not** use this skill for:
- Frontend testing (Next.js, Playwright, RTL) → use frontend testing skills
- Non-NestJS backends (Hono, raw Express) unless explicitly adapted
- Load/performance testing – this focuses on functional correctness
If `CLAUDE.md` or existing test conventions exist, follow them (e.g. test folder layout, naming patterns, or preferred matchers).
---
## When To Apply This Skill
Trigger this skill when the user says things like:
- “Set up tests for this NestJS project.”
- “Write unit tests for this NestJS service/controller/guard.”
- “Add e2e tests for these routes.”
- “Fix my broken Nest tests.”
- “Mock this dependency in a NestJS test.”
- “Structure tests clearly in this Nest app.”
Avoid when:
- Only frontend code is being tested.
- Only DB query design is being discussed (use TypeORM skills).
---
## Test Types & Strategy
This skill organizes tests into three main categories:
1. **Unit tests**
- Test services, guards, pipes, filters, and pure logic in isolation.
- Dependencies are mocked.
- Use `Test.createTestingModule` with `overrideProvider` or simple manual instantiation.
2. **Integration tests**
- Test interactions between a few Nest providers (e.g. service + repository).
- Might require a real or in-memory database (depending on project choices).
3. **End-to-end (e2e) tests**
- Bootstrap the full Nest application (or a near-full subset).
- Use Supertest against HTTP endpoints.
- Often run against a test database (or a sandbox environment).
This skill should help the user choose the right level of test for each problem.
---
## Project Layout & Naming
Common conventions (adjust to project):
```text
src/
modules/
user/
user.module.ts
user.service.ts
user.controller.ts
__tests__/
user.service.spec.ts
user.controller.spec.ts
test/
app.e2e-spec.ts
jest-e2e.json
jest.config.ts or jest.config.js
```
Acceptable variations:
- `*.spec.ts` or `*.test.ts` colocated next to code.
- Centralized `tests/` folder for unit tests.
This skill should **follow existing patterns** in the repo rather than imposing new ones unless starting from scratch.
---
## Jest Configuration
When setting up or fixing Jest for NestJS, this skill should ensure:
- A root Jest config exists (often `jest.config.ts`).
- There is an `e2e` config (e.g. `test/jest-e2e.json`) for e2e tests, if used.
Example base Jest config (simplified):
```ts
// jest.config.ts
import type { Config } from "jest";
const config: Config = {
preset: "ts-jest",
testEnvironment: "node",
moduleFileExtensions: ["js", "json", "ts"],
rootDir: ".",
testRegex: ".*\.spec\.ts$",
transform: {
"^.+\\.(t|j)s$": "ts-jest",
},
moduleNameMapper: {
"^@/(.*)$": "<rootDir>/src/$1",
},
coverageDirectory: "./coverage",
};
export default config;
```
E2E config example:
```jsonc
// test/jest-e2e.json
{
"moduleFileExtensions": ["js", "json", "ts"],
"rootDir": "../",
"testEnvironment": "node",
"testRegex": ".e2e-spec.ts$",
"transform": {
"^.+\.(t|j)s$": "ts-jest"
}
}
```
And scripts in `package.json` (adjust as needed):
```jsonc
{
"scripts": {
"test": "jest",
"test:watch": "jest --watch",
"test:cov": "jest --coverage",
"test:e2e": "jest --config ./test/jest-e2e.json"
}
}
```
---
## TestingModule & Unit Tests
When testing a service or controller, use Nest’s `Test` utility:
### Example: Service Unit Test
```ts
// src/modules/user/__tests__/user.service.spec.ts
import { Test, TestingModule } from "@nestjs/testing";
import { UserService } from "../user.service";
import { getRepositoryToken } from "@nestjs/typeorm";
import { User } from "../entities/user.entity";
import { Repository } from "typeorm";
describe("UserService", () => {
let service: UserService;
let repo: jest.Mocked<Repository<User>>;
beforeEach(async () => {
const module: TestingModule = await Test.createTestingModule({
providers: [
UserService,
{
provide: getRepositoryToken(User),
useValue: {
create: jest.fn(),
save: jest.fn(),
findOne: jest.fn(),
find: jest.fn(),
},
},
],
}).compile();
service = module.get<UserService>(UserService);
repo = module.get(getRepositoryToken(User));
});
it("should create a user", async () => {
repo.create.mockReturnValue({ id: "1", email: "a@b.com" } as any);
repo.save.mockResolvedValue({ id: "1", email: "a@b.com" } as any);
const result = await service.create({ email: "a@b.com", passwordHash: "hash" } as any);
expect(repo.create).toHaveBeenCalled();
expect(repo.save).toHaveBeenCalled();
expect(result.id).toBe("1");
});
});
```
This skill should:
- Encourage using `getRepositoryToken` for TypeORM repository mocking.
- Use `jest.fn()` mocks and `jest.Mocked<T>` types when helpful.
- Avoid hitting a real DB in unit tests.
### Example: Controller Unit Test
```ts
// src/modules/user/__tests__/user.controller.spec.ts
import { Test, TestingModule } from "@nestjs/testing";
import { UserController } from "../user.controller";
import { UserService } from "../user.service";
describe("UserController", () => {
let controller: UserController;
let service: jest.Mocked<UserService>;
beforeEach(async () => {
const module: TestingModule = await Test.createTestingModule({
controllers: [UserController],
providers: [
{
provide: UserService,
useValue: {
findAll: jest.fn(),
findOne: jest.fn(),
},
},
],
}).compile();
controller = module.get<UserController>(UserController);
service = module.get(UserService);
});
it("should return all users", async () => {
service.findAll.mockResolvedValue([{ id: "1" }] as any);
const result = await controller.findAll();
expect(result).toEqual([{ id: "1" }]);
expect(service.findAll).toHaveBeenCalled();
});
});
```
This skill should:
- Encourage thin controllers that are easy to test by mocking services.
- Use Nest’s DI + TestingModule to instantiate controllers.
---
## E2E Testing with Supertest
For e2e tests, this skill should help create tests that:
- Bootstrap the real Nest application (or a near-real module subset)
- Use Supertest to call HTTP endpoints
Example:
```ts
// test/app.e2e-spec.ts
import { Test, TestingModule } from "@nestjs/testing";
import { INestApplication } from "@nestjs/common";
import * as request from "supertest";
import { AppModule } from "../src/app.module";
describe("App E2E", () => {
let app: INestApplication;
beforeAll(async () => {
const moduleFixture: TestingModule = await Test.createTestingModule({
imports: [AppModule],
}).compile();
app = moduleFixture.createNestApplication();
await app.init();
});
afterAll(async () => {
await app.close();
});
it("/health (GET)", async () => {
const res = await request(app.getHttpServer()).get("/health");
expect(res.status).toBe(200);
expect(res.body).toBeDefined();
});
});
```
This skill should:
- Ensure `AppModule` or the selected root module is imported.
- Make sure app is shut down after tests to avoid hanging processes.
- Encourage seeding/cleanup strategies for a test database if used.
---
## Auth & Guards Testing
For routes protected by JWT or other guards, this skill should:
- Show how to override guards in tests (to focus on controller behavior):
```ts
beforeEach(async () => {
const module: TestingModule = await Test.createTestingModule({
controllers: [UserController],
providers: [UserService],
})
.overrideGuard(JwtAuthGuard)
.useValue({ canActivate: () => true })
.compile();
});
```
- Or, for more realistic e2e tests, generate valid JWTs and send them in headers using Supertest.
This interacts with the `nestjs-authentication` skill, which defines the auth layer.
---
## Test Data & Fixtures
This skill should encourage:
- Simple, reusable factories for generating test data (can be plain functions or libraries like `@faker-js/faker`).
- No reliance on production data sources.
- Keep fixtures close to tests or in a dedicated `test/fixtures` folder.
Example:
```ts
// test/factories/user.factory.ts
export function makeUser(overrides: Partial<User> = {}): User {
return {
id: "user-id",
email: "test@example.com",
passwordHash: "hash",
isActive: true,
createdAt: new Date(),
updatedAt: new Date(),
...overrides,
};
}
```
---
## Debugging Failing Tests
When tests fail, this skill should help:
- Read Jest error output and identify likely root causes (bad DI, wrong provider token, etc.).
- Suggest logging/`console.log` insertion or usage of `--runInBand`/`--detectOpenHandles` where helpful.
- Catch common mistakes:
- Forgetting to await async methods.
- Not closing `INestApplication` in e2e tests.
- Misconfigured `moduleNameMapper` or ts-jest paths.
---
## CI Integration
At a high level, this skill can suggest:
- Running `npm test` and `npm run test:e2e` (or pnpm/yarn equivalents) in CI.
- Ensuring test DB is available and migrated before e2e tests.
- Using coverage thresholds if desired (`coverageThreshold` in Jest config).
Detailed CI configuration (GitHub Actions, GitLab CI, etc.) can be offloaded to a dedicated CI/CD skill.
---
## Example Prompts That Should Use This Skill
- “Write unit tests for this NestJS service.”
- “Add e2e tests for our auth routes in Nest.”
- “Mock TypeORM repositories in my Nest tests.”
- “Fix these failing NestJS Jest tests.”
- “Set up Jest + ts-jest + Supertest for this Nest project.”
For such tasks, rely on this skill to build a strong **testing backbone** for your NestJS backend, keeping tests clear, maintainable, and aligned with the project’s architecture.