What should API integration testing prove?
API integration testing checks whether connected components exchange data and produce the expected result across a defined boundary. For a business workflow, verify the downstream record and final state, not only the HTTP response. Record which systems were real, which were simulated, and what each test could not prove.
A passing mock test can show that your application handles a chosen response. It cannot show that a provider currently accepts your credentials, interprets your fields correctly, or completes the requested action. Conversely, one successful sandbox request does not cover every failure path.
This guide gives an engineering lead a proposed test-boundary worksheet and a hypothetical CRM-to-ERP release example. It is a planning framework, not a report of Hapy tests. Use the custom web app integration guide to settle API access, data ownership, and sync requirements first. Use the broader QA methodology to place these checks within the release process.
Choose the boundary before the tool
Define the interaction you need to verify before choosing a testing framework. Name the application, database, queue, and external service involved. State which components the test runs and which it replaces. Test names alone are not enough because teams use terms such as integration and end-to-end differently.
Postman’s integration-testing documentation describes checking component interactions and data flow with ordered requests, response assertions, environments, and mocks. Those mechanisms can support different test boundaries. The collection’s contents determine its evidence, not the tool’s name.
Use this proposed worksheet to separate the checks:
| Check | What runs | Useful evidence | What remains unverified |
|---|---|---|---|
| Local mapping test | Transformation code and fixed input | Expected identifiers, amounts, dates, and missing-field behavior | Network, persistence, and provider acceptance |
| Consumer/provider contract | Consumer expectations plus matching provider verification | Tested request and response compatibility for the recorded versions and states | Full business completion and deployed connectivity |
| Controlled integration | Application with real test database or queue; external provider simulated | Persistence, dispatch, recovery, and handling of chosen provider responses | Actual provider behavior |
| Provider sandbox workflow | Application and real provider test service | Credentials, configuration, accepted payloads, and observable test records | Production-specific differences and untested paths |
Choose the smallest boundary that exposes the risk. A field conversion can be checked locally. A queue acknowledgement or database transaction needs the relevant real component. A permission or provider configuration problem needs an approved provider environment.
Where contract evidence stops
Contract testing checks the messages applications expect to exchange. Pact’s introduction distinguishes consumer expectations from a standalone schema check. A schema can describe a valid field without proving that the consumer sends the right value or uses the response correctly.
In Pact’s consumer and provider process, consumer tests generate interactions and provider verification compares actual responses with those expectations. A mock that only repeats your assumptions is not that paired evidence. If an external provider does not participate, record the missing verification instead of calling the consumer test proof of compatibility.
Contract checks also do not prove that deployed credentials work or that a message crosses the actual broker. Keep those separate checks where the workflow requires them.
Build fixtures that make wrong results visible
Use synthetic fixtures with known expected outputs and a unique test-run identity. A fixture is the controlled data and state that a test starts from. Choose values that expose mapping mistakes rather than copying one ordinary example through every test.
For a proposed order integration, include a customer identity that differs from the ERP record ID, a decimal amount, an optional field that is absent, and enough records to cross a pagination boundary. Add currency or timezone cases only where the integration transforms those fields. Define the expected result independently; do not calculate it with the same mapping function under test.
Record the environment with the fixture: application version, provider API version, database state, queue configuration, account permissions, and relevant feature flags. Keep secrets out of test reports. A reproducible result needs configuration identity, not a copy of the credential.
Make each scenario independently repeatable. Give it its own namespace or records, establish preconditions explicitly, and avoid relying on another test to create an account first. Parallel runs must not change each other’s expected state.
Plan cleanup before the first write. Record created identifiers, run cleanup even after an assertion fails, and verify what remains. Where deletion is unavailable, use approved isolated records and a documented retention process. Never let a test cleanup routine select customer records through a broad filter.
Follow one workflow to its confirmed final state
For asynchronous work, assert the terminal business result within an agreed deadline. An accepted request is an intermediate observation. HTTP 202 Accepted means processing has been accepted but is not complete; it does not guarantee that the action will finish.
Consider a hypothetical workflow: an approved CRM order enters an integration queue, creates an ERP draft, and writes the ERP identifier back to the CRM. The team requires confirmation within 60 seconds in its test environment. That deadline is an example acceptance requirement, not a provider promise or measured benchmark.
The proposed test proceeds as follows:
- Create an isolated CRM order with known customer, line-item, and amount values. Confirm no matching ERP draft exists.
- Trigger the integration through its normal entry point. Record the operation identity and the accepted response without declaring success.
- Observe the queue and worker through supported test interfaces. Check that the operation remains pending while downstream work is unfinished.
- Poll the supported status or record-read interface until the required state appears or the 60-second deadline expires. Use bounded polling, not a fixed sleep followed by an unconditional pass.
- Read the ERP draft and CRM backlink. Compare both with the independent expected data. Fail the test if a critical value differs or completion is missing.
- Clean up the isolated records and verify cleanup. Preserve a masked diagnostic record when the test fails.
An empty queue does not prove completion if a failed operation disappeared from it. Preserve a trace from accepted input to the final record, or to a visible failure with a recovery owner.
Reconcile records, not only counts
Compare identities and material fields, not just the number of records. Ten expected and ten actual orders can still contain one duplicate and one omission. Match the expected identifier set, check uniqueness, and compare the required fields for each record.
In the example, a correct ERP draft with a missing CRM backlink is still an incomplete workflow. So is a matching total assigned to the wrong customer. The release evidence should make those distinctions visible.
Inject failures where you can control them
Use controlled doubles to reproduce external failures safely. Use real test components for the behavior that depends on those components. For example, a simulated provider can return an expired-credential response or malformed payload; it cannot prove that your deployed network path can reach the real provider.
Select failure cases from the workflow’s actual risks. For this proposed integration, check a rejected field, unavailable credentials, a delayed response, a worker restart after persistence, and a downstream write whose response is lost. Record the expected application state and operator action for each case.
Duplicate prevention belongs to the idempotency-key contract. This test plan should verify that the integration follows that contract rather than redesigning it. Likewise, use the shared API request budget when testing throttling and recovery. Do not flood a live provider to discover its limits.
Keep simulated responses aligned with current provider documentation and approved observations. Record their provenance and review them when the API version changes. A convenient fixture that no longer matches the provider can keep a broken integration green.
Make the release decision from the evidence
Approve a workflow only when its critical acceptance outcomes have adequate evidence. A large passing-test count does not compensate for an unverified data boundary or an unresolved wrong-record result.
Keep a short release record with the tested workflow, build and configuration identifiers, real and simulated components, fixture IDs, final-state assertions, run result, cleanup result, and known omissions. Link masked failure evidence to a named owner. State what must be rerun when the application or provider changes.
Separate a product defect from a provider-environment failure, but do not turn either into a pass. If the sandbox is unavailable, the relevant check remains unverified. The team can delay release, remove that workflow from scope, or obtain an approved alternative validation method. Record the decision and its limits.
Take the completed boundary worksheet and one critical workflow to the release review. Hapy offers business systems automation for teams that need help defining and delivering these integrations. Hapy has a commercial interest in that service.
