test-doubles-wiremock

Test Doubles & WireMock

Overview

An automated test that calls a real third-party service (payment gateway, auth provider, partner API) is slow, flaky, costs money, and cannot exercise failure modes on demand. Replace those dependencies with a controllable stub — WireMock for HTTP — so the test owns every response.

Core principle: The system under test is real; its external dependencies are stubbed. You test YOUR code's behavior against controlled inputs, not the third party's uptime.

When to Use / When NOT

• Stub: third-party/external HTTP services, payment/email/SMS providers, partner APIs, anything you don't own or that has side effects/cost.
• Do NOT stub: the product's own API or the code under test — driving those for real is the whole point. And do not stub the database; use a real test database instead (see test-database-seeding) so SQL/dialect behavior is genuine.

WireMock Essentials

Run WireMock as a standalone server or a Testcontainers container; point the app's config for that dependency at its URL.

// stub: the auth provider returns a valid token for a known client
{
  "request":  { "method": "POST", "url": "/oauth/token" },
  "response": { "status": 200, "jsonBody": { "access_token": "test-token", "expires_in": 3600 } }
}

Model the failure paths too — that's the value a real service won't give you on demand:

Scenario to cover	WireMock stub
Happy response	200 + expected body
Upstream 5xx	"status": 503 → assert your retry/fallback
Timeout	"fixedDelayMilliseconds": 30000 → assert your timeout handling
Malformed body	200 + garbage → assert you don't crash
Auth rejected	401 → assert your error surfaces cleanly

Rules

• Verify the request too, not just the canned response: assert the app called the dependency with the right method/path/body (WireMock verify). A stub that always returns 200 hides a broken request.
• Reset stubs between tests so one test's mappings don't leak into another.
• Match the contract exactly — stub the real endpoint's shape. A stub that diverges from reality passes tests but ships integration bugs; keep it aligned with the provider's documented contract.
• Prefer per-test stubs over one giant global mapping file — tests stay readable and independent.