Testing Express Apps

Integration testing API endpoints with supertest - testing routes without starting a real server, mocking the database layer, and what to actually test.

What it is, in plain English: Testing an Express app means sending real HTTP-like requests to your routes and asserting on the response -- status code, body shape, headers -- without actually binding to a network port. Supertest is the standard library for this: it wraps your Express app object directly, letting tests run fast and in-process. Combined with Vitest or Jest as the test runner, this is how Express APIs are tested in production codebases.

Testing routes without starting a real server

Step 1 -- structure your app for testability

// app.js -- defines the app, but does NOT start listening:
import express from "express";
const app = express();
app.use(express.json());

app.get("/health", (req, res) => res.json({ status: "ok" }));

export default app;

// server.js -- the actual entry point, separate from app.js:
import app from "./app.js";
app.listen(3000, () => console.log("Running"));

// This split matters: tests import app.js and never touch server.js,
// so they never actually bind to a port.

Step 2 -- install supertest

# npm install -D supertest vitest

A basic test

import request from "supertest";
import { test, expect } from "vitest";
import app from "../app.js";

test("GET /health returns ok status", async () => {
  const response = await request(app).get("/health");

  expect(response.status).toBe(200);
  expect(response.body).toEqual({ status: "ok" });
});

Testing POST requests with a body

test("POST /users creates a user", async () => {
  const response = await request(app)
    .post("/users")
    .send({ name: "Alice", email: "alice@example.com" });

  expect(response.status).toBe(201);
  expect(response.body).toMatchObject({ name: "Alice" });
  expect(response.body.id).toBeDefined();
});

test("POST /users rejects missing email", async () => {
  const response = await request(app)
    .post("/users")
    .send({ name: "Alice" });   // missing email

  expect(response.status).toBe(400);
});

Testing protected routes

test("GET /profile requires authentication", async () => {
  const response = await request(app).get("/profile");
  expect(response.status).toBe(401);
});

test("GET /profile works with a valid token", async () => {
  const token = generateTestToken({ userId: 1 });
  const response = await request(app)
    .get("/profile")
    .set("Authorization", `Bearer ${token}`);

  expect(response.status).toBe(200);
});

Try It Yourself (Node.js logic)

// Testing Express routes with supertest -- the standard pattern
// (supertest needs a real Express app -- reference code shown, logic demonstrated)

const APP_STRUCTURE = `
// app.js -- export the app WITHOUT calling listen() here:
import express from "express";
const app = express();
app.use(express.json());

app.get("/health", (req, res) => res.json({ status: "ok" }));

app.post("/users", (req, res) => {
  if (!req.body.email) return res.status(400).json({ error: "email required" });
  res.status(201).json({ id: 1, email: req.body.email });
});

export default app;   // <- exported, not started

// server.js -- the ACTUAL entry point that starts listening:
import app from "./app.js";
app.listen(3000);
`;

console.log("Splitting app.js from server.js makes testing possible:");
console.log(APP_STRUCTURE.trim());

const TEST_EXAMPLE = `
import request from "supertest";
import { test, expect, describe } from "vitest";
import app from "../app.js";

describe("GET /health", () => {
  test("returns 200 with status ok", async () => {
    const res = await request(app).get("/health");
    expect(res.status).toBe(200);
    expect(res.body).toEqual({ status: "ok" });
  });
});

describe("POST /users", () => {
  test("creates a user with valid data", async () => {
    const res = await request(app)
      .post("/users")
      .send({ email: "alice@example.com" });

expect(res.status).toBe(201);
    expect(res.body).toMatchObject({ email: "alice@example.com" });
  });

test("rejects missing email with 400", async () => {
    const res = await request(app)
      .post("/users")
      .send({});

expect(res.status).toBe(400);
    expect(res.body.error).toBe("email required");
  });
});
`;

console.log("\nsupertest test file:");
console.log(TEST_EXAMPLE.trim());

console.log("\nKey insight: supertest never opens a real network port --");
console.log("it talks to the Express app object directly, making tests fast.");

Database setup/teardown and mocking strategies

Using a real test database

import { beforeAll, afterAll, beforeEach, describe, test, expect } from "vitest";
import request from "supertest";
import app from "../app.js";
import { prisma } from "../db.js";

describe("Users API", () => {
  beforeAll(async () => {
    // Point at a SEPARATE test database (never your real one!):
    // DATABASE_URL=postgresql://localhost/myapp_test
  });

  beforeEach(async () => {
    // Clean state before each test:
    await prisma.user.deleteMany();
  });

  afterAll(async () => {
    await prisma.$disconnect();
  });

  test("GET /users returns empty array initially", async () => {
    const res = await request(app).get("/users");
    expect(res.body).toEqual([]);
  });

  test("GET /users returns created users", async () => {
    await prisma.user.create({ data: { name: "Alice", email: "a@example.com" } });
    const res = await request(app).get("/users");
    expect(res.body).toHaveLength(1);
  });
});

Mocking the database layer instead

import { vi, test, expect } from "vitest";
import request from "supertest";

vi.mock("../db.js", () => ({
  prisma: {
    user: {
      findMany: vi.fn().mockResolvedValue([{ id: 1, name: "Alice" }]),
      create:   vi.fn().mockResolvedValue({ id: 2, name: "Bob" }),
    },
  },
}));

import app from "../app.js";   // imports the MOCKED db.js

test("GET /users uses mocked data", async () => {
  const res = await request(app).get("/users");
  expect(res.body).toEqual([{ id: 1, name: "Alice" }]);
});
// Faster than a real database, but tests less of the actual integration --
// the classic mocking tradeoff (speed/isolation vs realism)

Testing error responses and edge cases

test("GET /users/:id returns 404 for missing user", async () => {
  const res = await request(app).get("/users/99999");
  expect(res.status).toBe(404);
});

test("POST /users rejects invalid email format", async () => {
  const res = await request(app).post("/users").send({ email: "not-an-email" });
  expect(res.status).toBe(400);
  expect(res.body.errors).toBeDefined();
});

Testing pyramid for APIs and contract testing

// A healthy Express API test suite, by layer:

// UNIT tests -- pure functions, no Express/HTTP involved:
test("calculateDiscount applies 10% correctly", () => {
  expect(calculateDiscount(100, 0.1)).toBe(90);
});

// INTEGRATION tests -- supertest against the app, real or test DB:
test("POST /orders creates an order and updates inventory", async () => {
  const res = await request(app).post("/orders").send({ productId: 1, qty: 2 });
  expect(res.status).toBe(201);
  const product = await prisma.product.findUnique({ where: { id: 1 } });
  expect(product.stock).toBe(8);   // verifies the SIDE EFFECT, not just the response
});

// E2E tests -- full system, real server, possibly real external services
// (fewer of these -- slow, but catch integration issues unit/integration tests miss)

Contract testing for API consumers

When multiple teams or services depend on your API's exact response shape, contract testing (tools like Pact) verifies that your API continues to satisfy the shape a consumer expects, independent of either side's internal implementation. This catches breaking changes — a renamed field, a changed type — before they reach production and break a consumer that wasn't directly tested against your latest code. For a single-team API with a known set of clients, this is often overkill; for a public API or microservices architecture with many independent consumers, it closes a gap that integration tests alone don't cover, since your integration tests only verify your own expectations of your own API.

Official Sources

The Codex links only to official documentation. No third-party tutorials.