wiremock

# setup-wiremock.sh — Run WireMock as a standalone server.
# Download and start with file-based stub mappings.

# Docker (recommended)
docker run -d --name wiremock \
  -p 8080:8080 \
  -v $(pwd)/wiremock:/home/wiremock \
  wiremock/wiremock:3.5.4

// wiremock/mappings/get-user.json — WireMock stub for GET /api/users/:id.
// Returns a user object with response templating.
{
  "request": {
    "method": "GET",
    "urlPathPattern": "/api/users/[0-9]+"
  },
  "response": {
    "status": 200,
    "headers": {
      "Content-Type": "application/json"
    },
    "jsonBody": {
      "id": "{{request.pathSegments.[2]}}",
      "name": "Jane Doe",
      "email": "jane@example.com"
    },
    "transformers": ["response-template"]
  }
}

// wiremock/mappings/create-user.json — WireMock stub for POST /api/users.
// Matches on request body content and returns created user.
{
  "request": {
    "method": "POST",
    "urlPath": "/api/users",
    "headers": {
      "Content-Type": { "equalTo": "application/json" }
    },
    "bodyPatterns": [
      { "matchesJsonPath": "$.name" },
      { "matchesJsonPath": "$.email" }
    ]
  },
  "response": {
    "status": 201,
    "headers": { "Content-Type": "application/json" },
    "jsonBody": {
      "id": "{{randomValue type='UUID'}}",
      "name": "{{jsonPath request.body '$.name'}}",
      "email": "{{jsonPath request.body '$.email'}}"
    },
    "transformers": ["response-template"]
  }
}

// wiremock/mappings/fault-injection.json — WireMock stubs for resilience testing.
// Simulates slow responses, connection resets, and variable latency.
{
  "mappings": [
    {
      "request": { "method": "GET", "urlPath": "/api/slow" },
      "response": {
        "status": 200,
        "fixedDelayMilliseconds": 5000,
        "jsonBody": { "data": "delayed" }
      }
    },
    {
      "request": { "method": "GET", "urlPath": "/api/flaky" },
      "response": {
        "fault": "CONNECTION_RESET_BY_PEER"
      }
    },
    {
      "request": { "method": "GET", "urlPath": "/api/random-delay" },
      "response": {
        "status": 200,
        "delayDistribution": {
          "type": "lognormal",
          "median": 200,
          "sigma": 0.4
        },
        "jsonBody": { "data": "variable latency" }
      }
    }
  ]
}

# record-api.sh — Use WireMock to record real API traffic.
# Proxies requests to the real API and saves responses as stubs.

# Start in record mode
docker run -d --name wiremock-recorder \
  -p 8080:8080 \
  -v $(pwd)/wiremock:/home/wiremock \
  wiremock/wiremock:3.5.4 \
  --proxy-all="https://api.example.com" \
  --record-mappings

# Make requests through WireMock (they get recorded)
curl http://localhost:8080/api/users
curl http://localhost:8080/api/products?category=electronics

# Stop recording — stubs are saved in wiremock/mappings/
docker stop wiremock-recorder

// wiremock/mappings/stateful-order.json — WireMock stateful scenario.
// Simulates an order that changes state: pending -> confirmed -> shipped.
{
  "mappings": [
    {
      "scenarioName": "Order Lifecycle",
      "requiredScenarioState": "Started",
      "newScenarioState": "Order Placed",
      "request": { "method": "POST", "urlPath": "/api/orders" },
      "response": {
        "status": 201,
        "jsonBody": { "id": "ord-123", "status": "pending" }
      }
    },
    {
      "scenarioName": "Order Lifecycle",
      "requiredScenarioState": "Order Placed",
      "newScenarioState": "Order Confirmed",
      "request": { "method": "GET", "urlPath": "/api/orders/ord-123" },
      "response": {
        "status": 200,
        "jsonBody": { "id": "ord-123", "status": "confirmed" }
      }
    },
    {
      "scenarioName": "Order Lifecycle",
      "requiredScenarioState": "Order Confirmed",
      "request": { "method": "GET", "urlPath": "/api/orders/ord-123" },
      "response": {
        "status": 200,
        "jsonBody": { "id": "ord-123", "status": "shipped" }
      }
    }
  ]
}

# wiremock-api.sh — Create stubs via WireMock's admin API at runtime.
# Useful for dynamic test setup.

# Create a stub
curl -X POST http://localhost:8080/__admin/mappings \
  -H 'Content-Type: application/json' \
  -d '{
    "request": { "method": "GET", "urlPath": "/api/health" },
    "response": { "status": 200, "jsonBody": { "status": "ok" } }
  }'

# List all stubs
curl http://localhost:8080/__admin/mappings

# Reset all stubs
curl -X POST http://localhost:8080/__admin/reset

# .github/workflows/wiremock.yml — Run tests against WireMock in CI.
# Uses Docker service container.
name: Integration Tests
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    services:
      wiremock:
        image: wiremock/wiremock:3.5.4
        ports:
          - 8080:8080
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm test
        env:
          MOCK_API_URL: http://localhost:8080