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.

Open in Test Case Prompt Generator

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.

How to use this resource

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

FAQ

Why does this prompt insist 401 and 403 be separate tests instead of one auth check?

They assert different behavior, so the prompt writes one test each: 401 covers missing, expired, or malformed credentials, while 403 covers a valid caller whose role is forbidden. Merging them hides the case where a wrong-permission request leaks whether the resource even exists, and a single failure message would no longer tell you which auth rule broke.

How do I make the generated tests catch a 400 that comes back as a 500?

The FAILURE SCENARIOS block already targets this: 'Invalid payloads return 400 with the documented error shape — not 500,' so a swallowed 500 fails the test instead of passing quietly. Paste the endpoint into CODE CONTEXT with its documented error body, and the generated tests assert both the status code and that error shape.

How does the idempotency scenario in this prompt actually get tested?

The FAILURE SCENARIOS marker 'a duplicate of a completed request behaves as specified' becomes at least one test, but 'as specified' is only as good as what you supply. Define your endpoint's idempotency contract in CODE CONTEXT — same response, no second charge, a 409, whatever applies — and the prompt writes the repeat-request assertion around it.

Do the generated API tests prove my endpoint's contract is correct once they pass?

Not on their own. This resource produces a test-writing prompt via the Test Case Prompt Generator; you run it in ChatGPT, Claude, or Gemini to get a runnable test file, then run that file in CI. Passing tests confirm only the assertions they hold — check the prompt's ASSUMPTIONS and GAPS output for unspecified behavior it flagged rather than covered.

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

Copy it as-is, or use Open in Test Case Prompt Generator to load it pre-filled and customize it with your own context.

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.

More resources from Test Case Prompt Generator

Resource

Playwright Test Prompt

getByRole over CSS chains, auto-wait over sleep, web-first assertions — Playwright tests written the way Playwright wants.

Engineering

Resource

Unit Test Prompt — Isolation Done Right

Mock the dependencies, test the business logic, one behavior per test — the unit testing contract that bans plumbing tests.

Engineering

Resource

Agent Safety & Refusal Evaluation Prompt

Test the two failure directions — does the agent refuse what it must, and does it stay helpful on the benign requests it shouldn't over-refuse?

AI Agents

Resources that pair well

Resource

Code Review Prompt — the Review Contract

"Review this code" gets shallow comments. The review contract gets findings with severities, a checklist, and a verdict.

Prompt Engineering

Resource

Debugging Prompt — the Investigation Contract

"Fix this error" gets guesses. The investigation contract gets a ten-stage diagnosis: facts separated from assumptions, alternatives weighed, fixes justified.

Prompt Engineering

Resource

Fix Invalid JSON from AI

The JSON won't parse and you can't see why. Deterministic cause-sniffing — trailing commas, single quotes, unclosed brackets — and the repair prompt that fixes it.

Engineering

Related tools

Tool

Test Case Prompt Generator

Build test generation prompts — unit, integration, or E2E — with framework modes and edge-case coverage rules.

Coding Workflows

Guides for this resource

Guide

How to Review an API Design With AI Before You Ship It

Code you can refactor on a quiet afternoon. A field you shipped is somebody else's dependency — you don't fix it, you version it. What an hour of contract review buys: method semantics, a truthful error model, retries, authorization, and compatibility you didn't mean to promise.

Software Development with AI

Tip: Save time by exploring related resources and tools that integrate with this resource.