API Mocking

Also Known As

TL;DR

Explanation

API mocking tools: Prism — generates a mock server from an OpenAPI spec instantly, returning example responses. WireMock — record real API calls and replay them, or configure stub responses with delays and error simulation. Mockoon — desktop GUI for managing mock APIs. PHP unit tests: Guzzle MockHandler intercepts HTTP at the client level — no actual network connection made. Use cases: test error scenarios (429, 503, timeouts) that are hard to trigger with real APIs, CI without external service dependencies, and frontend development before the backend is ready.

Common Misconception

Why It Matters

Common Mistakes

• Real API calls in unit tests — slow, flaky, require network, create production test data
• Mock responses that don't match the actual API spec — tests pass but integration fails
• Not testing error scenarios — real APIs fail; mocks must simulate 429, 503, network timeouts
• Outdated mock responses — mocks must be updated when the real API contract changes

Avoid When

• Avoid mocking as a substitute for contract or integration tests — mocks can drift from the real API silently.
• Do not mock at the HTTP level in integration tests that are specifically meant to verify end-to-end behaviour.
• Avoid over-specifying mock responses — brittle mocks that encode every response field break when the API evolves.

When To Use

• Unit testing code that calls external HTTP APIs — mocks remove network dependency and make tests deterministic.
• Developing a consumer before the provider API is ready — a mock server lets both teams work in parallel.
• Testing error and edge-case responses (timeouts, 429, 503) that are hard to trigger against a real service.

Code Examples

// Real HTTP calls in unit test — slow and fragile:
public function testSendConfirmationEmail(): void {
    $mailer = new SendGridMailer(API_KEY); // Real SendGrid client
    $result = $mailer->send($email);       // Real HTTP call to SendGrid!
    $this->assertTrue($result->success);
    // Fails if: no internet, SendGrid down, API key invalid, rate limited
}

// Guzzle MockHandler — no HTTP in unit tests:
public function testSendConfirmationEmail(): void {
    $mock    = new MockHandler([new Response(202, [], json_encode(['id'=>'test-123']))]);
    $client  = new Client(['handler' => HandlerStack::create($mock)]);
    $mailer  = new SendGridMailer($client); // Injected mock client
    $result  = $mailer->send($email);
    $this->assertTrue($result->success);
    $this->assertSame('test-123', $result->messageId);
    // Fast, deterministic, no network, no side effects
}

References

• ↗ https://docs.stoplight.io/docs/prism/

Tags

Related Terms