Testing a Typed API with Vitest & Supertest

Everything so far has been validated by the compiler and by Zod at runtime, but neither one confirms the API actually behaves correctly end to end. That's what integration tests are for.

npm install -D vitest supertest @types/supertest

Supertest sends real HTTP requests to your Express app in-process, no separate server or port needed, and Vitest runs the assertions, both fully typed against your existing app.

Testing a validated endpoint

TypeScript

import { describe, it, expect } from 'vitest';
import request from 'supertest';
import { app } from './app'; // the Express app, exported without calling .listen()

describe('POST /tasks', () => {
  it('creates a task with valid input', async () => {
    const response = await request(app)
      .post('/tasks')
      .send({ title: 'Write tests', priority: 'medium' });

    expect(response.status).toBe(201);
    expect(response.body).toMatchObject({ title: 'Write tests', priority: 'medium', done: false });
    expect(typeof response.body.id).toBe('string');
  });

  it('rejects an invalid priority with 400', async () => {
    const response = await request(app)
      .post('/tasks')
      .send({ title: 'Write tests', priority: 'urgent' }); // not in the enum

    expect(response.status).toBe(400);
    expect(response.body.error).toBeDefined();
  });
});

import { describe, it, expect } from 'vitest';
import request from 'supertest';
import { app } from './app'; // the Express app, exported without calling .listen()

describe('POST /tasks', () => {
  it('creates a task with valid input', async () => {
    const response = await request(app)
      .post('/tasks')
      .send({ title: 'Write tests', priority: 'medium' });

    expect(response.status).toBe(201);
    expect(response.body).toMatchObject({ title: 'Write tests', priority: 'medium', done: false });
    expect(typeof response.body.id).toBe('string');
  });

  it('rejects an invalid priority with 400', async () => {
    const response = await request(app)
      .post('/tasks')
      .send({ title: 'Write tests', priority: 'urgent' }); // not in the enum

    expect(response.status).toBe(400);
    expect(response.body.error).toBeDefined();
  });
});

Splitting app (the Express application) from the code that calls app.listen() is what makes this possible, Supertest talks to app directly in memory, no real network socket or port conflict involved. The second test is just as important as the first: it proves the 400/Zod-validation path from the earlier lesson actually fires for bad input, not just that the happy path works.

Testing the full lifecycle

TypeScript

it('creates, fetches, and deletes a task', async () => {
  const created = await request(app).post('/tasks').send({ title: 'Temp task', priority: 'low' });
  const id = created.body.id;

  await request(app).get(`/tasks/${id}`).expect(200);
  await request(app).delete(`/tasks/${id}`).expect(200);
  await request(app).get(`/tasks/${id}`).expect(404); // gone after delete
});

it('creates, fetches, and deletes a task', async () => {
  const created = await request(app).post('/tasks').send({ title: 'Temp task', priority: 'low' });
  const id = created.body.id;

  await request(app).get(`/tasks/${id}`).expect(200);
  await request(app).delete(`/tasks/${id}`).expect(200);
  await request(app).get(`/tasks/${id}`).expect(404); // gone after delete
});

One test walking through create → read → delete catches a class of bug unit tests on individual functions miss entirely: whether the pieces actually agree with each other once wired together as real HTTP requests.

TIP

Test both the happy path (valid input, expected status) and at least one failure path (invalid input, missing resource) for every endpoint, a suite that only exercises success cases won't catch a broken validation rule or a wrong error status code.

Testing a Typed API with Vitest & Supertest

Testing a validated endpoint

Testing the full lifecycle

📝 Testing with Vitest & Supertest Quiz