Testing an API: Unit, Integration and Contract

On the frontend you know the rule "test what the user sees." The backend version is "test what the API promises." That means status codes, response bodies, changes in the database, and the rules behind them. This lesson gives you a plan you can explain in an interview, and examples you can copy.

Words used in this lesson

• Test is a small program that runs your code and checks that the result is what you expect. If the result is different, the test fails.
• Unit test checks one small piece (a function) alone. Integration test checks several real pieces working together. Contract test checks that two sides agree on the shape of the data. End-to-end (E2E) test uses the whole running system like a real user. Difference in one line: the more pieces a test includes, the slower it is, but the more real problems it finds.
• Mock is a stand-in object that replaces a real part and records how it was called, so the test can check the calls. Fake is a simple working stand-in (for example a database kept in memory). Spy wraps a real function and records its calls.
• Assertion is one check inside a test, such as expect(x).toBe(5).
• Vitest is a test runner (a tool that finds and runs tests). Supertest is a library that sends HTTP requests to your app inside a test.
• Docker is a tool that runs programs in isolated containers. CI (continuous integration) is a server that runs your tests automatically on every change.
• Pure function is a function that gives the same output for the same input and changes nothing outside itself.

What to test, and at what level

The usual shape is a test pyramid: many unit tests for logic, a thick layer of integration tests for endpoints, and a few end-to-end tests. Some teams prefer a "trophy" shape. That means more integration tests than unit tests, instead of a strict pyramid. For CRUD-style backends (create, read, update, delete) this is usually right. Most bugs live in the seams, the places where parts connect. They do not live inside single functions.

Why can you not rely only on unit tests with a mocked database? The test can pass while the real SQL fails because of a missing column, a constraint, or how a transaction behaves. The mock simply does what you told it to do. Your assumptions are the thing that might be wrong.

Unit tests: pure logic

Clean code puts rules into pure functions. A pure function gives the same output for the same input and changes nothing outside itself. These are very easy to test:

import { describe, it, expect } from "vitest";import { calculateDiscount } from "./pricing";describe("calculateDiscount", () => {  it.each([    [{ subtotal: 10_000, itemCount: 1 }, { tier: "gold" }, 1_000],   // gold = 10%    [{ subtotal: 10_000, itemCount: 10 }, { tier: "free" }, 500],    // bulk = 5%    [{ subtotal: 10_000, itemCount: 2 }, { tier: "free" }, 0],    [{ subtotal: 0, itemCount: 0 }, { tier: "gold" }, 0],            // edge case  ])("order %j, customer %j → %i", (order, customer, expected) => {    expect(calculateDiscount(order, customer)).toBe(expected);  });});

A good unit test has these traits:

• no network
• no database
• no real clock (pass the clock in)
• no randomness
• checks of outputs, not of which inner helper was called

Integration tests: through HTTP, against a real database

Use Supertest (or fetch against buildApp(); see Lesson 01) with a real PostgreSQL, usually in Docker. TRUNCATE is the SQL command that deletes all rows of a table quickly.

import request from "supertest";import { afterAll, beforeEach, describe, it, expect } from "vitest";import { buildApp } from "../src/app";import { prisma } from "../src/lib/prisma";import { createUser, createOrderFor, authFor } from "./helpers";const app = buildApp();beforeEach(async () => {  // Reset state so tests are independent  await prisma.$executeRaw`TRUNCATE TABLE "OrderItem", "Order", "User" RESTART IDENTITY CASCADE`;});afterAll(() => prisma.$disconnect());describe("POST /v1/orders", () => {  it("creates an order and returns 201 with Location", async () => {    const user = await createUser();    const res = await request(app)      .post("/v1/orders")      .set(authFor(user))      .send({ items: [{ sku: "SKU-1", qty: 2 }] });    expect(res.status).toBe(201);    expect(res.headers.location).toMatch(/\/v1\/orders\/.+/);    expect(res.body).toMatchObject({ status: "pending", userId: user.id });    const saved = await prisma.order.findUnique({ where: { id: res.body.id }, include: { items: true } });    expect(saved?.items).toHaveLength(1);                         // verify the side effect, not just the response  });  it("rejects an empty cart with 422 and field errors", async () => {    const res = await request(app).post("/v1/orders").set(authFor(await createUser())).send({ items: [] });    expect(res.status).toBe(422);    expect(res.body.errors[0].path).toContain("items");  });  it("returns 401 without credentials", async () => {    expect((await request(app).post("/v1/orders").send({})).status).toBe(401);  });  it("does not let user B read user A's order", async () => {    const [a, b] = [await createUser(), await createUser()];    const order = await createOrderFor(a);    const res = await request(app).get(`/v1/orders/${order.id}`).set(authFor(b));    expect(res.status).toBe(404);                                 // 404, not 403: do not reveal that the order exists  });});

Make the database part easy

• Run a real PostgreSQL in Docker. Use docker compose in CI and on your machine. Or use Testcontainers, a library that starts a throwaway container from the test code and removes it afterwards.
• Apply the real migrations (prisma migrate deploy, which runs saved database changes) to the test database. Then the schema looks like production.
• Keep tests independent. Test files run in parallel by default in Vitest. If they all share one database, a TRUNCATE in one file wipes the data of another. You have three options:
  • Truncate (empty) the tables between tests. This is simple but a little slower.
  • Wrap each test in a transaction that rolls back. This is fast, but harder if your code also uses transactions.
  • Give each test file its own schema or database, so files can run in parallel.
• Use factories or builders (small helper functions that create test data, such as createUser() and createOrderFor(user)). Then setup is short and easy to read.
• Keep tests deterministic. Deterministic means the same result every time. Control time (vi.useFakeTimers() or a clock you pass in), randomness and ID generation.

Test the unhappy paths

The unhappy path is what happens when things go wrong. For each endpoint, test these cases:

• validation failures
• not logged in (unauthenticated: the server does not know who you are, status 401)
• not allowed (unauthorized or forbidden: the server knows you, but you may not do this, for example another user's data, or a lower role)
• not found
• conflicts (duplicates, or editing an old version of a record)
• idempotent retries (sending the same request again gives the same result)
• dependency failures, such as a payment provider that is down

Error handling is behaviour, so it needs tests too (Lesson 04).

What to mock (and what not)

If you mock too much, your tests only check the mocks. Here is a warning sign: you must change tests every time you refactor, even though the behaviour did not change.

Fakes, mocks and spies:

• A fake is a simple working version, such as a repository that keeps data in memory.
• A mock checks how it was called.
• A spy wraps a real function so you can watch it.

Prefer fakes. Prefer checks on results over checks on how something was called.

// A fake payment gateway implementing the same interface (injected, see Lesson 00).// It keeps charges in memory and can be told to fail.class FakeGateway implements PaymentGateway {  charges: { orderId: string; amount: number }[] = [];  shouldFail = false;  async charge(orderId: string, amount: number) {    if (this.shouldFail) throw new PaymentUnavailableError();    this.charges.push({ orderId, amount });    return { id: "ch_fake" };  }}

Contract tests

Scenario: the backend renames total to totalAmount. The backend unit and integration tests still pass, because someone updated them. The frontend still reads total, so it breaks in production. Which test was missing? A contract test. It is an automatic check that the shape both sides rely on has not changed.

Approaches:

1. A shared schema package in a monorepo (one repository holding several projects; Lesson 03). The frontend and backend import the same Zod schemas (Zod is a library that describes and checks the shape of data) and types. So a rename causes a compile error on both sides. The API test also checks that responses match the schema (orderResponseSchema.parse(res.body)).
2. OpenAPI as the contract. OpenAPI is a standard file that describes every endpoint of a REST API. Generate types and clients from it. In CI, run a breaking-change detector (oasdiff, openapi-diff) on pull requests. In tests, check real responses against the spec.
3. Consumer-driven contracts (Pact). Pact is a tool for this. The consumer (frontend) records the requests it makes and the responses it needs. The provider (API) checks in its own CI that it can meet them. This is good when you have many independent consumers.
4. A snapshot of the API schema (a saved copy of the schema; for GraphQL, a registry compares each change to it). CI fails when a change is breaking.

Also protect your database migrations. Test that the migration works on a copy of production-like data. Use backward-compatible (expand/contract) changes, so old and new code can work together during a rolling deployment (servers are replaced one by one) (Lesson 08).

Other kinds of testing worth knowing

• Load or performance tests (k6 and autocannon send many requests at once) in CI or staging for important endpoints. Set limits on p95 and p99 (the time that 95 or 99 out of 100 requests beat).
• Security tests. Test who can do what (an authorization matrix), audit your dependencies, and run an automatic scan from time to time. Add a regression test (a test that stops an old bug from coming back) for every security bug.
• Concurrency tests. Send parallel requests to endpoints like "buy the last item" or "use a coupon once". Check that the rule still holds (Lesson 07).
• Property-based tests (a tool such as fast-check) for parsers, serialisers and money math. Instead of fixed examples, you state a rule that must always be true, and the tool tries many random inputs.
• Mutation testing (a tool such as Stryker). The tool changes your code on purpose and checks whether your tests fail. This is a better signal than a coverage percentage.

Practices that keep a test suite healthy

• Fast feedback. Unit tests should take seconds. Integration tests should take a minute or two. Run them on every pull request in CI, and run them in parallel.
• One reason to fail. Each test checks one behaviour. Its name says what it checks ("returns 404 when the order belongs to another user").
• Use Arrange, Act, Assert. First set up, then do the action, then check the result. Do not put logic (loops, if) in tests.
• No shared changing state between tests. Tests must not depend on the order they run in.
• Flaky tests are bugs. A flaky test sometimes passes and sometimes fails for no clear reason. Move it aside and fix it. Do not ignore a red CI.
• Coverage is a smoke detector, not a goal. Coverage is the share of your code lines that ran during tests. 80% coverage with strong assertions is better than 100% of lines that only run code.
• Tests are code. Refactor them and keep the helpers tidy.

Common mistakes

1. Mocking the database in tests that should prove the endpoint works.
2. Testing inner details (which function was called) instead of results.
3. Only testing the happy path.
4. Shared test data that depends on order. It causes flaky failures.
5. Slow suites that developers stop running.
6. No contract protection between frontend and backend.
7. Chasing a coverage number with tests that have no assertions.
8. Real third-party calls in tests. They are flaky, they cost money, and they are unsafe.

Interview questions

Key takeaways

• Unit test pure logic. Integration test endpoints through HTTP with a real database. Contract test the agreement between frontend and backend. Keep E2E tests for the most important flows.
• Mock the edges, not your own code. Prefer fakes and checks on results.
• Cover unhappy paths (validation, auth, other users, conflicts, dependency failures) and concurrency rules.
• Keep tests independent, deterministic and fast. Treat flakiness as a bug.
• Protect against schema drift with shared schemas or OpenAPI breaking-change checks. Use backward-compatible migrations.

What's next

That completes Backend in Depth. Continue with Scenario Debugging to use this knowledge in "it's slow, fix it" interviews. Or try Practical Design Problems for the URL shortener, the rate limiter and the pagination designs.