API Testing

API Testing

Critical

These rules are non-negotiable. Violating any of them breaks the scaffold's contract.

• NEVER hardcode API URLs, access tokens, emails, passwords, or endpoint paths. The only allowed sources of truth are process.env.* (for URLs and credentials) and the enums/{area}/* enums (for endpoint paths, e.g. ApiEndpoints.LOGIN).
• ALWAYS validate API response bodies with Zod using the exact assertion pattern expect(SchemaName.parse(body)).toBeTruthy();. Type generics alone are not enough, and schema.parse(body) without the expect(...).toBeTruthy() wrapper is not enough.
• ALWAYS wrap each API call in test.step() when a test contains more than one API call.
• NEVER silently drop a test because the API misbehaves. Write the test as the spec says, wrap it in test.skip, and add a // FIXME: <ticket-url> comment.
• NEVER stop at {} empty-body validation. Every request-body endpoint requires per-field omission and per-field invalid-type tests.
• ALWAYS fuzz path parameters with the invalid-format data-driven loop — regardless of whether OpenAPI mentions it.
• ALWAYS use the apiRequest fixture directly in tests. Only promote to a helper fixture when the same setup/teardown is reused across 3+ test files.

Instructions

Phase 1: Source the contract (documentation first, exploration only as fallback)

The API contract — not observed behavior — is the source of truth for schemas and tests.

1. If OpenAPI / Swagger / equivalent documentation exists (the normal case):

   • Build schemas and tests strictly from the documented contract: field names, types, required vs optional, nullability, status codes, error shapes.
   • Do NOT curl the endpoint first to "see what it returns" and then write schemas that match reality.
   • If, during test execution, the actual response disagrees with the documentation (missing field, wrong type, wrong status code, extra field), that is a bug to report, not a reason to loosen the schema. Handle it via Phase 7 (test.skip + // FIXME: <ticket-url>).

2. Only if no documentation is provided (legacy endpoint, undocumented service, etc.):

   • Make a real request to discover actual response structure, field names, data types, optional vs required fields, nested objects/arrays, and error response formats.
   • Capture the findings and treat them as the working contract for this skill's remaining phases.
   • Flag the missing documentation back to the team — running tests against "whatever the API currently does" is a stopgap, not a target state.

Phase 2: Define the Zod schema and TypeScript type

Schemas live under fixtures/api/schemas/.

{area} is a placeholder. Run ls fixtures/api/schemas/ to discover the real subdirectory names in this repo (e.g., front-office, back-office) and use those instead.

fixtures/api/schemas/
├── {area}/         ← App-specific response/request schemas
│   └── userSchema.ts
└── util/           ← Shared error response schemas
    └── errorResponseSchema.ts

Build the schema directly from the OpenAPI / Swagger contract — including the response envelope (success / message / data / errors or whatever the spec describes). Spell every field out per endpoint; do not invent a factory helper. If the same envelope repeats across many endpoints in one domain, extract a per-domain _envelope.ts (z.strictObject) and compose via .extend(...) — only after the repetition is real:

// fixtures/api/schemas/{area}/productSchema.ts
import { z } from 'zod/v4';
import type { output as zOutput } from 'zod/v4';

export const ProductSchema = z.strictObject({
    id: z.uuid(),
    name: z.string().min(1),
    price: z.number().positive(),
    category: z.enum(['electronics', 'clothing', 'food']),
    inStock: z.boolean(),
});

// Response envelope is spelled out per the OpenAPI contract -- 1:1 mirror.
export const CreateProductResponseSchema = z.strictObject({
    success: z.boolean(),
    message: z.string(),
    data: ProductSchema,
    errors: z.unknown().nullable(),
});

export type Product = zOutput<typeof ProductSchema>;
export type CreateProductResponse = zOutput<typeof CreateProductResponseSchema>;

Error response schemas already exist in fixtures/api/schemas/util/errorResponseSchema.ts:

• BadRequestResponseSchema (400)
• UnauthorizedResponseSchema (401)
• ForbiddenResponseSchema (403)
• NotFoundResponseSchema (404)

import {
    UnauthorizedResponse,
    UnauthorizedResponseSchema,
} from '../../../fixtures/api/schemas/util/errorResponseSchema';

const { status, body } = await apiRequest<UnauthorizedResponse>({
    method: 'POST',
    url: '/api/login',
    baseUrl: process.env.API_URL,
    body: { email: 'bad@email.com', password: 'wrong' },
});

expect(status).toBe(401);
expect(UnauthorizedResponseSchema.parse(body)).toBeTruthy();

For 401 and 403 responses that return a null body, assert expect(body).toBeNull() directly — no schema needed.

Phase 3: Write the test using the apiRequest fixture

Use the apiRequest fixture for all API calls in tests. It provides type-safe requests with automatic response parsing via Playwright's dependency injection:

import { expect, test } from '../../../fixtures/pom/test-options';
import {
    UserResponse,
    UserResponseSchema,
} from '../../../fixtures/api/schemas/app/userSchema';

test('should return user data', { tag: '@api' }, async ({ apiRequest }) => {
    const { status, body } = await apiRequest<UserResponse>({
        method: 'GET',
        url: '/api/users/me',
        baseUrl: process.env.API_URL,
        headers: process.env.ACCESS_TOKEN,
    });

    expect(status).toBe(200);
    expect(UserResponseSchema.parse(body)).toBeTruthy();
});

Use the apiRequest fixture directly for all API work in tests — assertions, setup calls in beforeEach, teardown calls in afterEach, and one-off requests. Do not create a separate helper fixture for every endpoint.

Request parameters:

Response validation — combine compile-time and runtime safety:

const { status, body } = await apiRequest<UserResponse>({ ... });

expect(UserResponseSchema.parse(body)).toBeTruthy();

The generic <UserResponse> gives you compile-time type safety on body, while UserResponseSchema.parse() gives you runtime validation. Always use both.

Credentials and URLs — pull from env, never inline:

// CORRECT
baseUrl: process.env.API_URL,
headers: process.env.ACCESS_TOKEN,
body: { email: process.env.APP_EMAIL, password: process.env.APP_PASSWORD },

// FORBIDDEN
baseUrl: 'https://api.example.com',
headers: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',

Use enums for endpoint paths:

import { ApiEndpoints } from '../../../enums/app/app';

url: ApiEndpoints.LOGIN,

Phase 4: Wrap multi-call tests in test.step

MANDATORY: When a test contains more than one API call, each call MUST be wrapped in a dedicated test.step() with:

1. A descriptive name indicating the API operation
2. Proper validation based on the context (status code, schema, specific fields)

This improves:

• Readability — Clear flow of API operations
• Reporting — Detailed step-by-step execution traces
• Debugging — Pinpoint which API call failed

Correct pattern:

test(
    'should create and verify user workflow',
    { tag: '@api' },
    async ({ apiRequest }) => {
        const userData = generateUser();
        let userId: string;

        await test.step('Create user via POST /api/users', async () => {
            const { status, body } = await apiRequest<UserResponse>({
                method: 'POST',
                url: '/api/users',
                baseUrl: process.env.API_URL,
                headers: process.env.ACCESS_TOKEN,
                body: userData,
            });

            expect(status).toBe(201);
            expect(UserResponseSchema.parse(body)).toBeTruthy();
            userId = body.id;
        });

        await test.step('Retrieve user via GET /api/users/:id', async () => {
            const { status, body } = await apiRequest<UserResponse>({
                method: 'GET',
                url: `/api/users/${userId}`,
                baseUrl: process.env.API_URL,
                headers: process.env.ACCESS_TOKEN,
            });

            expect(status).toBe(200);
            expect(UserResponseSchema.parse(body)).toBeTruthy();
            expect(body.id).toBe(userId);
            expect(body.email).toBe(userData.email);
        });

        await test.step('Delete user via DELETE /api/users/:id', async () => {
            const { status, body } = await apiRequest<null>({
                method: 'DELETE',
                url: `/api/users/${userId}`,
                baseUrl: process.env.API_URL,
                headers: process.env.ACCESS_TOKEN,
            });

            expect(status).toBe(204);
            expect(body).toBeNull();
        });
    }
);

Forbidden pattern: multiple API calls inside a single test body without test.step wrappers — the trace shows one big test, debugging which call failed requires reading the assertions, and reporting can't surface create-vs-get-vs-delete structure. For the full anti-pattern code block see references/test-step-patterns.md.

Single API call exception: If a test contains only one API call, test.step is optional but recommended for consistency.

Phase 5: Cover the full status-code matrix

For every endpoint × HTTP method combination, tests MUST cover every status code listed in the OpenAPI spec plus the baseline scenarios below. If the OpenAPI spec lists a status code not in this table, it still requires a test.

Structure: One test.describe per HTTP method + path. Use beforeAll/afterAll (not beforeEach/afterEach) to create/delete shared resources needed by multiple tests in the same describe block.

Key conventions from real tests:

• Auth tokens: process.env.ACCESS_TOKEN (full permissions), process.env.ACCESS_TOKEN_ZERO (zero permissions)
• Config: process.env.API_URL + /api/X — never bare process.env.API_URL
• Cleanup: afterAll in POST describes (holds resourceId from the happy-path test); afterAll in GET/PUT/DELETE describes (resource created in beforeAll)
• When a test.skip is needed due to a backend bug: add // FIXME: <ticket-url> comment + /* eslint-disable playwright/no-skipped-test */ above it
• Tag: @api for API tests (check real tag in existing spec files for other areas)