Supertest

A Node.js library for HTTP integration testing. Write fluent request chains against Express, Fastify, Koa, or NestJS apps — with assertions on status codes, response bodies, and headers — without spinning up a real server.

What is Supertest?

Supertest is a Node.js HTTP integration testing library built on top of SuperAgent. It accepts a Node.js HTTP application (Express, Fastify via an HTTP adapter, Koa, NestJS) and makes it easy to send HTTP requests and assert on the responses — all without calling app.listen() or managing ports yourself.

Supertest is ideal for integration tests that cover the full request lifecycle: routing, middleware, validation, business logic, and database interactions together. Because tests hit real route handlers (not mocks), they provide high confidence that your API contracts are correct. Pair Supertest with an in-memory database or transaction rollback for fast, isolated integration tests.

Key Features

• No server management — pass your app directly to request(app); Supertest binds it to an ephemeral port automatically
• Fluent chaining — chain .get(), .post(), .set(), .send(), .expect(), .attach() in a single readable expression
• Built-in assertions — assert on status code, response body, and headers with .expect() without a separate assertion library
• Auth support — set headers with .set('Authorization', 'Bearer token') for JWT or API key authentication
• Cookie sessions — use request.agent(app) to persist cookies across multiple requests in a test
• File uploads — test multipart/form-data routes with .attach(fieldName, filePath)
• Works with any test runner — Jest, Vitest, Mocha, node:test — Supertest returns a Promise
• TypeScript — full types available via @types/supertest

Installation

# Install supertest and types
npm install --save-dev supertest @types/supertest

# Supertest works with any Node.js HTTP server:
# Express, Fastify (via http adapter), Koa, Hapi, NestJS, etc.

# Common test runner pairings:
npm install --save-dev vitest           # modern, fast
npm install --save-dev jest @types/jest # classic

Basic Route Tests

Export your app without calling app.listen(). Pass it to request(app) in your tests — Supertest handles the server binding internally.

// app.ts — a minimal Express app to test
import express from 'express';
const app = express();
app.use(express.json());

app.get('/api/users', (req, res) => {
  res.json([
    { id: 1, name: 'Alice' },
    { id: 2, name: 'Bob'   },
  ]);
});

app.post('/api/users', (req, res) => {
  const { name, email } = req.body;
  if (!name || !email) {
    return res.status(400).json({ error: 'name and email are required' });
  }
  res.status(201).json({ id: 3, name, email });
});

export default app; // export without .listen() — supertest handles binding

// tests/users.test.ts
import request from 'supertest';
import app from '../src/app';

describe('GET /api/users', () => {
  it('returns a list of users', async () => {
    const res = await request(app)
      .get('/api/users')
      .expect('Content-Type', /json/)
      .expect(200);

    expect(Array.isArray(res.body)).toBe(true);
    expect(res.body).toHaveLength(2);
    expect(res.body[0]).toMatchObject({ id: 1, name: 'Alice' });
  });
});

describe('POST /api/users', () => {
  it('creates a user with valid data', async () => {
    const res = await request(app)
      .post('/api/users')
      .send({ name: 'Carol', email: '[email protected]' })
      .expect(201);

    expect(res.body).toMatchObject({ name: 'Carol', email: '[email protected]' });
    expect(res.body.id).toBeDefined();
  });

  it('returns 400 when required fields are missing', async () => {
    const res = await request(app)
      .post('/api/users')
      .send({ name: 'Carol' }) // missing email
      .expect(400);

    expect(res.body.error).toBe('name and email are required');
  });
});

Testing Authentication

Use .set('Authorization', ...) to inject tokens. Generate real JWTs using your own token helper so middleware validation exercises the actual auth logic.

// Testing authenticated endpoints
import request from 'supertest';
import app from '../src/app';
import { generateToken } from '../src/auth/jwt';

describe('Protected routes', () => {
  let authToken: string;

  beforeAll(() => {
    // Generate a real JWT (or a test-specific one)
    authToken = generateToken({ id: 1, role: 'admin' });
  });

  it('returns 401 without a token', async () => {
    await request(app)
      .get('/api/admin/users')
      .expect(401);
  });

  it('returns 200 with a valid Bearer token', async () => {
    const res = await request(app)
      .get('/api/admin/users')
      .set('Authorization', "Bearer " + authToken)
      .expect(200);

    expect(Array.isArray(res.body)).toBe(true);
  });

  it('returns 403 for insufficient role', async () => {
    const userToken = generateToken({ id: 2, role: 'user' });
    await request(app)
      .delete('/api/admin/users/1')
      .set('Authorization', "Bearer " + userToken)
      .expect(403);
  });
});

File Upload Testing

Test file upload endpoints using .attach(fieldName, filePath). Supertest automatically sets the multipart/form-data content type and boundary.

// Testing file uploads with multipart/form-data
import request from 'supertest';
import path from 'path';
import app from '../src/app';

describe('POST /api/upload', () => {
  it('uploads a file successfully', async () => {
    const res = await request(app)
      .post('/api/upload')
      .attach('file', path.join(__dirname, 'fixtures/test-image.png'))
      .field('description', 'Test upload')
      .set('Authorization', 'Bearer test-token')
      .expect(200);

    expect(res.body.filename).toBeDefined();
    expect(res.body.size).toBeGreaterThan(0);
  });

  it('rejects files that are too large', async () => {
    await request(app)
      .post('/api/upload')
      .attach('file', path.join(__dirname, 'fixtures/large-file.zip'))
      .expect(413); // Payload Too Large
  });
});

Persistent Sessions with request.agent()

Use request.agent(app) to create a stateful agent that persists cookies across requests. Essential for testing login/logout flows and session-based authentication.

// Persisting cookies across requests with supertest agent
import request from 'supertest';
import app from '../src/app';

describe('Session-based auth', () => {
  it('maintains session cookies across requests', async () => {
    // Create an agent that persists cookies
    const agent = request.agent(app);

    // Log in — the agent stores the session cookie
    await agent
      .post('/api/login')
      .send({ email: '[email protected]', password: 's3cret' })
      .expect(200);

    // Subsequent requests automatically send the stored cookie
    const profile = await agent
      .get('/api/me')
      .expect(200);

    expect(profile.body.email).toBe('[email protected]');

    // Log out
    await agent.post('/api/logout').expect(200);
  });
});

Supertest vs Other Approaches

Pros and Cons