{"id":50805028,"url":"https://github.com/arun0009/flakymock","last_synced_at":"2026-06-13T00:04:40.940Z","repository":{"id":363015709,"uuid":"1261659572","full_name":"arun0009/flakymock","owner":"arun0009","description":"HTTP mock server for resilience testing — retries, circuit breakers, latency, rate limits","archived":false,"fork":false,"pushed_at":"2026-06-07T02:10:07.000Z","size":161,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-07T03:41:38.997Z","etag":null,"topics":["chaos-engineering","circuit-breaker","go","integration-testing","mock-server","resilience-testing","retry","testcontainers"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arun0009.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-07T01:41:49.000Z","updated_at":"2026-06-07T02:10:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/arun0009/flakymock","commit_stats":null,"previous_names":["arun0009/flakymock"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/arun0009/flakymock","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arun0009%2Fflakymock","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arun0009%2Fflakymock/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arun0009%2Fflakymock/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arun0009%2Fflakymock/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arun0009","download_url":"https://codeload.github.com/arun0009/flakymock/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arun0009%2Fflakymock/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34266932,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chaos-engineering","circuit-breaker","go","integration-testing","mock-server","resilience-testing","retry","testcontainers"],"created_at":"2026-06-13T00:04:38.757Z","updated_at":"2026-06-13T00:04:40.925Z","avatar_url":"https://github.com/arun0009.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"docs/flakymock.png\" alt=\"FlakyMock Mascot\" width=\"200\"/\u003e\n\u003c/div\u003e\n\n\u003ch1 align=\"center\"\u003eFlakyMock\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eStub the API. Break it on purpose. Assert your client handled it.\u003c/strong\u003e\u003cbr\u003e\n  One HTTP mock server for integration tests — delays, 503s, 429s, circuit breakers, and call verification.\n\u003c/p\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n[![Go Report Card](https://goreportcard.com/badge/github.com/arun0009/flakymock)](https://goreportcard.com/report/github.com/arun0009/flakymock)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Go Version](https://img.shields.io/github/go-mod/go-version/arun0009/flakymock)](https://golang.org/)\n\n\u003c/div\u003e\n\n---\n\n## The problem\n\nWireMock is great at returning the response you asked for. **FlakyMock is for when the downstream misbehaves.**\n\nRun 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.\n\n\u003e Not sure if this fits your stack? See [FlakyMock vs WireMock](docs/comparison.md).\n\n---\n\n## Quick start\n\n```bash\ndocker run -p 8080:8080 arun0009/flakymock:latest\n```\n\n**Zero-config fault** — no YAML, just headers:\n\n```bash\ncurl -i \"http://localhost:8080/echo\" \\\n  -H \"X-Echo-Delay: 500ms\" \\\n  -H \"X-Echo-Status: 503\"\n```\n\n**Stateful retry sequence** — fail twice, then succeed:\n\n```bash\ncurl -X POST http://localhost:8080/scenario \\\n  -H \"Content-Type: application/json\" \\\n  -d '[{\"path\":\"/users\",\"method\":\"GET\",\"responses\":[{\"status\":503},{\"status\":503},{\"status\":200}]}]'\n\ncurl -i http://localhost:8080/users   # 503\ncurl -i http://localhost:8080/users   # 503\ncurl -i http://localhost:8080/users   # 200\n```\n\n**Assert retries in tests** — did the client call enough times?\n\n```bash\ncurl -s \"http://localhost:8080/api/verify/requests?path=/users\u0026method=GET\u0026min=3\"\n# {\"count\":3,\"matched\":true,...}\n```\n\n**Reset for the next test run:**\n\n```bash\ncurl -X POST \"http://localhost:8080/api/control/reset-scenarios?path=/users\u0026method=GET\"\n```\n\nFull walkthrough: **[Resilience Testing Example](docs/resilience-testing-example.md)** (~10 min).\n\n---\n\n## When to use FlakyMock\n\n| Choose **FlakyMock** | Choose **WireMock** |\n|----------------------|---------------------|\n| Retries, timeouts, circuit breakers | Org-wide general API mocking |\n| Stateful sequences (fail N, then succeed) | Record/playback from real traffic |\n| Header-driven faults without config | Mature ecosystem and cloud offering |\n| Built-in verify + reset for CI | You already run WireMock everywhere |\n\n---\n\n## Test in CI\n\nCopy-paste integration test with [testcontainers-go](examples/testcontainers/):\n\n```bash\ncd examples/testcontainers\ngo test -tags=integration -v .\n```\n\nStarts FlakyMock from the repo Dockerfile, runs a 503→503→200 scenario, verifies call count, resets state.\n\n---\n\n## Recipes\n\nMount a file and go — pre-built scenarios in `recipes/`:\n\n```bash\n# Slow / flaky storage\ndocker run -p 8080:8080 \\\n  -v $(pwd)/recipes/aws-s3-slow.yaml:/scenarios.yaml \\\n  arun0009/flakymock:latest\n\n# Circuit breaker: healthy → spike → recovery\n# recipes/generic-circuit-breaker.yaml\n\n# Rate limit with Retry-After\n# recipes/stripe-rate-limit.yaml\n```\n\n---\n\n## Features\n\n**Mocking**\n- Path, method, header, query, and JSON body matching\n- Dynamic scenarios via `POST /scenario`; YAML on startup\n- File persistence under `SCENARIO_ROOT_DIR/mappings/`\n\n**Fault injection**\n- Stateful response sequences and probability-based faults\n- Delay jitter (`delayRange: \"200ms-500ms\"`)\n- Circuit breaker simulation (closed → open → half-open)\n- Chaos headers on `/echo` (`X-Echo-Delay`, `X-Echo-Status`)\n\n**Test assertions**\n- `GET /api/verify/requests` — count calls, filter by body/headers/status\n- `POST /api/verify/sequence` — assert call order\n- `POST /api/control/reset-scenarios` — repeatable CI runs\n\n**Ops**\n- Prometheus metrics at `/metrics`\n- Request history, replay, WebSocket/SSE testers\n- CPU/memory stress endpoints for neighbor testing\n\n---\n\n## Install\n\n```bash\n# Docker (recommended)\ndocker run -p 8080:8080 arun0009/flakymock:latest\n\n# Go\ngo install github.com/arun0009/flakymock@latest\n```\n\n---\n\n## Docs\n\n| Doc | What you'll find |\n|-----|------------------|\n| [Resilience Testing Example](docs/resilience-testing-example.md) | End-to-end retry demo |\n| [Comparison](docs/comparison.md) | FlakyMock vs WireMock |\n| [Scenarios](docs/scenarios.md) | YAML reference |\n| [API Reference](docs/api_reference.md) | Endpoints |\n| [Configuration](docs/configuration.md) | Environment variables |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farun0009%2Fflakymock","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farun0009%2Fflakymock","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farun0009%2Fflakymock/lists"}