An Integration Test Generation Prompt Built From Your API Contract

Ask a model to write integration tests for an API with nothing but a one-line description and you get a handful of happy-path calls that pass on day one and catch nothing on day ninety. The cases that matter, the malformed payload, the missing auth header, the off-by-one page size, never show up unless you ask for them by name.

An integration test generation prompt fixes that by starting from the API contract instead of a vague request. Endpoints, request schemas, response schemas, error codes. From there it derives a case matrix: happy path, negative, boundary, per endpoint, in a locked output shape. That's the difference between tests that document the API and tests that defend it.

Here's the prompt and the contract-first workflow.

Why "write integration tests" misses the cases that break in production

The popular e2e prompts skip the contract entirely. The widely shared e2e test flow generation prompt walks through architecture analysis and critical user journeys, but it has no locked output structure, no API-spec input, and barely touches negative or boundary cases. QA prompt collections like DeviQA's 50 prompts stay scenario-level too, payment flows and booking journeys, not contract-derived integration coverage.

That's the gap. None of them say "here is the schema, now generate every case the schema implies." A 404 on a missing resource, a 422 on a bad field type, a 401 without a token, these are written into the contract. A prompt that reads the contract can enumerate them. A prompt that reads a feature description can't.

What you can do with this prompt

• Turn an OpenAPI spec into a per-endpoint test matrix in one pass.
• Generate negative cases (wrong type, missing required field, bad auth) the contract implies.
• Cover boundary values: empty arrays, max page size, zero-length strings.
• Produce tests in your framework, Playwright, supertest, pytest with httpx, by swapping a variable.
• Re-derive the matrix after a schema change so new fields get coverage automatically.
• Hand the same prompt to QA and to backend devs and get the same case structure.

Anatomy of the prompt

Contract first, framework second, output contract last. The case matrix is the spine.

Role:    You are a test engineer writing integration tests in {{test_framework}}.
Context: {{api_contract}} — endpoints, request/response schemas, error codes.
         {{auth_model}} — how requests authenticate.
Task:    For each endpoint, derive cases across three classes:
         - happy path (valid request, expected 2xx and body shape)
         - negative (missing field, wrong type, bad auth -> expected 4xx)
         - boundary (empty, max, zero-length, pagination edges)
Output:  A matrix — Endpoint | Case class | Input | Expected status | Assertion.
         Then a fenced block with runnable tests for each row.

Step-by-step usage

1. Gather inputs

Get the contract. An OpenAPI or GraphQL schema is ideal. No spec? Paste the route handlers or one request/response pair per endpoint and let the prompt infer the contract first.

2. Fill variables

Set {{api_contract}}, {{test_framework}}, and {{auth_model}}. The auth model matters: tests that forget the token all fail with 401 and tell you nothing.

3. Run the prompt

Run per resource group, not the whole API at once. Twelve endpoints in one prompt and the boundary cases thin out by the last few.

4. Post-process

Check the negative-case expected statuses against the real contract. Models sometimes assert 400 where your framework returns 422. Pin it to the spec.

5. Iterate

When the schema changes, paste the diff and ask only for cases touching the changed fields. Don't regenerate the stable endpoints.

Prompt-craft patterns

Give the contract, not the description. A schema beats a sentence. "The endpoint accepts a user" tells the model nothing about which fields are required. The schema does, and required-field negatives are where integration bugs hide.

For POST /orders, the request schema is:
  { "items": [{ "sku": string, "qty": int >= 1 }], "coupon": string? }
Derive a negative case for: missing items, qty = 0, qty negative,
unknown coupon, items = [].

Separate status from body assertions. Ask the matrix to assert both the status code and the response shape. A 200 with the wrong body is a bug a status-only test waves through.

State the auth model once, at the top. Then every generated test inherits it. Restate it per test and the model drifts on which header carries the token.

One more behavior worth knowing: Claude tends to keep the case matrix complete across a dozen endpoints, while GPT-4o starts dropping boundary rows toward the end of a long contract unless the output contract is restated on the final line. If you're running the prompt on a big spec, paste the matrix headers again right before the "begin" instruction. It costs a few tokens and it keeps the negative cases from thinning out. Worth it.

The take worth defending: integration tests derived from a contract are more valuable than UI-level end-to-end tests for most teams, and cheaper to keep green. E2E tests through the browser are slow, flaky, and break on a CSS change that has nothing to do with behavior. Contract-derived integration tests break only when the contract breaks, which is exactly when you want them to. Spend your test budget at the API boundary first.

Variables you'll set

Getting started

1. Export your OpenAPI or GraphQL schema, or grab one request/response per endpoint.
2. Decide the framework and paste a sample test in your house style.
3. Fill {{api_contract}}, {{test_framework}}, {{auth_model}}.
4. Run per resource group.
5. Verify negative-case statuses against the real contract.
6. Wire the boundary cases into CI so a schema change can't ship uncovered.
7. For a repeatable contract-to-tests pipeline, the API Contract Test Harness derives the contract and the case matrix together.

Contract-derived tests cover the boundary. To round out the suite, pair this with generating unit tests for the logic inside each handler and detecting breaking API changes before they reach a consumer. If you also review the diffs that touch these endpoints, the Code Review Policy System Prompt keeps test-coverage one of the mandatory review dimensions.