These are notes from one project, not a general guide. I wrote 47 API tests with Playwright and
TypeScript against RESTful Booker,
a public API built for practising API testing. It is an independent project, not client or employer work,
and a practice API has no real users, roles or money, so none of this shows how I would test a
production system. What it does show is how I structure checks, and a few decisions I would
now make differently. All code below is from commit
a385240
of the public repository.
What the suite checks
| Spec | Tests | Covers |
|---|---|---|
| auth | 5 | Token creation, bad and empty credentials |
| booking-create | 7 | Create, response shape, optional fields |
| booking-read | 6 | Get one, list, required fields, dates |
| booking-update | 6 | Full update, with and without a token |
| booking-partial-update | 5 | PATCH behaviour |
| booking-delete | 6 | Delete, missing and invalid token, verify gone |
| health-check | 1 | Service reachable |
| negative-testing | 8 | Invalid input, bad IDs, odd payloads |
| workflow | 3 | Multi-step lifecycles |
1. Assert what the API actually does, and write down where it surprises you
I expected a failed login to return 401. RESTful Booker returns 200 with a body that carries a
reason instead. The test asserts that real behaviour, and its name says so:
test('POST /auth with invalid credentials should return 200 but no token', async () => {
const response = await authClient.createTokenResponse('invalid_user', 'wrong_password');
expect(response.status()).toBe(200);
const body = await response.json();
expect(body).toHaveProperty('reason');
expect(body.reason).toMatch(/Unauthorized|Bad credentials/i);
});
On a team I would not leave this as a passing test and move on. A 200 for failed authentication is something to raise with whoever owns the API, because clients that only check the status code will treat a failed login as a success. Here it is a practice API I do not control, so the test records the behaviour and the name makes the surprise visible.
2. Make every test create its own data
Each spec creates the booking it needs in a beforeEach or inside the test, and gets a
fresh token, so no test depends on another test having run and the order does not matter:
test.beforeEach(async ({ request }) => {
bookingClient = new BookingClient(request, config.baseURL);
authClient = new AuthClient(request, config.baseURL);
token = await authClient.createToken(config.auth.username, config.auth.password);
});
test('DELETE /booking/{id} without token should return 403', async () => {
const createResponse = await bookingClient.createBooking(validBooking);
const bookingId = createResponse.bookingid;
const response = await bookingClient.deleteBookingResponse(bookingId, '');
expect(response.status()).toBe(403);
});
tests/api/booking-delete.spec.ts (excerpt)
The trade-off I did not handle: only the delete and lifecycle tests remove what they create. Every
other test leaves its booking behind on a shared public server, and the fixtures reuse the same names
(John Smith), so a test cannot find its booking by name. It finds it by the returned
bookingid. Cleanup in an afterEach is the first thing I would add.
3. Keep a way to see the status code
The API client has two kinds of method. The convenient ones return the parsed body. The
...Response variants return the raw response so a test can assert on status and headers:
async get<T>(endpoint: string, token?: string): Promise<T> {
const headers = this.getHeaders(token);
const response = await this.request.get(`${this.baseURL}${endpoint}`, { headers });
return response.json();
}
async getResponse(endpoint: string, token?: string): Promise<APIResponse> {
const headers = this.getHeaders(token);
return this.request.get(`${this.baseURL}${endpoint}`, { headers });
}
src/api/clients/api-client.ts (excerpt)
That split keeps happy-path tests short, but it has a weakness: the body-returning helpers never check
the status. If the server returned a 500 with an error body, the failure would show up later as a
confusing assertion on a missing field instead of a clear status failure. I would make those helpers
assert response.ok() before parsing.
4. Negative tests can pin behaviour you would call a bug, and some cannot fail
Several of the eight negative tests do not show the API rejecting bad input. They show it accepting it: a negative price, an invalid date string, a checkout date before the check-in date.
test('POST /booking with negative price is accepted by API', async ({ request }) => {
const bookingWithNegativePrice = {
...validBooking,
totalprice: -100,
};
const response = await bookingClient.postResponse('/booking', bookingWithNegativePrice);
expect(response.ok).toBeTruthy();
});
tests/api/negative-testing.spec.ts (excerpt)
On a real product each of these would be a defect report or a question about the requirement, not a
green test that blesses the behaviour. Reviewing this file for this article I also found a bug in my
own assertion. In Playwright, response.ok is a method, so without the call parentheses
the expression is a function and always truthy, and the check can never fail. Three tests have it
(lines 35, 48 and 61 of that file). It should be response.ok(). Those three therefore
count in the 47 test definitions but prove nothing about the API. A test that cannot fail is the first
thing I look for when I review tests, and I missed it in my own.
Only two of the eight negative tests assert a rejection: an incomplete PUT returns 400, and a non-numeric booking ID returns 404. The other six record input the API accepts (zero and negative prices, an invalid date, a checkout before the check-in, special characters in the login, a 1,000-character name). Rejection of a missing token is covered separately in the delete spec, which expects a 403.
5. After a write, read it back
A successful response to an update does not prove the data was saved. The lifecycle test reads the booking again after each change, and finishes by checking that the deleted booking now returns 404:
// Step 4: Update booking
const updatedResponse = await bookingClient.updateBooking(bookingId, updatedBooking, token);
expect(updatedResponse.firstname).toBe(updatedBooking.firstname);
// Step 5: Verify update persisted
const verifyUpdated = await bookingClient.getBooking(bookingId);
expect(verifyUpdated.firstname).toBe(updatedBooking.firstname);
expect(verifyUpdated.totalprice).toBe(updatedBooking.totalprice);
tests/api/workflow.spec.ts (excerpt)
6. CI, retries and what a green run does not prove
The Playwright configuration retries once in CI, collects a trace on the first retry, and runs with a single worker so tests do not collide on shared server state:
retries: process.env.CI ? 1 : 0,
workers: process.env.CI ? 1 : undefined,
use: {
trace: 'on-first-retry',
}
playwright.config.ts (excerpt)
The first workflow run on 10 September 2026 failed, and the next run, after a commit titled “fix: align CI Node version with Playwright”, passed. That commit message is my only evidence for the cause, because GitHub Actions logs need a sign-in to read, so treat it as the likely cause, not a documented root cause. Retries are also a reason to read a green run carefully: with one retry configured, a pass does not by itself show that no test needed it. A later run on 22 October 2026 (commit 1e7f137, which only added a manual workflow trigger) passed; by my reading of its job log, no test was retried.
What this suite does not cover
- Contract or schema validation. Response shape is checked with
toHavePropertyon a few fields, not against a schema, so an extra, renamed or wrongly typed field would go unnoticed. - Performance and load. There are no response-time assertions and no load tests.
- Authorization models. The API has one admin account and a cookie token. There are no roles, so nothing here tests who may see whose data.
- Databases and integrations. Everything goes through the public HTTP interface.
- Real systems. This is a demo service that other people also use. Results depend on its uptime and on shared data.
The API testing evidence map lists, risk by risk, which tests in this suite and in my two other public repositories cover what, and which assertions cannot fail. For the same approach applied to something with money in it, the payment gateway article covers webhooks, signatures and refunds in a Razorpay Test Mode project. The RESTful Booker case study and the Evidence Library have the reports and runs.