Idempotency Acceptance Criteria Prompt

This prompt is for integration test engineers and backend developers who need to translate an API's idempotency requirements into verifiable, automation-ready Gherkin scenarios. The core job-to-be-done is taking a technical specification—often a single sentence like 'the payment endpoint must be idempotent'—and expanding it into a comprehensive set of behavior contracts that cover duplicate requests, concurrent submissions, key lifecycle, and collision handling. The ideal user has access to the API specification, the idempotency key header name, and any known business rules around key expiration or scope (e.g., per-account vs. global). Without this context, the prompt will produce generic scenarios that miss critical implementation details.

Use this prompt when you are building integration tests for any state-changing endpoint where a retried request must not produce a duplicate side effect. This includes payment capture, order creation, ledger entries, and resource provisioning. The prompt is designed to produce Gherkin feature files that can be directly fed into BDD frameworks like Cucumber or SpecFlow. It is not suitable for read-only endpoints, fire-and-forget operations where duplicates are acceptable, or workflows that rely on external transactional guarantees without an idempotency key. Do not use this prompt if you are looking for a general explanation of idempotency; it assumes the reader already understands the concept and needs executable specifications.

Before running this prompt, gather the exact idempotency key header name, the key's scope (e.g., per merchant, per account, or global), the documented or intended expiration window, and any known collision behavior. The output will include scenarios for the happy path (first request accepted, duplicate returned with original result), concurrent submissions, key reuse after expiration, missing or malformed keys, and cross-scope collision attempts. After generating the scenarios, you must validate them against the actual API implementation—this prompt produces a starting point for test design, not a replacement for exploratory testing against the real system. Pay special attention to the [IDEMPOTENCY_KEY_EXPIRATION] and [KEY_SCOPE] placeholders; if you leave them unresolved, the generated scenarios will contain vague assertions that cannot be verified.

This prompt template translates technical specifications for idempotent operations—such as payment endpoints, order creation, or any state-changing API—into executable Gherkin scenarios. It is designed to be copied directly into your prompt library or AI harness, with square-bracket placeholders that your application layer should populate before sending the request to the model. The template forces the model to reason about the full idempotency-key lifecycle: creation, storage, validation, expiration, collision handling, and concurrent request behavior.

textCopy
You are a senior integration test engineer specializing in API reliability and safe-retry patterns.

Your task is to generate executable Gherkin acceptance criteria for idempotent behavior based on the provided API specification and system design context.

## INPUT
[API_SPECIFICATION]
[IDEMPOTENCY_DESIGN_DOC]

## CONSTRAINTS
- Generate only Gherkin scenarios with Given-When-Then structure.
- Cover the full idempotency-key lifecycle: first request, duplicate request, concurrent requests, key expiration, key collision, and cross-client key isolation.
- Include explicit examples tables for request payloads, idempotency keys, and expected responses.
- For each scenario, specify the expected HTTP status code, response body shape, and any side-effect guarantees (e.g., exactly-one execution).
- Flag any scenario where the specification is ambiguous and state the assumption you made.
- Do not invent API behavior not present in the input documents.

## OUTPUT_SCHEMA
Return a JSON object with the following structure:
{
  "scenarios": [
    {
      "id": "string",
      "name": "string",
      "category": "first-request | duplicate-request | concurrent-request | key-expiration | key-collision | cross-client-isolation | key-reuse",
      "gherkin": "string (multi-line Gherkin with Given, When, Then)",
      "examples_table": [
        {
          "columns": ["string"],
          "rows": [["string"]]
        }
      ],
      "expected_status": 200,
      "expected_response_shape": {},
      "side_effect_guarantee": "string",
      "assumptions": ["string"]
    }
  ],
  "coverage_gaps": ["string (categories or edge cases not addressed by the input documents)"],
  "ambiguities_flagged": ["string (specification points that require clarification before implementation)"]
}

## EXAMPLES
Example scenario structure:
{
  "id": "IDEM-001",
  "name": "Duplicate request with same idempotency key returns stored result",
  "category": "duplicate-request",
  "gherkin": "Given a payment endpoint \"POST /payments\"\nAnd a valid idempotency key \"idem-abc123\" was used in a successful request that returned status 201 with body {\"id\": \"pay-001\", \"status\": \"succeeded\"}\nWhen a second request is sent with the same idempotency key \"idem-abc123\" and identical body\nThen the response status is 200\nAnd the response body matches the original response {\"id\": \"pay-001\", \"status\": \"succeeded\"}\nAnd no new payment is created",
  "examples_table": [
    {
      "columns": ["Request", "Idempotency-Key", "Expected Status", "Expected Body"],
      "rows": [
        ["POST /payments {\"amount\": 100}", "idem-abc123", "201", "{\"id\": \"pay-001\"}"],
        ["POST /payments {\"amount\": 100}", "idem-abc123", "200", "{\"id\": \"pay-001\"}"]
      ]
    }
  ],
  "expected_status": 200,
  "expected_response_shape": {"id": "string", "status": "string"},
  "side_effect_guarantee": "No duplicate payment created; original result returned unchanged.",
  "assumptions": ["Idempotency key storage duration exceeds the retry window."]
}

## RISK_LEVEL
[RISK_LEVEL]

To adapt this template, replace [API_SPECIFICATION] with your OpenAPI spec, endpoint documentation, or a plain-text description of the endpoint's request and response contracts. Replace [IDEMPOTENCY_DESIGN_DOC] with your team's design decisions around key storage, expiration policy, collision strategy, and scope (per-account, per-endpoint, or global). The [RISK_LEVEL] placeholder should be set to high for payment or financial operations—this signals the model to apply stricter validation and flag more edge cases. If your application needs a different output format, modify OUTPUT_SCHEMA before injecting the prompt. Always validate the model's output against the schema before accepting it into your test management system.

This prompt is designed to be called programmatically as part of a test asset generation pipeline. The primary input is a structured API specification (OpenAPI, gRPC proto, or a plain-text endpoint description) and the target idempotency strategy (e.g., Idempotency-Key header, token-based, or payload hash). The output is a set of Gherkin feature files. To integrate this, wrap the prompt in a thin service that accepts an API spec and a strategy type, injects them into the [API_SPECIFICATION] and [IDEMPOTENCY_STRATEGY] placeholders, and calls the LLM. The service should enforce a strict output contract: the response must contain only the Gherkin text block, or a parseable JSON object with a scenarios array if you modify the template to request structured output.

Before the generated .feature files land in your test repository, implement a validation gate. A lightweight parser should verify that every scenario contains the mandatory tags (@idempotency, @safe-retry, @concurrent), that Given steps reference a known initial state (e.g., 'a payment with ID X does not exist'), and that Then steps assert on the exact resource state, not just HTTP status codes. For high-risk domains like payment processing, add a human review step in your CI pipeline: if the prompt generates a new scenario involving a 409 Conflict or a key-collision case, flag it for a senior engineer to confirm the expected behavior before the test is merged. Log the prompt version, model, and input hash alongside the generated scenarios to enable traceability when a test fails in production and you need to determine if the failure is a spec bug or a generation artifact.

For retry and error handling, configure your harness to call the LLM with a temperature of 0.0 to maximize determinism. If the output fails validation (e.g., a missing Scenario Outline for a parameterized test), do not silently discard it. Instead, feed the raw output and the validator error message into a repair prompt that asks the model to fix the specific structural issue. Limit this repair loop to a single retry to avoid infinite correction cycles. Finally, treat the generated Gherkin as a starting point, not a finished test suite. The harness should append a comment header to each .feature file noting the generation date, the source API spec version, and a warning that human review is required before the test gates a release.