How to Use Supertest to Test HTTP APIs in Node.js

In the rapidly evolving API landscape, teams need two things: fast feedback at the code level and trustworthy, end‑to‑end validation across environments. Supertest delivers the first—blazing‑fast HTTP assertions for Node.js services. And when you are ready to collaborate across roles, run scenario tests, mock dependencies, and publish documentation, an API testing platform like Apidog completes the picture. This official, objective guide explains how to use Supertest to test APIs, where it shines, and how to pair it with Apidog to accelerate delivery with confidence.

Pro Tip: Turn your Supertest checks into production‑ready quality gates with Apidog. Design API specifications, auto‑mock endpoints, build visual assertions, run CI, and publish API docs—all in one place.

button

What Is Supertest?

Supertest is a lightweight Node.js library for testing HTTP servers. It builds on superagent and lets you write expressive assertions against status codes, headers, and response bodies—without spinning up external clients. It’s ideal when you:

Need quick, deterministic tests during development
Want to test controllers/routers close to the code
Prefer a minimal dependency footprint and fast runtime
Why teams like Supertest among modern API testing tools:
Simple, chainable assertions with .expect()
Works with any test runner (Jest, Mocha, Vitest)
Accepts either a running URL or an in‑process http.Server/Express app
Integrates easily with CI and code coverage tools

When you need collaboration, API compliance governance, environment orchestration, and visual testing, you’ll complement Supertest with an API test platform like Apidog. The rest of this article shows how to do both.

button

Install and Set Up Supertest

You can install Supertest in minutes. Use npm, pnpm, or yarn:

# npm   npm install --save-dev supertest jest

# pnpm  pnpm add -D supertest jest

# yarn

yarn add -D supertest jest

A minimal Express API (app.js):

const express = require('express');

const app = express();



app.get('/greet', (req, res) => {

  const name = req.query.name || 'World';

  res.json({ message: `Hello, ${name}!` });

});



module.exports = app;

A simple test (app.test.js) using Supertest + Jest:

const request = require('supertest');

const app = require('./app');



describe('GET /greet', () => {

  it('greets anonymously', async () => {

    const res = await request(app)

      .get('/greet')

      .expect('Content-Type', /json/)

      .expect(200);



    expect(res.body.message).toBe('Hello, World!');

  });



  it('greets by name', async () => {

    const res = await request(app)

      .get('/greet?name=Alice')

      .expect('Content-Type', /json/)

      .expect(200);



    expect(res.body.message).toBe('Hello, Alice!');

  });

});

Update package.json to run tests:

{

  "scripts": {

    "test": "jest"

  }

}

Run your tests:

npm test

If you prefer Mocha or Vitest, Supertest works the same—the .expect() API is identical.

Writing Great Supertest Assertions

Supertest’s power comes from its chainable assertions—quick to write and easy to read. Here are patterns you’ll use every day:

Status and headers

request(app)

  .get('/users')

  .expect(200)

  .expect('Content-Type', /json/);

Validate body structure with a custom function

request(app)

  .get('/users')

  .expect(200)

  .expect(res => {

    if (!Array.isArray(res.body)) throw new Error('Expected an array');

    if (res.body.length === 0) throw new Error('Expected at least one user');

  });

Exact body match or regex

request(app)

  .get('/health')

  .expect(200)

  .expect({ status: 'ok' });



request(app)

  .get('/health')

  .expect(200)

  .expect(/"status":"ok"/);

Auth, query, and payloads

request(app)

  .post('/posts')

  .set('Authorization', 'Bearer test-token')

  .send({ title: 'Hello', body: 'World' })

  .expect(201)

  .expect(res => {

    if (!res.body.id) throw new Error('Missing id');

  });

Persist cookies across requests using agent

const agent = request.agent(app);

await agent.get('/login').expect(200);

await agent.get('/me').expect(200).expect(res => {

  if (!res.body.user) throw new Error('Expected authenticated user');

});

Tip: Keep tests small and deterministic. Supertest excels at validating controllers, middleware, and adapters in isolation.

Supertest in CI/CD and Monorepos

To keep quality consistent, run Supertest in CI for every pull request. A typical setup:

Run unit + Supertest suites in parallel for speed
Use a test database (containers or an in‑memory store)
Seed small datasets per test file to avoid cross‑test coupling
Fail fast on contract regressions (status, headers, schema)

Example GitHub Actions snippet:

name: api-tests

on: [push, pull_request]

jobs:

  test:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4

        with:

          node-version: '20'

      - run: npm ci

      - run: npm test -- --ci

In monorepos, run affected tests only and cache node_modules to speed up feedback loops. Supertest’s minimal overhead makes it a great fit for large codebases.

When to Use an API Test Platform

Supertest is superb for fast, code‑level feedback. But production realities demand more:

Cross‑team collaboration (product, backend, frontend, QA)
Contract‑first API design and governance (OpenAPI)
Mock servers to unblock front‑end development
Data‑driven scenario tests and visual assertions
Multi‑environment variables, secrets, and test data
CI orchestration and shareable, interactive documentation

This is where an API test platform like Apidog shines. It unifies API design, mocking, testing, debugging and documentation to keep teams aligned and your quality gates durable.

button

Why Apidog Complements Supertest

Design and version OpenAPI specifications visually or import existing specs
Auto‑generate mock servers to parallelize front‑end and back‑end work
Build tests with visual assertions and variable extraction
Validate responses against your spec and prevent schema drift
Publish interactive online API documentation that your team and partners can consume

A Combined Workflow: Supertest + Apidog

Use Supertest for developer‑centric checks and Apidog for end‑to‑end collaboration. Here’s a pragmatic split of responsibilities:

Task	Supertest	Apidog
Controller/middleware unit checks	Excellent	Complementary
Quick contract regressions (status/headers)	Excellent	Excellent
Schema governance (OpenAPI)	Manual	First‑class
Mock servers for front‑end	Limited	Built‑in
Data‑driven scenarios	Limited	First‑class
CI orchestration across envs	Good	First‑class
Team collaboration/docs	Minimal	First‑class

Example flow:

Define or import the API spec in Apidog. Align on fields, errors, and versions.
Generate mocks so the front‑end can start immediately.
Implement endpoints in Node.js; write Supertest checks for status/headers/payloads.
In Apidog, build scenario tests and visual assertions against the same spec.
Gate merges with both suites in CI. Publish docs from Apidog.

Advanced Supertest Patterns

A few additional tips that pay off:

Centralize your request = request(app) or base URL in a helper to avoid repetition
Use factories/fixtures for repeatable payloads
Combine Supertest with schema validators (e.g., ajv) to enforce response contracts
For streaming or SSE, test headers and chunk patterns; for WebSockets, use a protocol‑specific client plus integration tests in Apidog
Keep a strict linter and formatter to maintain readability under deadline pressure

Conclusion: A Balanced Approach to API Quality

Quality APIs are built with both speed and rigor. Supertest gives developers a fast, expressive way to verify endpoints near the code—perfect for tight feedback loops and catching regressions before they escape a branch. It’s simple, dependable, and battle‑tested across many Node.js backends.

As systems grow, however, you need collaboration, contract governance, and environment‑aware execution. That’s where Apidog—an integrated API test platform—elevates your workflow. By unifying contract design (OpenAPI), mock servers, visual assertions, environment variables, and CI orchestration, Apidog helps teams move in lockstep from idea to delivery. Front‑end, back‑end, and QA can share the same source of truth while Supertest continues to guard your code paths with swift, deterministic assertions.

If you want confident velocity, use both:

Keep Supertest for rapid, code‑level tests that developers love
Adopt Apidog to design API contracts, unblock teams with mocks, validate responses against specs, and publish docs

This balanced approach yields APIs that are not only correct today but resilient as your product evolves. Start writing your Supertest checks now—and bring them to life in a production‑grade pipeline with Apidog.

button