A reusable, typed API test framework built on Playwright's request API. It's the layer I'd put
between a test suite and a REST API. It has typed clients, contract checks with Zod schemas, auth
handled by fixtures, realistic test data, and cleanup that fails the test if anything is left behind.
The demo target is the public Restful-Booker API. To test your own API, set
BASE_URLand add clients and schemas.
| Pattern | Where | Why |
|---|---|---|
| Typed API clients | src/clients/ |
Endpoints live in one place; tests read like behavior, not URLs |
| Schemas as contracts | src/schemas/ |
Zod checks responses, and the TS types come from the same schema |
| Custom matcher | src/matchers/schema.ts |
await expect(res).toMatchSchema(Schema) with readable field-level errors |
| Auth fixture | src/fixtures/api.ts |
The token is fetched once per worker and passed in for you |
| Auto cleanup | BookingClient.cleanup() |
Every booking a test creates is deleted, and a leftover fails the test |
| Data factories | src/data/bookingFactory.ts |
Faker data with valid, ordered dates; override any field |
| Tags | @smoke @contract @negative |
Run focused subsets |
| Quality gates | ESLint, Prettier, tsc, CI |
Lint, format, and typecheck all gate the build |
When the API drifts from its contract, the matcher points at every broken field:
schema validation failed:
• lastname: Too small: expected string to have >=1 characters
• totalprice: Invalid input: expected number, received string
• bookingdates.checkin: expected a YYYY-MM-DD date
npm install
npm test # everything (no browser needed)
npm run test:smoke # @smoke subset
npm run test:contract # schema/contract checks
npm run test:negative # negative + access-control checks
npm run report # open the HTML reportConfigure via env vars (see .env.example): BASE_URL, API_USERNAME, API_PASSWORD.
import { test, expect } from '../src/fixtures/api.js';
import { BookingSchema } from '../src/schemas/booking.schema.js';
import { buildBooking } from '../src/data/bookingFactory.js';
test('a created booking can be read back', async ({ bookingClient }) => {
const payload = buildBooking({ firstname: 'Vincent' });
const { bookingid } = await (await bookingClient.create(payload)).json();
const res = await bookingClient.get(bookingid);
await expect(res).toMatchSchema(BookingSchema);
expect(await res.json()).toEqual(payload);
}); // the booking is deleted automatically after the testapi-testing-framework/
├── playwright.config.ts # baseURL + default headers, reporters
├── src/
│ ├── config/env.ts # env-driven config
│ ├── clients/ # BaseClient · AuthClient · BookingClient
│ ├── schemas/ # Zod contracts (+ inferred types)
│ ├── matchers/schema.ts # toMatchSchema custom matcher
│ ├── fixtures/api.ts # token (worker) · authClient · bookingClient (auto-cleanup)
│ └── data/bookingFactory.ts # faker data builder
└── tests/
├── health.spec.ts # @smoke
├── auth.spec.ts # token contract + bad/missing credentials
├── booking.crud.spec.ts # create · read · put · patch · delete
├── booking.contract.spec.ts # @contract schema checks
└── booking.negative.spec.ts # @negative 404, no-auth, invalid token, malformed input
The tests pin the demo API's actual behavior and flag where a well-behaved API would differ:
| Behavior | Actual | Expected in a real API |
|---|---|---|
GET /ping |
201 |
200 |
Bad credentials on POST /auth |
200 + reason |
401 |
Successful DELETE |
201 |
200 / 204 |
Malformed POST /booking |
500 |
400 |
.github/workflows/ci.yml runs lint · format · typecheck first and
starts the API suite only if they pass, so a broken build never hits the live API. It runs on every
push/PR, plus a weekly scheduled run against the live API to catch contract drift even when the
code hasn't changed.
toMatchSchema takes the APIResponse rather than the parsed body on purpose: Playwright drops custom
matchers from the typings when the received value is any, and res.json() returns any. Passing the
typed response keeps assertions type-safe. The typecheck gate caught this during development.