Turn an integration contract into sandbox acceptance tests
Prepared with AI assistance by Alactic Editorial. Examples identified as hypothetical are illustrative, not customer results.
A sandbox demonstration can show a successful request without showing whether the integration performed the agreed business operation. A response might echo submitted data, acknowledge work that later fails, or update the right field while changing something else.
An acceptance test connects a functional requirement to observable evidence: preconditions, exact input, expected state, inspection method and a verdict rule. Here, “contract” means the agreed functional specification, not a legal interpretation.
The fictional pack below covers an authorised write, an invalid value, a relationship lookup and asynchronous completion. It excludes load testing, workflow automation testing and production observability. Its central discipline is to define exactly what will be compared before executing anything.
1. Turn each clause into an observable assertion
Replace “update the customer correctly” with a target record, permitted change, authorised identity and measurable result. Then identify what must remain unchanged. Otherwise, two testers can inspect different fields and both report a pass.
Each assertion needs five answers:
- Actor: Which sandbox identity acts, and with what permission?
- Target: Which workspace and stable object identifier are involved?
- Change: Which stored value must change?
- Boundary: Which other records and fields must be compared?
- Completion: What evidence distinguishes receipt from finished work?
Keep clause IDs attached to scenario IDs. Missing evidence is not a pass, and a scenario without a contractual requirement should be labelled an additional recommendation.
Broad phrases such as “all unrelated data remains unchanged” require broad inspection. If that inspection is unavailable, either narrow the agreed acceptance boundary before testing or mark the evidence insufficient. Do not quietly substitute a few convenient spot checks.
2. Fix the contract and the complete comparison boundary
Fictional worked example: Every identifier, value, state name and timing below is hypothetical. This is a recommended test design, not an Alactic capability description or a completed test run. Inputs are business notation, not real endpoints.
The integration can change a customer's service tier and read its linked account. The allowed tiers are standard and priority. The fictional contract contains these clauses:
- C-01: The authorised identity may change C-101's tier. Within comparison set B1 below, only C-101.service_tier may change.
- C-02: An unsupported tier must be rejected synchronously before work is queued. The response must identify the invalid field, and B1 must remain unchanged.
- C-03: Looking up C-101's account must return A-201 and its specified account fields. B1 must remain unchanged.
- C-04: An asynchronous acknowledgement identifies an operation but does not prove completion. Completion requires both a successful terminal operation state and the expected stored state.
B1 is the entire agreed comparison set: the following four records and every field shown for them. No other business records exist in this isolated fictional fixture.
Fixture: F1 | Workspace: W-TEST
Customer fields: id, workspace_id, service_tier,
contact_address, account_id
C-101 | W-TEST | standard | fixture@example.invalid | A-201
C-102 | W-TEST | standard | second@example.invalid | A-202
Account fields: id, workspace_id, display_name,
account_status, billing_reference
A-201 | W-TEST | Northstar | active | BILL-201
A-202 | W-TEST | Northstar | paused | BILL-202The duplicate account name is intentional. A-201 and A-202 differ in identity and business fields.
Excluded from B1 are system-managed updated_at and version fields, audit entries and operation-processing records. They may change and are not used to establish business-field non-mutation. Operation records are inspected separately as processing evidence. No claim is made about unlisted fields or data outside this isolated fixture.
This bounded contract is narrower than a promise that every unspecified field everywhere stays unchanged. If the actual requirement includes additional records or fields, expand B1 and its snapshots before execution.
3. Make the filled pack executable and scoreable
Use the following run card alongside the scenarios. Its evidence slots remain empty until execution; expected values are not observations.
Pack: P1 | Contract: C1 | Fixture: F1 | Boundary: B1
Identity: I-TEST
Permissions: read B1; update C-101.service_tier in W-TEST
Reset: approved sandbox fixture reset, followed by B1 verification
Readback: agreed authoritative sandbox read, not a request echo
Freshness: read reflects committed state at the observation time
Comparison: exact field values, matched by stable record ID
Rejected-write observation: response time plus 60 seconds
Async completion deadline: acknowledgement time plus 60 seconds
Evidence IDs: A-01/*, A-02/*, A-03/*, A-04/*
Initial verdicts: not run
Reviewer: assigned before executionThe observation periods are fictional acceptance choices, not product performance claims. Agree on a mechanism for inspecting operation state and synchronous admission decisions before starting. If those mechanisms or the required readback are unavailable, revise the design by agreement or mark the affected scenario blocked.
Each evidence bundle needs the sanitised input, response, identity reference without credentials, baseline B1 snapshot, required final B1 snapshot, observation times and reviewer verdict. Keep actual results separate from expected results.
Use pass only when every assertion has supporting evidence; fail when an observation contradicts a requirement; and blocked when execution or inspection cannot establish the result. A successful response with missing readback is blocked, not passed.
4. A-01: prove the authorised write and every required non-change
Traceability: C-01, plus C-04 if processing is asynchronous.
Preconditions: Reset F1 and capture all of B1. Verify I-TEST's agreed permission and confirm there are no outstanding operations from earlier runs. Isolate the fixture from other writers.
Input:
operation: change_customer_tier
workspace: W-TEST
customer: C-101
changes:
service_tier: priorityExpected result: After established completion, C-101.service_tier equals priority. Every other B1 value equals its baseline value: all remaining C-101 fields, every C-102 field and every field of both accounts.
Inspection: Retain the response. For synchronous completion, use the agreed completion meaning and authoritative readback. For asynchronous processing, apply A-04. Then obtain a complete B1 snapshot and compare every field by stable ID.
Worked comparison: F1 contains four records with five fields each: 20 compared values. Exactly one is expected to differ. A final C-101 tier of priority with A-202.account_status changed to active fails, even if the contact address, relationship and C-102 look correct.
Pass rule: Completion is evidenced, the one permitted difference exists and the other 19 values match. A missing record or unreadable comparison field prevents a conclusive pass. An observed prohibited change fails.
This proves an authorised operation, not denial of unauthorised operations. OWASP authorization guidance recommends least privilege and permission checks on every request. Add negative permission scenarios when those boundaries are part of the contract.
5. A-02: reject an invalid value before queuing work
Traceability: C-02.
Preconditions: Reset and verify all B1 values. Confirm I-TEST can submit a valid tier change, so a permission failure cannot masquerade as value validation. Ensure no earlier operation remains outstanding.
Input:
operation: change_customer_tier
workspace: W-TEST
customer: C-101
changes:
service_tier: platinumExpected result: The synchronous response rejects platinum and identifies service_tier through the agreed error structure. The admission evidence shows terminal rejection before queuing, with no executable job created for this submission.
Inspection: Submit through the integration interface, not only a form that might block the value locally. Retain the response and its correlation reference. Inspect the agreed authoritative admission record for that submission. Capture all B1 values immediately after rejection and again 60 seconds after the response.
Pass rule: The field error, terminal pre-queue rejection and both complete unchanged B1 snapshots must all be evidenced. A queued operation fails C-02 even if it later rejects without mutation. A prohibited change at either readback also fails.
An immediate unchanged snapshot alone cannot establish this result: it could precede an incorrectly delayed write. The later observation adds a bounded check, but elapsed time alone does not prove that nothing was queued. If admission evidence is unavailable, the scenario is blocked rather than conclusively passed.
If the actual integration permits deferred validation, rewrite C-02 before testing. Specify the terminal rejected state, how to establish that no executable work remains, and when the final full comparison occurs. Do not reuse this synchronous-rejection pass rule for a deferred design.
6. A-03: resolve the relationship using filled account values
Traceability: C-03.
Preconditions: Reset F1 and capture B1. Independently confirm C-101.account_id is A-201. I-TEST can read the customer and linked account.
Input:
operation: look_up_customer_account
workspace: W-TEST
customer: C-101Expected returned account:
id: A-201
workspace_id: W-TEST
display_name: Northstar
account_status: active
billing_reference: BILL-201Inspection: Compare all five returned account fields with these filled expected values. Establish the relationship from the independent fixture snapshot rather than trusting the lookup response itself. After the read completes, capture B1 again and compare every customer and account field.
Pass rule: All five returned values match A-201, and all 20 B1 values match the baseline. Returning A-202 fails even though its display name matches. Returning only Northstar is insufficient. Any prohibited mutation fails; missing required evidence blocks the verdict.
This scenario tests the in-scope relationship only. It does not establish cross-workspace isolation. Where required, add a separate out-of-scope lookup scenario: possession of a record identifier alone should not establish permission, as explained in OWASP object-level authorization guidance.
7. A-04: distinguish acknowledgement from completion
Traceability: C-04 and the asynchronous completion portion of A-01.
Preconditions: Reset F1, capture B1 and use the agreed asynchronous test path. The hypothetical operation states are received, running, succeeded and failed; the last two are terminal.
Input: Submit A-01's change to priority.
Expected result: The acknowledgement identifies an operation. Within 60 seconds of acknowledgement, that same operation reaches succeeded, and authoritative readback shows the complete A-01 expected B1 state.
Inspection: Capture acknowledgement time and operation reference. Inspect subsequent states through the agreed mechanism, recording observation times. After success is reported, read and compare all B1 values before the deadline.
Pass rule: Correlated receipt, terminal success and the complete expected B1 state are all evidenced within the fictional deadline. An acknowledgement alone cannot pass. A terminal failure or prohibited B1 change fails. If inspection works but completion is late, fail the timing assertion; if required inspection is unavailable, mark the scenario blocked.
Do not resubmit merely because the first response proves only receipt. Inspect the original operation first. Retry safety requires its own agreed behaviour and is not established by this pack.
8. Retain evidence without hiding gaps
Keep failed runs alongside reruns. For each discrepancy, distinguish an implementation defect, an incorrect fixture, an ambiguous requirement and unavailable evidence. Correct the relevant cause rather than changing expected values to fit the result.
Use narrow read permissions where possible, but do not reduce the agreed comparison coverage without recording the change. Sanitise credentials and unnecessary personal data in shared evidence. Reset fixtures only through an approved sandbox method.
The review deliverable is the filled pack plus actual evidence and verdicts—not a demonstration video alone. Report clause coverage, conclusive scenario results and unresolved failures or blocks separately. That makes the remaining decision concrete: which business assertions have been established, and which still lack proof?
Put the next conversation to work.
Explore Alactic Communications for WhatsApp conversations, campaigns and AI-assisted workflows. Choose the product and plan that fit your team.
Explore Communications