Engineering

API Test Prompt — the Contract Is the Subject

Status codes, response shapes, 401 vs 403, idempotency — API tests that test the contract, not the implementation.

Overview

API tests that only check 200-and-some-JSON miss what APIs break: the 400 that comes back as a 500, the 401/403 confusion that leaks resource existence, the error body whose shape nobody asserted. This setup generates the API contract test suite: every response asserting status code, body shape, and meaningful headers; auth as behavior (missing credentials → 401, wrong permissions → 403 — different tests); error responses held to their contract as strictly as success; idempotency of repeated requests; and payload limits enforced at the documented boundary.

Workflow

Test the contract, not the code
Request in, response out — the suite holds the documented behavior, whatever the implementation does inside.
Separate the auth tests
401 for who-are-you, 403 for you-can't — one test each, never merged.
Repeat the dangerous requests
The idempotency scenario: send the completed request again and assert the documented behavior, not luck.

Why This Works

Contract framing tests what consumers depend on instead of implementation details
The 401/403 distinction encodes the auth correctness most suites blur
Error-shape assertions protect the clients that parse failures programmatically

Best for

Public and partner-facing endpoints
APIs whose error contract is part of the product
Teams that learned the 401-vs-403 lesson in production

Not for

Writing the API documentation — that's the Markdown Output Builder
Defining the response format itself — that's the JSON Output Prompt Builder

Use cases

Testing REST endpoints before they go public
Catching the invalid payload that 500s instead of 400s
Asserting error response shapes that clients parse

Customize This Resource

Opens this setup in Test Case Prompt Generator. Generate to get the full test contract — then adjust the strategy, framework, coverage, and depth.

Open in Test Case Prompt Generator

Prompt Template

TESTING OBJECTIVE
Generate tests for the orders REST endpoint before it goes public.
Strategy: API tests — the contract is the subject: requests, responses, status codes, auth.
Generate tests only — do not modify the implementation.

CODE CONTEXT
[Paste the endpoint under test here]

TEST STRATEGY
- Test the contract, not the implementation: request validation, response shape, and status codes are the spec.
- Every response asserts three things: status code, body shape, and the headers that matter.
- Auth is tested as behavior: 401 for missing/expired credentials, 403 for valid-but-forbidden — and they are different tests.
- Error responses have a contract too — assert their shape as strictly as the success path.

COVERAGE AREAS
Happy Path:
- The primary success path with realistic, typical inputs
- The most common variations users actually exercise
- Expected outputs asserted precisely — values and shape, not just "no exception"
Error Handling:
- Every declared error path actually triggers in a test
- Errors carry the right type, message, and code
- Failures leave state clean — no partial writes survive
- Errors propagate or are swallowed exactly as specified
Validation:
- Required fields missing — one at a time, each with its own test
- Invalid formats: emails, dates, IDs, and the patterns the code claims to enforce
- Invalid state transitions rejected with the specified behavior
- Business rule violations tested at their exact boundaries
Security:
- Authentication failures: missing, expired, and malformed credentials
- Permission boundaries: the right operations return 403 for the wrong roles
- Malicious input: injection attempts in every text field
- Access to other users' resources by ID is rejected

FAILURE SCENARIOS
Each of these gets at least one test:
- Invalid payloads return 400 with the documented error shape — not 500
- Missing or expired auth returns 401; wrong permissions return 403
- Nonexistent resources return 404, not 500 or an empty 200
- A duplicate of a completed request behaves as specified (idempotency)
- Oversized payloads are rejected at the documented limit

TEST DATA GUIDANCE
- Use realistic, production-shaped data — names, amounts, and dates that could exist.
- Build complex objects with builders or factories, not hand-assembled literals repeated per test.
- Name boundary data for its intent (maxLengthName, expiredToken), not its value.
- Never share mutable fixtures between tests.

FRAMEWORK GUIDANCE
Framework: Generic.
- Use the project's existing test framework and follow its established conventions.

OUTPUT FORMAT
- Return one complete, runnable test file.
- Group tests by coverage area, with a comment header per group.
- Each test: arrange-act-assert structure, one behavior per test.
- Cover every selected coverage area systematically — each coverage item above gets at least one test.
- Parametrize repetitive cases instead of copy-pasting tests.
- Name tests so a failure message alone identifies the broken behavior.

ASSUMPTIONS
- After the tests, list every assumption you made about unspecified behavior under an ASSUMPTIONS heading.
- Where the code's intent is ambiguous, test the most likely intent and flag the ambiguity.
- List GAPS: behaviors you could not test with the information given.

NON-GOALS
- Do not rewrite or "improve" the implementation code — test it as it is.
- Do not refactor the architecture to make it more testable; flag testability problems instead.
- Do not invent requirements — test only specified or clearly implied behavior.
- Do not weaken assertions to make tests pass.

Related Resources

Explore more resources that work well with this one.