🛰️ Testing API Endpoints

Why Test at the HTTP Layer?

Think of your API as a vending machine. You could unit-test the internal coil-release motor in isolation — but what customers actually care about is: put in the right code, get the right snack; put in a bad code, get a clear error and your money back. Endpoint tests check the machine through the slot, exactly the way a real caller uses it.

An endpoint test sends a genuine HTTP request — method, URL, headers, body — through your entire Express stack (routing, middleware, controller, database) and asserts on the response. That single test exercises more wiring than a dozen isolated unit tests, which is why it gives such high confidence per line.

Making the App Testable

The single most important setup step is to separate building the app from starting it. If your file both defines routes and calls app.listen(), then importing it in a test would bind a real network port — slow, and a nightmare for parallel runs.

Split into two files. app.js builds and exports the Express instance. server.js imports it and listens. Tests import app and never touch a port.

// src/app.js — builds the app, exports it, does NOT listen
const express = require('express');
const usersRouter = require('./routes/users');
const errorHandler = require('./middleware/errorHandler');

const app = express();
app.use(express.json());                 // parse JSON request bodies
app.use('/api/users', usersRouter);
app.use(errorHandler);                   // centralized error-to-response mapping

module.exports = app;

// src/server.js — the only place a real port is opened
const app = require('./app');
const port = process.env.PORT || 3000;

app.listen(port, () => console.log(`Server running on port ${port}`));

supertest in 90 Seconds

supertest wraps your Express app, boots it on a throwaway port for the duration of one request, sends the request, and gives you a fluent API to assert on the response. You chain .expect() calls for quick checks and drop into Jest's expect() for deeper assertions on the body.

const request = require('supertest');
const app = require('../src/app');

test('GET /api/users returns an empty list initially', async () => {
    const res = await request(app)
        .get('/api/users')                     // method + path
        .expect('Content-Type', /json/)        // assert a header
        .expect(200);                          // assert the status code

    expect(res.body).toEqual([]);              // assert on the parsed JSON body
});

The anatomy of a request builder:

Here is the full round trip a single supertest call makes through your stack:

A Full CRUD Suite

Let's test a products resource end to end. The suite connects once, resets before each test, and covers create, read, update, and delete. Notice that every mutating test asserts on both the response and the database — the response could lie, the database cannot.

const request = require('supertest');
const app = require('../src/app');
const db = require('../src/db');

beforeAll(async () => {
    await db.connect();
    await db.migrate();
});
afterAll(async () => {
    await db.disconnect();
});
beforeEach(async () => {
    await db.truncateAll();        // isolation: every test starts empty
});

// A factory keeps test data valid and unique
function makeProduct(overrides = {}) {
    const n = Math.random().toString(36).slice(2, 8);
    return { name: `Widget ${n}`, price: 19.99, sku: `SKU-${n}`, ...overrides };
}

describe('Products API', () => {
    test('POST creates a product and persists it', async () => {
        const res = await request(app)
            .post('/api/products')
            .send(makeProduct({ name: 'Test Widget' }))
            .expect('Content-Type', /json/)
            .expect(201);

        expect(res.body.id).toBeDefined();
        expect(res.body.name).toBe('Test Widget');

        // Verify persistence directly
        const saved = await db.findProductById(res.body.id);
        expect(saved).toBeTruthy();
        expect(saved.name).toBe('Test Widget');
    });

    test('GET returns all products', async () => {
        await db.createProduct(makeProduct());
        await db.createProduct(makeProduct());

        const res = await request(app).get('/api/products').expect(200);

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

    test('GET /:id returns one product', async () => {
        const created = await db.createProduct(makeProduct({ name: 'Findable' }));

        const res = await request(app)
            .get(`/api/products/${created.id}`)
            .expect(200);

        expect(res.body.id).toBe(created.id);
        expect(res.body.name).toBe('Findable');
    });

    test('PUT updates a product', async () => {
        const created = await db.createProduct(makeProduct({ price: 10 }));

        const res = await request(app)
            .put(`/api/products/${created.id}`)
            .send({ price: 42 })
            .expect(200);

        expect(res.body.price).toBe(42);

        const saved = await db.findProductById(created.id);
        expect(saved.price).toBe(42);           // change really persisted
    });

    test('DELETE removes a product', async () => {
        const created = await db.createProduct(makeProduct());

        await request(app)
            .delete(`/api/products/${created.id}`)
            .expect(204);                        // No Content

        const saved = await db.findProductById(created.id);
        expect(saved).toBeNull();                // gone from the database
    });
});

Testing Authentication

Most real endpoints are protected. To test them you generate a valid JWT in the test, attach it as a bearer token, and assert the endpoint lets you through. You also test the opposite: no token gets a 401, and a valid-but-insufficient token gets a 403.

const jwt = require('jsonwebtoken');
const request = require('supertest');
const app = require('../src/app');
const db = require('../src/db');

// Helper: create a user in the DB and mint a token for them
async function makeAuthedUser(role = 'user') {
    const user = await db.createUser({
        name: 'Auth User',
        email: `auth-${Date.now()}@example.com`,
        role,
    });
    const token = jwt.sign({ id: user.id, role: user.role }, process.env.JWT_SECRET);
    return { user, token };
}

describe('Protected routes', () => {
    test('rejects a request with no token', async () => {
        await request(app).get('/api/products/secret').expect(401);
    });

    test('rejects a request with a bad token', async () => {
        await request(app)
            .get('/api/products/secret')
            .set('Authorization', 'Bearer not.a.real.token')
            .expect(401);
    });

    test('allows an authenticated request', async () => {
        const { token } = await makeAuthedUser();

        const res = await request(app)
            .get('/api/products/secret')
            .set('Authorization', `Bearer ${token}`)
            .expect(200);

        expect(res.body).toBeDefined();
    });

    test('forbids a regular user from an admin action', async () => {
        const { token } = await makeAuthedUser('user');   // NOT an admin

        await request(app)
            .post('/api/products')
            .set('Authorization', `Bearer ${token}`)
            .send({ name: 'Nope', price: 1, sku: 'X' })
            .expect(403);                                  // Forbidden
    });
});

For a registration/login flow, also assert on the security-critical details: the password is hashed (never returned), and a login with the correct password issues a working token.

const bcrypt = require('bcrypt');

test('register hashes the password and returns a token', async () => {
    const res = await request(app)
        .post('/api/auth/register')
        .send({ name: 'Ada', email: 'ada@example.com', password: 'Str0ng!pass' })
        .expect(201);

    expect(res.body.token).toBeDefined();
    expect(res.body.user.password).toBeUndefined();   // never leak the password

    const saved = await db.findUserByEmail('ada@example.com');
    expect(saved.password).not.toBe('Str0ng!pass');   // stored value is hashed
    expect(await bcrypt.compare('Str0ng!pass', saved.password)).toBe(true);
});

Testing the Unhappy Paths

Beginners test the happy path and stop. Robust APIs are defined by how they fail. For every endpoint, ask: what does a caller see when the input is wrong, the resource is missing, or a uniqueness rule is broken? Each answer is a test.

describe('Error handling', () => {
    test('400 when a required field is missing', async () => {
        const res = await request(app)
            .post('/api/products')
            .set('Authorization', `Bearer ${adminToken}`)
            .send({ name: 'No price or sku' })     // invalid
            .expect(400);

        expect(res.body.error).toBeDefined();
    });

    test('404 for a product that does not exist', async () => {
        await request(app).get('/api/products/999999').expect(404);
    });

    test('409 when creating a duplicate SKU', async () => {
        await db.createProduct(makeProduct({ sku: 'DUP-1' }));

        const res = await request(app)
            .post('/api/products')
            .set('Authorization', `Bearer ${adminToken}`)
            .send(makeProduct({ sku: 'DUP-1' }))    // same SKU
            .expect(409);

        expect(res.body.error).toMatch(/sku/i);
    });
});

Practice & Quiz

test('create then read a product', async () => {
    const created = await request(app)
        .post('/api/products')
        .set('Authorization', `Bearer ${adminToken}`)
        .send({ name: 'Round Trip', price: 5, sku: 'RT-1' })
        .expect(201);

    const res = await request(app)
        .get(`/api/products/${created.body.id}`)
        .expect(200);

    expect(res.body.name).toBe('Round Trip');
});

test('admin can delete', async () => {
    const p = await db.createProduct(makeProduct());
    await request(app)
        .delete(`/api/products/${p.id}`)
        .set('Authorization', `Bearer ${adminToken}`)
        .expect(204);
    expect(await db.findProductById(p.id)).toBeNull();
});

test('regular user cannot delete', async () => {
    const p = await db.createProduct(makeProduct());
    await request(app)
        .delete(`/api/products/${p.id}`)
        .set('Authorization', `Bearer ${userToken}`)
        .expect(403);
    expect(await db.findProductById(p.id)).toBeTruthy();   // still there
});

Best Practices & Pitfalls

✅ Do

• Split app.js from server.js and hand the app to supertest
• Assert on the status code and the JSON body, not just one
• Verify persistence by querying the test database after a mutation
• Cover the unhappy paths: 400, 401, 403, 404, 409
• Generate auth tokens in a small helper so token setup stays DRY
• Reset the database in beforeEach so tests are order-independent

❌ Don't

• Call app.listen() in code you import into tests
• Only test the happy path — the failures are where bugs hide
• Trust the response body alone as proof the write happened
• Hard-code a token string that expires or leaks a real secret
• Return stack traces or SQL in error responses (test that you don't)

Summary

📚 Additional Resources

• supertest — official README and API
• Jest — the expect assertion reference
• Express — error handling middleware
• MDN — HTTP response status codes

🚀 What's Next?

Your endpoint tests only tell the truth if the database underneath them is real, fast, and isolated. Next up: Database Testing — how to stand up a genuine test database with Docker or Testcontainers, seed fixtures, and roll back between tests so every run starts clean.