# API-first testing

Use this reference when source exposes HTTP routes, an OpenAPI/Swagger document is present, a user supplies an authorized HAR, or UI failures may originate in a service contract.

## Learn contracts and traffic locally

Prefer OpenAPI JSON or YAML for declared operations, request fields, response statuses, security, boundaries, and idempotency extensions. An authorized redacted HAR can reveal observed methods, paths, statuses, timing, and UI page origins. Treat traffic as observation, not a complete specification.

Never retain authorization headers, cookies, tokens, passwords, private payload values, or unrelated user traffic. Keep schema and HAR processing local by default. Ask before installing an optional YAML parser; JSON works without an added dependency.

## Candidate families per operation

Generate and then tailor:

- **positive:** documented success status/schema plus persisted and user-visible effect;
- **negative:** missing required fields, wrong types/formats, unknown fields, malformed encodings, and stable error envelopes without partial effects;
- **boundary:** null versus absent, empty, min/max neighbors, representation size, Unicode, pagination, timestamps, and numeric precision;
- **authentication and authorization:** signed out, expired, wrong role, wrong owner, and cross-tenant denial without existence or timing leaks;
- **idempotency:** duplicate delivery and ambiguous-timeout retry for state-changing operations, verifying business effect, events, notifications, and audit records;
- **resilience:** timeout, response loss, 429, dependency 5xx, retry budget, cancellation, cleanup, and truthful terminal state.

Mutating, fault-injection, high-volume, cross-role, payment, notification, and shared-environment variants remain planned until the user supplies safe identities/data, authorization, load bounds, and recovery.

## Connect API evidence to UI flows

When a HAR page origin or `x-carbon-ui-flows` link connects an operation to a flow, validate both directions:

1. UI action emits the expected request exactly once with the intended identity and payload.
2. API response and persistence appear truthfully in the UI.
3. API validation/auth/failure states recover in the UI without stale success, duplicate action, lost input, or misleading retry.
4. Direct API mutation, where authorized, is reflected after refresh/reload and does not bypass UI-enforced policy.

Store the shared `apiOperation` and `flowIds` on candidate tests so an API failure can select the smallest adjacent UI regression set.

## Execution and evidence

Use isolated direct HTTP checks, not the user’s live browser session, for contract-level probes. Record environment, build/revision, synthetic fixture identity, request template without secrets, response status/schema, persisted effect, linked UI evidence, timing where relevant, and cleanup. A generated case is not a pass, and a schema match alone is not a complete product oracle.
