{"id":49506984,"url":"https://github.com/captchaai/captchaai-workflow-doctor","last_synced_at":"2026-05-01T17:01:19.492Z","repository":{"id":354991509,"uuid":"1225941681","full_name":"CaptchaAI/captchaai-workflow-doctor","owner":"CaptchaAI","description":"Diagnostic CLI that walks a CAPTCHA-solving workflow end-to-end (CaptchaAI submit -\u003e poll -\u003e inject -\u003e callback -\u003e verify) and reports the exact root cause of failure. Supports Turnstile, reCAPTCHA v2/v3, Cloudflare Challenge.","archived":false,"fork":false,"pushed_at":"2026-05-01T09:18:03.000Z","size":139,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-01T11:15:12.201Z","etag":null,"topics":["automation-testing","captcha","captchaai","cli","cloudflare-challenge","cloudflare-turnstile","diagnostics","playwright","python","recaptcha"],"latest_commit_sha":null,"homepage":"https://github.com/CaptchaAI/captchaai-workflow-doctor","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CaptchaAI.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","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-04-30T20:06:25.000Z","updated_at":"2026-05-01T09:18:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/CaptchaAI/captchaai-workflow-doctor","commit_stats":null,"previous_names":["captchaai/captchaai-workflow-doctor"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/CaptchaAI/captchaai-workflow-doctor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CaptchaAI%2Fcaptchaai-workflow-doctor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CaptchaAI%2Fcaptchaai-workflow-doctor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CaptchaAI%2Fcaptchaai-workflow-doctor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CaptchaAI%2Fcaptchaai-workflow-doctor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CaptchaAI","download_url":"https://codeload.github.com/CaptchaAI/captchaai-workflow-doctor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CaptchaAI%2Fcaptchaai-workflow-doctor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32505110,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"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":["automation-testing","captcha","captchaai","cli","cloudflare-challenge","cloudflare-turnstile","diagnostics","playwright","python","recaptcha"],"created_at":"2026-05-01T17:00:36.406Z","updated_at":"2026-05-01T17:01:19.391Z","avatar_url":"https://github.com/CaptchaAI.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CaptchaAI Workflow Doctor\n\n\u003e Status: **Beta** — `v0.2.0` released (multi-CAPTCHA: Turnstile, reCAPTCHA v2/v3, Cloudflare Challenge). See [CHANGELOG.md](CHANGELOG.md), [ROADMAP.md](ROADMAP.md), and [PROGRESS.md](PROGRESS.md).\n\u003e\n\u003e 📖 **Read the guide:** [Why CAPTCHA Tokens Work in the API but Fail in the Browser](https://blog.captchaai.com/why-captcha-tokens-fail-in-browser) — the four token-handling constraints, with worked examples and a Python integration that satisfies all of them.\n\n![CaptchaAI Workflow Doctor](docs/assets/hero.png)\n\nA diagnostic CLI for debugging CAPTCHA-solving workflows from CaptchaAI\nAPI request to browser acceptance. Run one command, get a labeled\nroot cause and a one-line fix.\n\n```text\n$ captchaai-doctor run --profile profiles/checkout.yaml --ci --fail-on workflow\nstatus=failure root_cause=callback_not_invoked duration=4.71s report=run-artifacts/report.json html=run-artifacts/report.html\n```\n\n## What it does\n\nWhen the solver returns a token but your page still rejects the\nworkflow, doctor walks the full pipeline against a real Chromium\nbrowser — submit → poll → inject → invoke callback → submit → verify —\nand tells you *exactly* where it broke. See\n[docs/failure-taxonomy.md](docs/failure-taxonomy.md) for the 12\npossible root causes.\n\nEvery run produces:\n\n- `report.json` (validates against [the published JSON Schema](docs/report-schema.md))\n- `report.html` (single self-contained file with screenshots)\n- a Playwright trace and per-step screenshots\n\n## Responsible use\n\nDoctor is for systems you own, operate, or are explicitly authorized to\ntest. It is not for bypassing third-party CAPTCHAs. See\n[docs/responsible-use.md](docs/responsible-use.md).\n\n## Quickstart (10 minutes from a fresh checkout)\n\n```bash\ngit clone https://github.com/CaptchaAI/captchaai-workflow-doctor.git\ncd captchaai-workflow-doctor\npython -m venv .venv\n. .venv/bin/activate                    # Windows: .venv\\Scripts\\Activate.ps1\npip install -e \".[dev]\"\npython -m playwright install chromium\ncaptchaai-doctor --help\n```\n\n### Run the bundled demos (no API key required)\n\n```bash\ncaptchaai-doctor demo turnstile\ncaptchaai-doctor demo turnstile-invisible\ncaptchaai-doctor demo recaptcha-v2\ncaptchaai-doctor demo recaptcha-v3\ncaptchaai-doctor demo cloudflare-challenge\n```\n\nEach spins up a local Flask app, drives it through the full pipeline\nwith the fake CaptchaAI client, and writes\n`run-artifacts/demo-*/report.{json,html}`.\n\n### Run against your own profile + the real CaptchaAI API\n\n```bash\nexport CAPTCHAAI_API_KEY=...   # see .env.example\ncaptchaai-doctor run \\\n  --profile profiles/turnstile-generic.yaml \\\n  --artifact-dir run-artifacts/ \\\n  --ci --fail-on workflow\n```\n\n## Documentation\n\n- [Overview](docs/overview.md)\n- [Profile schema](docs/profile-schema.md) — write your own profile\n- [Failure taxonomy](docs/failure-taxonomy.md) — what each `root_cause` means\n- [Token lifecycle](docs/token-lifecycle.md) — the four constraints\n- [Report schema](docs/report-schema.md) — JSON shape + how to validate\n- [CI integration](docs/ci-integration.md) — wiring into your pipeline\n- [Architecture](docs/architecture.md) — module map\n- [Troubleshooting](docs/troubleshooting.md) — common gotchas\n- [Real-API evidence log](docs/real-e2e-evidence.md)\n\n## Supported CAPTCHA types\n\n| Type                  | Submit method (CaptchaAI)            | Demo command                                  |\n| --------------------- | ------------------------------------ | --------------------------------------------- |\n| Cloudflare Turnstile  | `turnstile`                          | `demo turnstile` / `demo turnstile-invisible` |\n| reCAPTCHA v2          | `userrecaptcha`                      | `demo recaptcha-v2`                           |\n| reCAPTCHA v3          | `userrecaptcha` (v3, action+score)   | `demo recaptcha-v3`                           |\n| Cloudflare Challenge  | `cloudflare_challenge` (proxy req'd) | `demo cloudflare-challenge`                   |\n\nSee [docs/profile-schema.md](docs/profile-schema.md) for the per-type\nprofile fields. Cloudflare Challenge requires a `proxy:` block because\nthe `cf_clearance` cookie is bound to the egress IP that solved it.\n\n## CLI\n\n```text\ncaptchaai-doctor run                       # run a profile end-to-end\ncaptchaai-doctor demo turnstile            # bundled Turnstile mock + driver\ncaptchaai-doctor demo turnstile-invisible\ncaptchaai-doctor demo recaptcha-v2\ncaptchaai-doctor demo recaptcha-v3\ncaptchaai-doctor demo cloudflare-challenge\ncaptchaai-doctor validate-profile \u003cpath\u003e\ncaptchaai-doctor schema [--output path]\n```\n\nExit codes follow [docs/ci-integration.md](docs/ci-integration.md):\n`0` ok · `1` workflow failure (with `--fail-on`) · `2` profile/usage error.\n\n## Sample reports\n\n`sample-reports/` contains ten fixtures rendered by\n`scripts/regenerate_sample_reports.py`:\n\n- `success` — happy path (Turnstile)\n- `verification-failed`\n- `callback-not-invoked`\n- `sitekey-not-found`\n- `captchaai-balance`\n- `turnstile-invisible-success`\n- `recaptcha-v3-success`\n- `recaptcha-v3-action-missing`\n- `cloudflare-challenge-success`\n- `cloudflare-proxy-misconfigured`\n\nOpen any `.html` to see what doctor produces in the wild.\n\n## Status \u0026 contributing\n\nSee [PROGRESS.md](PROGRESS.md) for the per-phase checklist,\n[ROADMAP.md](ROADMAP.md) for what's on deck, and\n[CONTRIBUTING.md](CONTRIBUTING.md) for the dev workflow.\n\n## Support\n\n- [SUPPORT.md](SUPPORT.md) — how to ask questions and report bugs.\n- [docs/sending-a-support-report.md](docs/sending-a-support-report.md)\n  — the redact-and-attach checklist for sending a `report.json`.\n- Account / billing / API-key questions go to\n  **`support@captchaai.com`** (not this repo).\n\n## Known limitations\n\n- **Cloudflare Challenge needs a residential proxy.** Cloudflare\n  binds the `cf_clearance` cookie to the egress IP that solved it,\n  so the doctor's CF Challenge profile requires a `proxy:` block.\n- **Headed mode (`--headed`) needs a local display.** On headless\n  CI runners, run without `--headed` and use the trace viewer for\n  step-through debugging.\n- **CAPTCHA tokens expire in ~120 seconds.** Workflows that pause\n  at a debugger or batch tokens for later submission will see\n  `token_expired_before_submit`. See\n  [docs/token-lifecycle.md](docs/token-lifecycle.md).\n\n## License\n\n- Source: **Apache-2.0** — see [LICENSE](LICENSE).\n- Attribution: see [NOTICE](NOTICE). Projects derived from or\n  substantially built on this repo are kindly asked to mention\n  **`captchaai.com`** in their README. (This is a request, not an\n  additional license condition.)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaptchaai%2Fcaptchaai-workflow-doctor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcaptchaai%2Fcaptchaai-workflow-doctor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaptchaai%2Fcaptchaai-workflow-doctor/lists"}