Integration Test Scaffold Prompt for API Endpoints

This prompt is designed for backend engineers who need to quickly bootstrap a complete, runnable integration test for a single API endpoint. The ideal user has an OpenAPI specification excerpt, a clear endpoint definition, and an existing codebase with established test patterns. The job-to-be-done is not just generating a test, but generating one that immediately fits the team's conventions for fixtures, database state management, and assertion style, saving the hours of boilerplate wiring that typically slow down test-driven development.

Use this prompt when you are adding a new endpoint to a service and need a test that validates the full request-response lifecycle, including database interactions. It is also effective for rapidly covering legacy endpoints that lack integration tests, provided you can supply the spec and a few examples of your team's current test patterns. The prompt is specifically scoped to single-service, single-endpoint integration tests. It is not suitable for generating unit tests that mock all dependencies, contract tests that validate provider-consumer pacts, or end-to-end flows that orchestrate multiple services and asynchronous events. For those, you need separate, specialized prompts.

Before using this prompt, gather three pieces of context: the target endpoint's OpenAPI definition (method, path, request/response schemas, and status codes), 2-3 examples of existing integration tests from your repository to establish the pattern, and any database schema information relevant to the endpoint's side effects. The generated output is a starting point that requires human review for business logic correctness, test data sensitivity, and environment dependencies. Do not use this prompt for endpoints that trigger irreversible side effects (e.g., payment processing, user deletion) without first adding manual confirmation steps and running against a sandbox environment.

This prompt template instructs an AI coding agent to produce a complete integration test scaffold for a single API endpoint. It is designed to be pasted directly into your agent's interface after you replace the square-bracket placeholders with your specific endpoint details, repository conventions, and quality constraints. The prompt forces the agent to analyze the provided context—such as an OpenAPI specification, route handler, and existing test patterns—before generating any code, ensuring the output respects your project's established testing style.

markdownCopy
You are an expert backend test engineer. Your task is to generate a complete integration test scaffold for the API endpoint described below. You must analyze the provided context to understand the endpoint's contract, side effects, and the project's existing test conventions before writing any code.

## Required Inputs
- **Endpoint Definition:** [ENDPOINT_SPECIFICATION]
- **Route Handler Code:** [ROUTE_HANDLER_CODE]
- **Database Schema (if applicable):** [DATABASE_SCHEMA]
- **Existing Test File (for style reference):** [EXISTING_TEST_FILE]
- **Test Framework & Libraries:** [TEST_FRAMEWORK]

## Task
1.  **Analyze:** First, identify the HTTP method, path, request body schema, query parameters, and expected success/error response schemas from [ENDPOINT_SPECIFICATION].
2.  **Map Side Effects:** Analyze [ROUTE_HANDLER_CODE] to determine all side effects, such as database writes, external API calls, or event publications.
3.  **Adopt Conventions:** Examine [EXISTING_TEST_FILE] to extract the project's patterns for test structure, naming, assertion style, fixture setup, and teardown.
4.  **Generate Scaffold:** Produce a test file using [TEST_FRAMEWORK] that includes:
    - A `describe` block named after the endpoint (e.g., `POST /api/users`).
    - A `beforeEach`/`afterEach` block to set up and tear down the required database state using the provided [DATABASE_SCHEMA].
    - A test case for a successful request (`201 Created`) with valid request body and assertions on the response status, headers, and body shape.
    - A test case for a client error (`400 Bad Request` or `422 Unprocessable Entity`) with an invalid request body, asserting on the error response structure.
    - A test case for a server-side failure, mocking any external dependencies identified in step 2 to simulate an error, and asserting on the `500 Internal Server Error` response.
    - A test case for an authentication/authorization failure (`401 Unauthorized` or `403 Forbidden`) if the endpoint is protected, as indicated by [ENDPOINT_SPECIFICATION].
5.  **Output Format:** Return ONLY the raw test file content, enclosed in a single fenced code block with the appropriate language identifier. Do not include any introductory or concluding remarks outside the code block.

## Constraints
- [CONSTRAINTS]

To adapt this template, replace the placeholders with concrete values. For [ENDPOINT_SPECIFICATION], you can paste a fragment of an OpenAPI YAML/JSON file or a curl command. For [ROUTE_HANDLER_CODE], provide the actual controller or handler function. The [CONSTRAINTS] placeholder is critical for safety; use it to inject non-negotiable rules such as 'Do not generate tests that mutate a production-like database' or 'All external calls must be mocked using the project's standard mocking library.' After pasting the filled-in prompt, review the generated scaffold to ensure the mocks are complete and the database setup/teardown logic is correct and isolated before integrating it into your CI pipeline.

This prompt is designed to be called programmatically as part of a CI pipeline or a developer CLI tool, not as a one-off chat interaction. The primary integration point is a backend service that receives an OpenAPI specification file, a target endpoint path, and the repository's existing test conventions as input. The service assembles the prompt, calls the model, and then must validate the generated scaffold before it ever touches a test file. Treat the raw model output as a draft proposal, not a finished artifact.

The implementation harness requires three mandatory validation gates before the scaffold is written to disk. First, a schema validator must confirm the output contains the expected structure: a top-level testScaffold object with testName, setupSteps, requestFixture, responseAssertions, and teardownSteps arrays. If the model returns malformed JSON or missing fields, trigger a single retry with a stricter repair prompt that includes the validation error and the original schema. Second, a spec-compliance check must verify that every request fixture path, method, header, and status code in the generated scaffold exists in the source OpenAPI specification. Any hallucinated endpoint or parameter is a hard stop. Third, a convention-linting step must compare the generated test against the repository's existing test patterns—framework imports, naming conventions, assertion library usage, and setup/teardown patterns—and flag deviations for human review. Only after all three gates pass should the scaffold be written to a temporary branch for PR creation.

For model choice, prefer a model with strong code generation and structured output capabilities, such as Claude 3.5 Sonnet or GPT-4o, with the response_format set to json_schema and the expected schema provided as part of the API call. Set temperature to 0.1 to maximize determinism. Log every prompt version, model response, validation result, and human decision to an audit table. This is critical for debugging when a generated test later proves flaky or misses a contract change. If the workflow is applied to production APIs with regulatory or availability requirements, route all generated scaffolds through a mandatory human approval queue in the PR review tool before merging. Never auto-merge generated integration tests against production endpoints without human sign-off.

The most common production failure mode is spec drift: the OpenAPI file used at generation time is stale relative to the deployed API. Mitigate this by fetching the live spec from a known endpoint or requiring a spec version hash as a required input. If the hash doesn't match the latest deployment, abort generation and alert the team. A secondary failure mode is test pollution: generated setup steps that mutate shared state and break other tests. The harness should scan generated setup for database writes, queue publishes, or cache mutations and flag them for isolation review. Finally, avoid wiring this prompt into a fully autonomous agent loop. The cost of a bad integration test—false confidence in a broken API—is far higher than the cost of human review.