Apex Testing & Integration Reliability

A mocked callout proves your Apex—not your integration

JSBC Labs13 October 20268 min read

A test double is controlled fiction

Salesforce requires Apex tests to replace HTTP callouts with controlled responses. HttpCalloutMock is the right mechanism: the test registers a mock, the callout is intercepted and the mock supplies an HttpResponse. That isolation makes tests fast, deterministic and independent of a vendor's availability. It is a feature, not a compromise.

The mistake is interpreting that green test as proof that the integration works. The mock implements the assumptions already held by the Salesforce team. It cannot independently confirm the provider's schema, authentication, routing, certificates, rate limits or failure behaviour. The JSBC Labs position is simple: a mock verifies client logic against a simulation; integration confidence requires evidence from outside that simulation.

Name the layer each test covers

Use a layered model. Unit tests verify Apex branching, mapping and persistence with mocks. Contract tests verify that request and response schemas remain compatible. Component tests exercise the deployed Salesforce service with realistic configuration. Environment tests connect non-production systems. A small number of end-to-end scenarios verify the business outcome across the complete route.

These layers answer different questions and should not be collapsed into one suite. Salesforce Well-Architected guidance recommends a test pyramid with many unit tests, fewer integration tests and very few end-to-end tests. The exact counts depend on risk, but the principle matters: fast isolation provides breadth, while slower cross-system tests provide reality.

Assert the request, not only the result

Weak mocks return a successful payload regardless of what Apex sends. The test then proves only that the happy-path response can be deserialised. A useful HttpCalloutMock should inspect the HTTP method, endpoint path, query parameters, required headers and body. It should fail when mandatory fields are absent, types are wrong or data is sent to the wrong resource.

Keep secrets and volatile tokens out of assertions, but verify the contract around them. Test encoding, dates, nulls, decimal precision, external identifiers and correlation IDs. For write operations, assert the idempotency key or equivalent replay protection. The request is the product your integration publishes; treating it as incidental leaves the most important defect outside the test.

Make contracts executable

A hand-written response fixture can drift silently from the provider. Prefer a versioned OpenAPI, JSON Schema, WSDL or agreed set of canonical examples when the service supports one. Validate fixtures against that source and run provider or consumer contract checks in CI. Contract-first integration is one of the decisions Salesforce's integration guidance asks architects to evaluate.

Contract tests do not replace an environment connection. They detect structural incompatibility early and clarify who owns change. Version the contract, define compatibility rules and require notice for breaking changes. Test additive fields, missing optional fields and unknown enum values so a harmless provider enhancement does not become an Apex parsing incident.

Test failure as a first-class response

Production services do not return only 200 responses and neat error bodies. Build mock scenarios for authentication failures, validation errors, throttling, server errors, timeouts, malformed content, empty bodies and partial results. Assert the system's decision: retry, reject, park for review, surface a user-safe error or continue with degraded functionality.

Do not retry every failure. A validation error will not improve with repetition; an authentication failure may require configuration repair; a transient server error may justify bounded backoff. Tests should verify retry ceilings, ageing, dead-letter handling and operator visibility. Otherwise resilience code can turn one provider fault into duplicate work, queue pressure and exhausted Salesforce limits.

Authentication needs separate evidence

Named Credentials correctly separate endpoints and authentication from Apex code. Salesforce resolves the configured endpoint and credential at runtime, while principals can be mapped through permission sets, profiles or permission set groups. A mock-based unit test bypasses the real handshake, token scope, principal mapping and target environment configuration.

Add a deployment check that confirms the required Named Credential and External Credential metadata exist, then perform a controlled connectivity test in the target environment. Verify least privilege with the same identity model production uses. A test that succeeds only under an administrator or a developer's personal principal is evidence of a security gap, not a successful integration.

Exercise the transaction boundary

Callout design is also transaction design. Test whether database work happens before or after the request, what is committed when the provider succeeds but local persistence fails, and what happens when asynchronous work is delivered more than once. Use Test.startTest and Test.stopTest to execute queued work in unit tests, but recognise that they do not reproduce production queue depth, concurrency or downstream latency.

For critical writes, define a durable state machine: pending, sent, confirmed, failed and reconciled. Persist enough correlation data to investigate uncertainty without storing sensitive payloads unnecessarily. Unit tests should cover transitions; environment tests should interrupt the route at awkward points. The hardest integration defects live between two successful components, after one side has committed and the other side is unknown.

Use representative environments deliberately

A connected sandbox is valuable only when its data, credentials, permissions and provider behaviour resemble the path being released. Shared test endpoints often have different limits, certificates, validation rules or reference data. Document those differences instead of labelling the environment ‘production-like’ and assuming equivalence.

Run a compact smoke suite after deployment: authenticate, perform a safe read, execute one controlled business transaction and verify both systems' state. Clean up test data and make the suite repeatable. Reserve broad end-to-end scenarios for the journeys whose failure has material customer, financial or regulatory impact; exhaustive cross-system testing becomes slow and brittle without necessarily improving risk coverage.

Keep the pipeline fast without hiding risk

Unit tests with mocks should remain the base of the pipeline because developers need quick feedback and deployments need predictable validation. Run contract checks on every relevant change. Run connected integration tests where environment stability permits, and schedule wider resilience or performance tests at a cadence aligned to risk. A flaky end-to-end test should be diagnosed, not normalised through automatic reruns until green.

Publish results by layer so decision-makers can see what actually passed. ‘All tests green’ is ambiguous when only isolated unit tests ran. A release record should distinguish code validation, contract validation, target-environment connectivity and business-journey verification. That precision allows an informed go-live decision instead of transferring uncertainty into production.

Production completes the test strategy

No pre-production suite can reproduce every provider change, network condition or data combination. Instrument the live integration with correlation IDs, latency, response class, retry count, queue age and reconciliation status. Alert on user impact and sustained trends rather than every isolated transient error. Feed incidents and near-misses back into fixtures, contracts and failure scenarios.

The practical rule is to keep mocks—and narrow their claim. They are excellent evidence that Apex behaves correctly for the cases the team imagined. Contract checks, connected environments, controlled end-to-end journeys and production observability provide the evidence the mock cannot. That layered strategy protects delivery speed without confusing simulated success with operational truth.