SuperTest API Testing
This skill makes an AI agent write integration tests for Express/Koa/Fastify-compatible Node HTTP apps using SuperTest: pass the app object directly to request() so no port is bound, chain .expect() for status/header checks, and assert response bodies with Jest matchers. Trigger it when a Node project exposes an Express app, when the user asks to test REST endpoints without spinning up a server, or when supertest is already in devDependencies.
Core Principles
- Test the app object, not a running server.
request(app) binds to an ephemeral port per request and tears it down — no app.listen(), no port conflicts, no orphaned servers in CI.
- Export
app separately from the listener. The single biggest enabler: app.ts exports the Express app, server.ts calls listen(). Tests import app.ts only.
- Always
await (or return) the request chain. A SuperTest call is a thenable; forgetting await means the test passes before the request even fires.
.expect(status) for transport, Jest matchers for payload. Status codes and content-type belong in the chain; body shape belongs in expect(res.body).toMatchObject(...) where failure diffs are readable.
- Real database or none — never half-mocked. Either run integration tests against a disposable database (Testcontainers, SQLite in-memory) or mock the data layer entirely. Mocking two of five queries gives you tests that lie.
- Each test owns its data. Create the records a test needs inside the test (or a
beforeEach), and make cleanup idempotent. Order-dependent suites rot within a sprint.
Setup
npm install --save-dev supertest @types/supertest jest ts-jest @types/jest
The app/server split that makes everything testable:
// src/app.ts
import express from 'express';
import { usersRouter } from './routes/users';
export function createApp(): express.Express {
const app = express();
app.use(express.json());
app.use('/api/users', usersRouter);
app.get('/health', (_req, res) => res.json({ status: 'ok' }));
return app;
}
// src/server.ts — the ONLY file that listens; never imported by tests
import { createApp } from './app';
const port = Number(process.env.PORT ?? 3000);
createApp().listen(port, () => console.log(`listening on :${port}`));
First test:
// src/app.test.ts
import request from 'supertest';
import { createApp } from './app';
const app = createApp();
describe('GET /health', () => {
it('responds 200 with status ok', async () => {
const res = await request(app)
.get('/health')
.expect('Content-Type', /json/)
.expect(200);
expect(res.body).toEqual({ status: 'ok' });
});
});
Patterns
CRUD Round-Trip with Body Assertions
import request from 'supertest';
import { createApp } from './app';
import { resetDb } from '../test/helpers/db';
const app = createApp();
beforeEach(async () => {
await resetDb();
});
describe('POST /api/users', () => {
it('creates a user and returns 201 with the persisted record', async () => {
const res = await request(app)
.post('/api/users')
.send({ email: 'mira@example.com', name: 'Mira' })
.expect(201);
expect(res.body).toMatchObject({
email: 'mira@example.com',
name: 'Mira',
});
expect(res.body.id).toEqual(expect.any(String));
// Round-trip: the created resource is retrievable
const fetched = await request(app).get(`/api/users/${res.body.id}`).expect(200);
expect(fetched.body.email).toBe('mira@example.com');
});
it('rejects an invalid email with 400 and a field-level error', async () => {
const res = await request(app)
.post('/api/users')
.send({ email: 'not-an-email', name: 'Mira' })
.expect(400);
expect(res.body.errors).toContainEqual(
expect.objectContaining({ field: 'email' }),
);
});
});
Authenticated Requests
// test/helpers/auth.ts — log in once per suite, reuse the token
import request from 'supertest';
import type { Express } from 'express';
export async function getAuthToken(app: Express): Promise<string> {
const res = await request(app)
.post('/api/auth/login')
.send({ email: 'admin@example.com', password: 'test-password-123' })
.expect(200);
return res.body.token as string;
}
import request from 'supertest';
import { createApp } from './app';
import { getAuthToken } from '../test/helpers/auth';
const app = createApp();
let token: string;
beforeAll(async () => {
token = await getAuthToken(app);
});
describe('DELETE /api/users/:id', () => {
it('returns 401 without a token', async () => {
await request(app).delete('/api/users/u_123').expect(401);
});
it('deletes with a valid bearer token', async () => {
await request(app)
.delete('/api/users/u_123')
.set('Authorization', `Bearer ${token}`)
.expect(204);
});
});
Query Params, File Upload, and Custom Assertions
// Query strings via .query() — never hand-concatenate
const res = await request(app)
.get('/api/users')
.query({ page: 2, limit: 10, sort: 'createdAt' })
.expect(200);
expect(res.body.items).toHaveLength(10);
expect(res.body.page).toBe(2);
// multipart upload
await request(app)
.post('/api/avatars')
.set('Authorization', `Bearer ${token}`)
.attach('avatar', 'test/fixtures/avatar.png')
.field('alt', 'profile picture')
.expect(201);
// Function form of .expect() for response-wide invariants
await request(app)
.get('/api/users')
.expect(200)
.expect((response) => {
if (response.body.items.some((u: { password?: string }) => u.password)) {
throw new Error('password leaked in list endpoint');
}
});
Cookies and Sessions
// Persist cookies across requests with an agent
const agent = request.agent(app);
await agent
.post('/api/auth/login')
.send({ email: 'admin@example.com', password: 'test-password-123' })
.expect(200);
// agent carries the session cookie automatically
await agent.get('/api/me').expect(200);
Best Practices
- Name tests by behavior and status:
'returns 409 when email already exists', not 'test create user 2'.
- Cover the unhappy paths the framework will not: malformed JSON body, missing auth, wrong content-type, oversized payload, nonexistent IDs (404 vs 400 for invalid format).
- Run integration tests serially against a shared DB (
jest --runInBand) or give each worker its own schema; parallel workers on one mutable DB produce heisenbugs.
- Keep
Content-Type assertions as regex (/json/) — servers append ; charset=utf-8.
- Add a
jest.setup.ts that fails tests on unhandled promise rejections; SuperTest chains silently swallow them otherwise.
- For Fastify, call
await app.ready() before passing app.server to request().
Anti-Patterns
app.listen() in test setup. Port collisions across Jest workers, orphan servers on failure. request(app) exists precisely so you never listen.
- Forgetting
await on the chain. The test exits green while the request is in flight. Enable @typescript-eslint/no-floating-promises to make this a lint error.
- Asserting entire bodies with
toEqual including timestamps and IDs. Use toMatchObject plus expect.any(String) for generated fields; full-body equality breaks on every schema addition.
- One mega-test that exercises login, create, update, and delete. When it fails at step 14 you debug all 14 steps. Split per behavior, share setup via helpers.
- Seeding through raw SQL while testing through HTTP. Your seed bypasses validation and hashing; create test data through the API or through the same repository layer the app uses.
- Testing third-party middleware (body-parser limits, cors echo) — pin your config in one test if you must, but do not re-test Express itself.
When to Trigger This Skill
supertest is in devDependencies, or the user asks to test Express/Koa/NestJS HTTP endpoints.
- An API has no integration tests and the user wants coverage without deploying or binding ports.
- Reviewing failing or flaky API tests that use
app.listen, missing await, or shared mutable test data.
- The user asks how to test auth-protected routes, file uploads, or cookie sessions in Node.
- Setting up the app/server split so an existing Express codebase becomes testable.
1---2name: supertest-api-testing3description: Test Node.js HTTP APIs in-process with SuperTest — request(app) without binding a port, chained .expect assertions, auth headers, JSON body validation, and Jest integration with proper async/await patterns.4version: 1.0.05author: thetestingacademy6license: MIT7tags: [supertest, api-testing, express, nodejs, jest, integration-testing, http, rest, assertions]8testingTypes: [api, integration]9frameworks: [jest, supertest, express]10languages: [typescript, javascript]11domains: [api]12agents: [claude-code, cursor, github-copilot, windsurf, codex, aider, continue, cline, zed, bolt, gemini-cli, amp]13metadata:14 source: https://skillmd.com/skills/pramoddutta/supertest-api-testing15---1617# SuperTest API Testing1819This skill makes an AI agent write integration tests for Express/Koa/Fastify-compatible Node HTTP apps using SuperTest: pass the app object directly to `request()` so no port is bound, chain `.expect()` for status/header checks, and assert response bodies with Jest matchers. Trigger it when a Node project exposes an Express `app`, when the user asks to test REST endpoints without spinning up a server, or when `supertest` is already in `devDependencies`.2021## Core Principles22231. **Test the app object, not a running server.** `request(app)` binds to an ephemeral port per request and tears it down — no `app.listen()`, no port conflicts, no orphaned servers in CI.242. **Export `app` separately from the listener.** The single biggest enabler: `app.ts` exports the Express app, `server.ts` calls `listen()`. Tests import `app.ts` only.253. **Always `await` (or return) the request chain.** A SuperTest call is a thenable; forgetting `await` means the test passes before the request even fires.264. **`.expect(status)` for transport, Jest matchers for payload.** Status codes and content-type belong in the chain; body shape belongs in `expect(res.body).toMatchObject(...)` where failure diffs are readable.275. **Real database or none — never half-mocked.** Either run integration tests against a disposable database (Testcontainers, SQLite in-memory) or mock the data layer entirely. Mocking two of five queries gives you tests that lie.286. **Each test owns its data.** Create the records a test needs inside the test (or a `beforeEach`), and make cleanup idempotent. Order-dependent suites rot within a sprint.2930## Setup3132```bash33npm install --save-dev supertest @types/supertest jest ts-jest @types/jest34```3536The app/server split that makes everything testable:3738```typescript39// src/app.ts40import express from 'express';41import { usersRouter } from './routes/users';4243export function createApp(): express.Express {44 const app = express();45 app.use(express.json());46 app.use('/api/users', usersRouter);47 app.get('/health', (_req, res) => res.json({ status: 'ok' }));48 return app;49}50```5152```typescript53// src/server.ts — the ONLY file that listens; never imported by tests54import { createApp } from './app';5556const port = Number(process.env.PORT ?? 3000);57createApp().listen(port, () => console.log(`listening on :${port}`));58```5960First test:6162```typescript63// src/app.test.ts64import request from 'supertest';65import { createApp } from './app';6667const app = createApp();6869describe('GET /health', () => {70 it('responds 200 with status ok', async () => {71 const res = await request(app)72 .get('/health')73 .expect('Content-Type', /json/)74 .expect(200);7576 expect(res.body).toEqual({ status: 'ok' });77 });78});79```8081## Patterns8283### CRUD Round-Trip with Body Assertions8485```typescript86import request from 'supertest';87import { createApp } from './app';88import { resetDb } from '../test/helpers/db';8990const app = createApp();9192beforeEach(async () => {93 await resetDb();94});9596describe('POST /api/users', () => {97 it('creates a user and returns 201 with the persisted record', async () => {98 const res = await request(app)99 .post('/api/users')100 .send({ email: 'mira@example.com', name: 'Mira' })101 .expect(201);102103 expect(res.body).toMatchObject({104 email: 'mira@example.com',105 name: 'Mira',106 });107 expect(res.body.id).toEqual(expect.any(String));108109 // Round-trip: the created resource is retrievable110 const fetched = await request(app).get(`/api/users/${res.body.id}`).expect(200);111 expect(fetched.body.email).toBe('mira@example.com');112 });113114 it('rejects an invalid email with 400 and a field-level error', async () => {115 const res = await request(app)116 .post('/api/users')117 .send({ email: 'not-an-email', name: 'Mira' })118 .expect(400);119120 expect(res.body.errors).toContainEqual(121 expect.objectContaining({ field: 'email' }),122 );123 });124});125```126127### Authenticated Requests128129```typescript130// test/helpers/auth.ts — log in once per suite, reuse the token131import request from 'supertest';132import type { Express } from 'express';133134export async function getAuthToken(app: Express): Promise<string> {135 const res = await request(app)136 .post('/api/auth/login')137 .send({ email: 'admin@example.com', password: 'test-password-123' })138 .expect(200);139 return res.body.token as string;140}141```142143```typescript144import request from 'supertest';145import { createApp } from './app';146import { getAuthToken } from '../test/helpers/auth';147148const app = createApp();149let token: string;150151beforeAll(async () => {152 token = await getAuthToken(app);153});154155describe('DELETE /api/users/:id', () => {156 it('returns 401 without a token', async () => {157 await request(app).delete('/api/users/u_123').expect(401);158 });159160 it('deletes with a valid bearer token', async () => {161 await request(app)162 .delete('/api/users/u_123')163 .set('Authorization', `Bearer ${token}`)164 .expect(204);165 });166});167```168169### Query Params, File Upload, and Custom Assertions170171```typescript172// Query strings via .query() — never hand-concatenate173const res = await request(app)174 .get('/api/users')175 .query({ page: 2, limit: 10, sort: 'createdAt' })176 .expect(200);177expect(res.body.items).toHaveLength(10);178expect(res.body.page).toBe(2);179180// multipart upload181await request(app)182 .post('/api/avatars')183 .set('Authorization', `Bearer ${token}`)184 .attach('avatar', 'test/fixtures/avatar.png')185 .field('alt', 'profile picture')186 .expect(201);187188// Function form of .expect() for response-wide invariants189await request(app)190 .get('/api/users')191 .expect(200)192 .expect((response) => {193 if (response.body.items.some((u: { password?: string }) => u.password)) {194 throw new Error('password leaked in list endpoint');195 }196 });197```198199### Cookies and Sessions200201```typescript202// Persist cookies across requests with an agent203const agent = request.agent(app);204205await agent206 .post('/api/auth/login')207 .send({ email: 'admin@example.com', password: 'test-password-123' })208 .expect(200);209210// agent carries the session cookie automatically211await agent.get('/api/me').expect(200);212```213214## Best Practices215216- Name tests by behavior and status: `'returns 409 when email already exists'`, not `'test create user 2'`.217- Cover the unhappy paths the framework will not: malformed JSON body, missing auth, wrong content-type, oversized payload, nonexistent IDs (404 vs 400 for invalid format).218- Run integration tests serially against a shared DB (`jest --runInBand`) or give each worker its own schema; parallel workers on one mutable DB produce heisenbugs.219- Keep `Content-Type` assertions as regex (`/json/`) — servers append `; charset=utf-8`.220- Add a `jest.setup.ts` that fails tests on unhandled promise rejections; SuperTest chains silently swallow them otherwise.221- For Fastify, call `await app.ready()` before passing `app.server` to `request()`.222223## Anti-Patterns224225- **`app.listen()` in test setup.** Port collisions across Jest workers, orphan servers on failure. `request(app)` exists precisely so you never listen.226- **Forgetting `await` on the chain.** The test exits green while the request is in flight. Enable `@typescript-eslint/no-floating-promises` to make this a lint error.227- **Asserting entire bodies with `toEqual` including timestamps and IDs.** Use `toMatchObject` plus `expect.any(String)` for generated fields; full-body equality breaks on every schema addition.228- **One mega-test that exercises login, create, update, and delete.** When it fails at step 14 you debug all 14 steps. Split per behavior, share setup via helpers.229- **Seeding through raw SQL while testing through HTTP.** Your seed bypasses validation and hashing; create test data through the API or through the same repository layer the app uses.230- **Testing third-party middleware** (body-parser limits, cors echo) — pin your config in one test if you must, but do not re-test Express itself.231232## When to Trigger This Skill233234- `supertest` is in `devDependencies`, or the user asks to test Express/Koa/NestJS HTTP endpoints.235- An API has no integration tests and the user wants coverage without deploying or binding ports.236- Reviewing failing or flaky API tests that use `app.listen`, missing `await`, or shared mutable test data.237- The user asks how to test auth-protected routes, file uploads, or cookie sessions in Node.238- Setting up the app/server split so an existing Express codebase becomes testable.