What is the difference between mocking an API and using a real sandbox?

What a mock actually does

When you mock an API, you replace the real service with a stub that returns a canned answer. Mocks are fast, cheap, and perfect for unit tests, because they let you check one narrow thing without any network. The catch is that a mock only knows what you told it. If you forgot that Stripe rejects a refund larger than the original charge, your mock will happily approve it, and the bug waits for production.

What a real sandbox does instead

A sandbox runs the real rules against a throwaway dataset. Create a customer and it is stored. Read it back and it is there. Try to refund more than you charged and it refuses, the same way the live API would. You are no longer testing your assumptions about the service, you are testing against the service.

When to use which

• Use mocks for unit tests, where you want speed and a single isolated assertion
• Use a sandbox for integration and workflow tests, where the point is whether the sequence of real actions holds together

They are not rivals. Mocks check that your code calls the API correctly. A sandbox, whether a vendor test mode like Stripe test mode and test cards or a dedicated cross-service environment, checks that the API accepts what your agent actually did.

The tools between a mock and production

This is a spectrum, not a binary, and the right point on it depends on how much realism a given test needs. From lightest to most realistic.

• Record and replay (Polly.js and VCR-style libraries) captures real responses once and plays them back deterministically. The payloads are real, but the state is frozen and it cannot produce a failure you did not record.
• Mock servers (WireMock, Mockoon) are programmable HTTP stubs with configurable delays and error responses. Good for exercising one service's failure paths, though they hold no real state and enforce none of the service's rules.
• Real dependencies in Docker (Testcontainers) run an actual Postgres, Redis, or Kafka inside the test. Genuinely realistic, but only for services with a self-hostable image, which leaves out SaaS like Stripe or Slack.
• Vendor test modes (Stripe test mode and test cards, Salesforce Developer Edition and scratch orgs) are the real service's own sandbox. Accurate for that one service, but each is siloed and configured its own way.
• Cross-service replicas (Arga Labs) run connected, stateful twins of several SaaS at once, so a record created in one is visible from another and you can fail exactly one mid-workflow. Closest to production for a multi-service agent, and heavier to run than a mock.

Most teams end up with a mix. A mock for the unit test, a mock server or a recording for one service's edge cases, and a replica when the thing under test is a workflow that crosses several services.

When a mock is the right choice

Do not reach for a sandbox reflexively. A mock is the better tool when:

• You are unit-testing your own code paths (retry logic, error handling, parsing) and want to force a specific response, including ones that are hard to trigger for real
• You need determinism and millisecond speed on every commit, with no network
• The service has no usable test environment, so a mock is the only option short of hitting production

The failure mode is trusting a mock beyond its remit. A mock only knows what you told it, so it cannot catch a rule you did not know about (a refund larger than the charge, a required field, a permission you lack). Use mocks to test your code, and a sandbox to test the integration. Most real suites use both.