Mock Servers for API Testing: Simulating External Dependencies

# WireMock can run as standalone JAR or embedded in tests
# Install: java -jar wiremock-standalone-3.x.jar --port 8080

# Python test with WireMock (via HTTP admin API)
import requests
import json

WIREMOCK_URL = "http://localhost:8080"

def setup_mock_stripe_charge():
    """Stub the Stripe charge API."""
    mapping = {
        "request": {
            "method": "POST",
            "url": "/v1/charges",
            "headers": {
                "Authorization": {
                    "matches": "Bearer sk_test_.*"
                }
            }
        },
        "response": {
            "status": 200,
            "json_body": {
                "id": "ch_mock_123",
                "object": "charge",
                "amount": 2999,
                "currency": "usd",
                "status": "succeeded",
                "outcome": {"network_status": "approved_by_network"}
            },
            "headers": {
                "Content-Type": "application/json"
            }
        }
    }
    resp = requests.post(
        f"{WIREMOCK_URL}/__admin/mappings",
        json=mapping
    )
    print(f"Stub created: {resp.status_code}")
    return mapping

setup_mock_stripe_charge()

# Now your app's Stripe calls go to WireMock instead of Stripe
# Your app would use: stripe.api_base = "http://localhost:8080"

# Dynamic response based on request body
def setup_dynamic_stub():
    mapping = {
        "request": {
            "method": "POST",
            "url": "/v1/charges"
        },
        "response": {
            "status": 200,
            "json_body": {
                "id": "{{randomValue length=20 type='ALPHANUMERIC'}}",
                "amount": "{{jsonPath request.body '$.amount'}}",
                "status": "{{#unless request.body.card}}failed{{else}}succeeded{{/unless}}",
                "created": "{{now}}"
            },
            "transformers": ["response-template"]
        }
    }
    requests.post(f"{WIREMOCK_URL}/__admin/mappings", json=mapping)

setup_dynamic_stub()

# Verify request was made to WireMock
def verify_mock_called():
    resp = requests.get(f"{WIREMOCK_URL}/__admin/requests")
    requests_data = resp.json()
    print(f"Requests made to mock: {len(requests_data['requests'])}")
    for req in requests_data["requests"]:
        print(f"  {req['request']['method']} {req['request']['url']}")

# verify_mock_called()
# Expected output:
# Requests made to mock: 1
#   POST /v1/charges

def setup_error_scenarios():
    """Configure different error responses."""

    # 500 Internal Server Error
    error_500 = {
        "request": {"method": "GET", "url": "/v1/payments/unstable"},
        "response": {
            "status": 500,
            "json_body": {
                "error": {"type": "api_error", "message": "Internal server error"}
            }
        }
    }
    requests.post(f"{WIREMOCK_URL}/__admin/mappings", json=error_500)

    # Timeout simulation (fixed delay)
    timeout_mapping = {
        "request": {"method": "GET", "url": "/v1/payments/slow"},
        "response": {
            "status": 200,
            "json_body": {"status": "ok"},
            "fixedDelayMilliseconds": 30000  # 30 second delay
        }
    }
    requests.post(f"{WIREMOCK_URL}/__admin/mappings", json=timeout_mapping)

    # Rate limiting
    rate_limit = {
        "request": {"method": "POST", "url": "/v1/charges"},
        "response": {
            "status": 429,
            "json_body": {
                "error": {"type": "rate_limit", "message": "Too many requests"}
            },
            "headers": {"Retry-After": "5"}
        }
    }
    requests.post(f"{WIREMOCK_URL}/__admin/mappings", json=rate_limit)

    # Connection reset (simulate network failure)
    socket_reset = {
        "request": {"method": "GET", "url": "/v1/payments/unreachable"},
        "response": {
            "fault": "CONNECTION_RESET_BY_PEER"
        }
    }
    requests.post(f"{WIREMOCK_URL}/__admin/mappings", json=socket_reset)

setup_error_scenarios()
print("Error scenarios configured")

# Test your app's error handling
# Your app should handle 500, timeout, 429, and connection reset gracefully

def setup_record_replay():
    """
    Record mode: proxy to real API and save responses.
    Replay mode: serve saved responses without real API.
    """

    # Record mode - proxy unmatched requests to real API
    record_config = {
        "request": {"method": "ANY", "urlPattern": "/api/.*"},
        "response": {
            "proxyBaseUrl": "https://api.real-service.com"
        },
        "persistent": True
    }
    # In WireMock: responses are automatically recorded when using proxy

    # Switch to stub mode after recording
    # WireMock serves recorded responses without hitting the real API

    print("Record-replay pattern:")
    print("  1. Start with proxy to record real responses")
    print("  2. Run tests once to capture responses")
    print("  3. Switch to stub mode (remove proxy mapping)")
    print("  4. Tests now use recorded responses offline")

# For Python tests, you can use responses library for record-replay
# Or VCR.py for recording HTTP interactions

# MockServer (Java) provides similar functionality
# Can be run as Docker container or embedded

# MockServer with Docker:
# docker run -d -p 1080:1080 mockserver/mockserver

# Python client for MockServer
import requests

MOCKSERVER_URL = "http://localhost:1080"

def setup_mockserver_expectation():
    expectation = {
        "httpRequest": {
            "method": "POST",
            "path": "/api/external/users",
            "headers": {
                "Authorization": {"values": ["Bearer test_token"]}
            }
        },
        "httpResponse": {
            "statusCode": 201,
            "body": json.dumps({
                "id": "mock-user-123",
                "email": "mock@example.com"
            }),
            "headers": {
                "Content-Type": ["application/json"]
            }
        },
        "times": {
            "unlimited": True
        }
    }
    resp = requests.put(
        f"{MOCKSERVER_URL}/mockserver/expectation",
        json=expectation
    )
    print(f"MockServer expectation: {resp.status_code}")

# setup_mockserver_expectation()