agentic-playwright api-testing.instructions.md

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>).