API Testing

// TypeScript, supertest. In-process: no port, no deployment, ~10ms.
import request from 'supertest';
import { app } from '../src/app';

describe('POST /orders', () => {
  it('creates an order and returns its location', async () => {
    const response = await request(app)
      .post('/orders')
      .set('Idempotency-Key', 'ORD-test-1')
      .send({ sku: 'book-1', quantity: 2 })
      .expect(201)
      .expect('Content-Type', /json/);

    expect(response.headers.location).toMatch(/^\/orders\/[0-9a-f-]{36}$/);

    // Read it back through the API, not the database: the test then
    // describes the contract rather than the schema.
    await request(app).get(response.headers.location).expect(200).expect(({ body }) => {
      expect(body).toMatchObject({ sku: 'book-1', quantity: 2, status: 'reserved' });
    });
  });

  it('is idempotent: the same key returns the same order', async () => {
    const key = 'ORD-test-2';
    const first = await request(app).post('/orders').set('Idempotency-Key', key)
      .send({ sku: 'book-1', quantity: 1 }).expect(201);
    const second = await request(app).post('/orders').set('Idempotency-Key', key)
      .send({ sku: 'book-1', quantity: 1 }).expect(200);

    expect(second.headers.location).toBe(first.headers.location);
  });

  it('rejects an unknown sku with a useful error', async () => {
    await request(app).post('/orders').send({ sku: 'nope', quantity: 1 })
      .expect(422)
      .expect(({ body }) => {
        expect(body).toMatchObject({ error: 'unknown_sku', field: 'sku' });
      });
  });
});

// Java, RestAssured against a running service
@Test
void rejectsAnOrderForAnUnknownSku() {
    given()
        .contentType(ContentType.JSON)
        .body(Map.of("sku", "nope", "quantity", 1))
    .when()
        .post("/orders")
    .then()
        .statusCode(422)
        .body("error", equalTo("unknown_sku"))
        .body("field", equalTo("sku"));
}

# Python, httpx + FastAPI's TestClient
def test_pagination_is_stable_across_pages(client, seeded_orders):
    first = client.get("/orders?limit=2").json()
    second = client.get(f"/orders?limit=2&cursor={first['next']}").json()

    assert len(first["items"]) == 2
    assert {o["id"] for o in first["items"]} & {o["id"] for o in second["items"]} == set()

it.each([
  ['owner', 200],
  ['other-tenant', 404],   // 404, not 403: do not confirm the resource exists
  ['anonymous', 401]
])('GET /orders/:id as %s returns %i', async (who, expected) => {
  await request(app).get(`/orders/${order.id}`).set(authFor(who)).expect(expected);
});

import Ajv from 'ajv';
import openapi from '../openapi.json';

const ajv = new Ajv({ strict: false });
const validateOrder = ajv.compile(openapi.components.schemas.Order);

it('returns a body matching the published Order schema', async () => {
  const { body } = await request(app).get(`/orders/${order.id}`).expect(200);

  expect(validateOrder(body)).toBe(true);
  expect(validateOrder.errors).toBeNull();
});

it('publishes OrderPlaced with the fields consumers rely on', async () => {
  await placeOrder({ sku: 'book-1', quantity: 2 });

  const [message] = await broker.drain('orders');

  expect(JSON.parse(message.body)).toMatchObject({
    type: 'OrderPlaced',
    version: 1,
    orderId: expect.any(String),
    sku: 'book-1'
  });
});