Stub the API. Break it on purpose. Assert your client handled it.
One HTTP mock server for integration tests — delays, 503s, 429s, circuit breakers, and call verification.

WireMock is great at returning the response you asked for. FlakyMock is for when the downstream misbehaves.

Run it as a Docker sidecar and pretend to be Stripe, S3, or a legacy API that flakes — then prove your app retried, backed off, or tripped a circuit breaker. No second chaos tool. Any language can hit it over HTTP.

Not sure if this fits your stack? See FlakyMock vs WireMock.

docker run -p 8080:8080 arun0009/flakymock:latest

Zero-config fault — no YAML, just headers:

curl -i "http://localhost:8080/echo" \
  -H "X-Echo-Delay: 500ms" \
  -H "X-Echo-Status: 503"

Stateful retry sequence — fail twice, then succeed:

curl -X POST http://localhost:8080/scenario \
  -H "Content-Type: application/json" \
  -d '[{"path":"/users","method":"GET","responses":[{"status":503},{"status":503},{"status":200}]}]'

curl -i http://localhost:8080/users   # 503
curl -i http://localhost:8080/users   # 503
curl -i http://localhost:8080/users   # 200

Assert retries in tests — did the client call enough times?

curl -s "http://localhost:8080/api/verify/requests?path=/users&method=GET&min=3"
# {"count":3,"matched":true,...}

Reset for the next test run:

curl -X POST "http://localhost:8080/api/control/reset-scenarios?path=/users&method=GET"

Full walkthrough: Resilience Testing Example (~10 min).

Copy-paste integration test with testcontainers-go:

cd examples/testcontainers
go test -tags=integration -v .

Starts FlakyMock from the repo Dockerfile, runs a 503→503→200 scenario, verifies call count, resets state.

Mount a file and go — pre-built scenarios in recipes/:

# Slow / flaky storage
docker run -p 8080:8080 \
  -v $(pwd)/recipes/aws-s3-slow.yaml:/scenarios.yaml \
  arun0009/flakymock:latest

# Circuit breaker: healthy → spike → recovery
# recipes/generic-circuit-breaker.yaml

# Rate limit with Retry-After
# recipes/stripe-rate-limit.yaml

Mocking

• Path, method, header, query, and JSON body matching
• Dynamic scenarios via POST /scenario; YAML on startup
• File persistence under SCENARIO_ROOT_DIR/mappings/

Fault injection

• Stateful response sequences and probability-based faults
• Delay jitter (delayRange: "200ms-500ms")
• Circuit breaker simulation (closed → open → half-open)
• Chaos headers on /echo (X-Echo-Delay, X-Echo-Status)

Test assertions

• GET /api/verify/requests — count calls, filter by body/headers/status
• POST /api/verify/sequence — assert call order
• POST /api/control/reset-scenarios — repeatable CI runs

Ops

• Prometheus metrics at /metrics
• Request history, replay, WebSocket/SSE testers
• CPU/memory stress endpoints for neighbor testing

# Docker (recommended)
docker run -p 8080:8080 arun0009/flakymock:latest

# Go
go install github.com/arun0009/flakymock@latest