A repeated HTTP response does not prove an operation was safe. API idempotency testing follows a request through the stored result and every business effect it could create.
Why this Skill is needed
A client may time out after the server commits an order. If the client retries, a response cache can look correct while a second payment, event, or notification slips through. This Skill helps teams examine the write contract and reconcile those effects.
What the Skill helps you do
Use the API Idempotency Testing Skill to turn a write operation into a bounded scenario set:
- Extract the documented key scope, payload matching rule, retention window, concurrency behavior, and conflict response. Mark any missing rule as a question.
- Vary one condition at a time: reuse a key, change the payload, race requests, retry after a timeout, and cross the documented expiry boundary.
- Join responses to durable records—such as order IDs, payment attempts, and emitted events—then record an AIT-## finding with the evidence and next validation action.
The point is to judge the contract against observable effects, not to reward familiar-looking response bodies. Awesome QA Skills organizes Skills by language and testing stage; the series overview explains the shared installation model.
Scope and limits
The Skill can propose scenarios and organize supplied evidence. It does not decide what the API’s key scope or expiry policy should be, execute requests, or infer a successful commit from a timeout. A design review without run records remains a test plan, not an execution result.
What to inspect
| Contract area | Questions to resolve | Evidence to compare |
|---|---|---|
| Key scope | Is the key scoped by operation, account, endpoint, or another documented boundary? | Request identity, authenticated principal, operation record |
| Payload identity | What happens when the same key arrives with a changed body? | Canonical request or fingerprint, conflict response, write ledger |
| Replay window | How long is the result retained, and what is defined after expiry? | Contract version, key record, timestamps around the boundary |
| Concurrency | What does a second request observe while the first is still processing? | Ordered request timeline, lock/claim state, response and commit record |
| Business effects | Did the operation create more than one durable effect? | Order, charge, message, or event identifiers joined to the key |
Keep response replay and side-effect uniqueness as separate judgments. A repeated 202 or identical body is not enough if the business ledger contains two writes.
Audit inputs before designing scenarios
| Needed input | Why it matters | If it is missing |
|---|---|---|
| Write operation and intended business effect | Defines what must happen once | Name the unknown effect; do not invent one |
| Key and payload contract | Defines equivalence and conflict | Leave same-key/different-payload behavior open |
| Retention and concurrency rules | Defines timing boundaries | Do not infer an expiry from cache configuration |
| Evidence sources and join fields | Connects requests to committed effects | Request the smallest useful query or trace; keep the result unassessed |
Record source version, environment, time range, included operations, and the owner who can confirm the contract. Distinguish known, missing, conflicting, stale, out_of_scope, and assumptions in the input notes.
Worked scenario: checkout response lost after commit
This is a test-design example, not a claim that the endpoint has been run. Suppose cart-1842 is submitted with key checkout-1842, the server commits an order, and the client times out before receiving the response.
Scenario sequence
| Step | Request or check | Question to answer |
|---|---|---|
| 1 | Submit the checkout request and retain its key, body, and request ID | What does the contract say the write creates? |
| 2 | After the timeout, query the order and payment records using available join fields | Is the first commit confirmed, absent, or still indeterminate? |
| 3 | Replay the original request serially, then submit overlapping requests with the same key | Does the documented in-progress or replay behavior hold, and how many effects exist? |
| 4 | Reuse the key with a changed cart, then inspect the contract-defined conflict result | Is the payload conflict handled as specified without another write? |
| 5 | Submit the same business intent with a new key | Does the contract treat it as a new operation, and is that effect intentional? |
| 6 | Repeat on both sides of the retention boundary | What happens to a late retry, and is that behavior explicitly defined? |
Judge each row against the supplied contract. For example, do not assert that every API must return 409; record the expected conflict behavior from the actual contract. Count committed business effects, not request attempts.
Example finding
Use this shape only after replacing the placeholders with project evidence:
| Field | Example |
|---|---|
| ID and question | AIT-01 — Does a retry after a committed checkout timeout create another order or payment? |
| Evidence state | UNASSESSED until request and business ledgers are joined |
| Impact and priority | Describe the affected effect and use the project’s impact scale; NOT_SCORED until evidence supports a score |
| Owner | API or payment-contract owner who can confirm replay and expiry rules |
| Close condition | Contract judgment, joined commit ledger, and repeatable scenario results are reviewable |
Do not label the example as a defect or a pass before the source, run, and business-state evidence exist.
Handoff to the next stage
| Handoff field | Include |
|---|---|
| Contract | Versioned key scope, payload rule, replay window, and conflict behavior |
| Scenario | Exact request variants, timing, concurrency, and environment |
| Reconciliation | Join fields and counts for each durable business effect |
| Finding | AIT-##, evidence state, impact basis, owner, and close condition |
| Next action | The missing query, contract decision, or repeatable runtime check |
A downstream reviewer should be able to follow the key from request to stored result and effect ledger. If those records cannot be joined, say which link is missing instead of claiming exactly-once behavior.
Related Skills
- API Contract Testing establishes the request and response contract.
- Retry Testing explores retry triggers and boundaries.
- API Error Contract Testing reviews conflict and processing responses.
Common traps
- Treating equal responses as proof of one business effect.
- Testing serial retries but not overlapping requests.
- Assuming a changed payload, missing key, or expired key has a universal expected response.
- Counting HTTP attempts instead of committed orders, charges, messages, or events.
Install and invoke
Install the individual Skill, then attach the real operation contract and evidence sources:
npx skills add https://github.com/naodeng/awesome-qa-skills/tree/main/skills/en/testing-types/api-idempotency-testing -gUse the prompt’s output contract when preparing a design or evidence review:
Use the api-idempotency-testing Skill.
Task: assess a checkout POST whose client timed out after the server may have committed the order
Inputs: [contract version, request samples, logs, state queries, or data paths]
Scope: [operations and business effects included or excluded]
Unknowns: [missing environment, key rules, join fields, or permissions]
Expected output: [risk-ordered AIT-## findings, evidence states, and next validation actions]
Separate facts, assumptions, and open rules. Do not claim execution without a run record.FAQ
What if the first response was lost?
First establish whether the write committed by querying the business record with the available operation ID or key. A timeout alone does not establish either success or failure.
Must the server reject every changed payload using an existing key?
Follow the documented API contract. If it does not define the case, record a contract gap and ask the accountable owner; do not supply a policy in the test result.
Is a time-based key expiry sufficient?
Only when the contract defines late-retry behavior and the remaining duplicate-effect risk has been assessed with evidence.
References
Source Skill and execution contract
The API Idempotency Testing prompt defines the workflow and output contract. The source directory contains its entry point and supporting material.