CaptchaSonic Playwright Examples — Solve Any Captcha in TypeScript

Automate captcha solving with Playwright and the CaptchaSonic API. Works with reCAPTCHA v2, reCAPTCHA v3, Cloudflare Turnstile, Geetest v4, AWS WAF, and image captchas.

---

Quick Start

# 1. Clone and install
git clone https://github.com/Captcha-Sonic/playwright-solver.git
cd captchasonic-playwright-examples
npm install

# 2. Install Playwright browsers
npx playwright install chromium

# 3. Configure your API key
cp .env.example .env
# Edit .env and add your API key

# 4. Run any example
npm run recaptcha-v2

Get your API key at captchasonic.com.

---

Supported Captcha Types

Captcha	Token Method	Script Method	Run Command
reCAPTCHA v2	✅	✅	npm run recaptcha-v2
reCAPTCHA v3	✅	—	npm run recaptcha-v3
Cloudflare Turnstile	✅	—	npm run turnstile
Geetest v4	✅	✅	npm run geetest
AWS WAF	✅	✅	npm run aws-waf
Image Captcha (OCR)	✅	—	npm run image-captcha
Popular Captcha	✅	✅	npm run popularcaptcha

---

Two Ways to Solve

Token Method (token-method.ts)

Uses the CaptchaSonic API to solve captchas server-side — no visible browser interaction needed.

Your script → CaptchaSonic API → returns token → inject into page → submit

import { chromium } from 'playwright';
import { CaptchaSonic } from 'captchasonic';

const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('https://example.com/login');

const client = new CaptchaSonic(process.env.CAPTCHASONIC_API_KEY);
const result = await client.solveRecaptchaV2Token({
  websiteURL: 'https://example.com/login',
  websiteKey: '6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-',
});

await page.evaluate((token) => {
  (document.querySelector('#g-recaptcha-response') as HTMLTextAreaElement).value = token;
  document.querySelector('form')!.submit();
}, result.solution.gRecaptchaResponse);

Best for: headless automation, CI/CD pipelines, maximum speed (5–15s)

Script Method (script-method.ts)

Injects lightweight JS scripts into the page that detect, extract, and click captcha challenges using the CaptchaSonic image classification API.

Inject script → detect captcha → extract images → SDK classifies → inject clicks

import { ScriptSolver } from '../shared/solver';

const solver = new ScriptSolver(challengeFrame, client);
const result = await solver.solve('popularcaptcha', { timeout: 120, maxRetries: 5 });

Best for: Popular Captcha, Geetest, AWS WAF, and any visual challenge captcha

	Token Method	Script Method
How it works	API returns bypass token	JS extracts tiles → SDK classifies → JS clicks
Speed	⚡ 5–15 seconds	🐢 30–60 seconds per round
Best for	reCAPTCHA v2/v3, Turnstile	Popular Captcha, Geetest, AWS WAF
Recommended	✅ Start here	When token method is unavailable

---

AI / Agent Implementation Guide

If you are an AI agent or LLM-based tool integrating CaptchaSonic into a Playwright workflow, follow this protocol:

Architecture

┌──────────────────┐     ┌────────────────┐     ┌────────────────┐
│  Playwright Page │────▶│  ScriptSolver  │────▶│ CaptchaSonic   │
│  (browser ctrl)  │◀────│  (orchestrator)│◀────│ SDK (gRPC/HTTP) │
└──────────────────┘     └────────────────┘     └────────────────┘
         ↕                       ↕
   Page / frames          JS scripts (detect/
                          extract/inject)

Token Method — Step by Step

1. Initialize SDK: const client = new CaptchaSonic(apiKey)
2. Navigate: await page.goto(targetUrl)
3. Solve: Call the appropriate client.solve*Token({ websiteURL, websiteKey }) method
4. Extract token: result.solution.gRecaptchaResponse (or .token or .['cf-turnstile-response'])
5. Inject: Use shared/helpers.ts → injectRecaptchaToken(page, token) or injectTurnstileToken(page, token)
6. Submit form: await page.click('button[type="submit"]')

Script Method — Step by Step

1. Initialize SDK: const client = new CaptchaSonic(apiKey)
2. Navigate to target page and wait for captcha iframe
3. Find challenge frame: Use page.frames() to locate the challenge iframe (look for challenge in URL)
4. Create solver: const solver = new ScriptSolver(challengeFrame, client)
5. Solve: const result = await solver.solve('popularcaptcha', { timeout: 120, maxRetries: 5 })
6. Check result: result.solved → true means captcha is complete

ScriptSolver Lifecycle (Internal)

The solve() method runs this loop internally:

1. inject(script.js) → adds global object (e.g. CaptchaSonic_PopularCaptcha)
2. detect()          → returns {found, type, solved}
3. extract()         → returns {images[], question, questionType}
4. SDK call          → sends images to CaptchaSonic API → returns answers
5. inject(solution)  → clicks correct tiles / coordinates in DOM
6. Check solved      → if newChallenge, repeat from step 3

Supported Captcha Types for ScriptSolver

captchaType	JS Script	SDK Method
'popularcaptcha'	popularcaptcha.js	solvePopularCaptcha()
'recaptcha_v2'	recaptcha-v2.js	solveRecaptchaV2()
'geetest'	geetest.js	solveGeetest()
'aws_waf'	aws-waf.js	solveAwsWaf()

Key Files

File	Purpose
shared/solver.ts	ScriptSolver class — main orchestration logic
shared/helpers.ts	API key loading, token extraction, injection utilities
scripts/*.js	Vendored JS scripts for DOM detection/extraction/injection
examples/*/token-method.ts	Token-based solve (fastest, start here)
examples/*/script-method.ts	Script-based solve (visual captchas)

---

All Commands

# Token method (API-based)
npm run recaptcha-v2
npm run recaptcha-v3
npm run turnstile
npm run geetest
npm run aws-waf
npm run image-captcha
npm run popularcaptcha

# Script method (JS injection)
npm run recaptcha-v2:script
npm run geetest:script
npm run aws-waf:script
npm run popularcaptcha:script

---

Environment Variables

cp .env.example .env

CAPTCHASONIC_API_KEY=sonic_your_key_here

Variable	Required	Description
CAPTCHASONIC_API_KEY	✅	Your CaptchaSonic API key (sonic_xxx)

---

Adapt to Your Site

Each example targets a public demo page. To use on your own site:

1. Open any token-method.ts
2. Change SITE_URL to your target page
3. Change SITE_KEY to the captcha key on that page
4. Run the script

const SITE_URL = 'https://yoursite.com/login';
const SITE_KEY = 'your-site-key-here';

---

Project Structure

captchasonic-playwright-examples/
├── scripts/                            # Vendored JS captcha scripts
│   ├── popularcaptcha.js
│   ├── recaptcha-v2.js
│   ├── geetest.js
│   └── aws-waf.js
├── shared/
│   ├── helpers.ts                      # Reusable utilities
│   └── solver.ts                       # ScriptSolver bridge class
├── examples/
│   ├── recaptcha-v2/
│   │   ├── token-method.ts
│   │   └── script-method.ts
│   ├── recaptcha-v3/
│   │   └── token-method.ts
│   ├── turnstile/
│   │   └── token-method.ts
│   ├── geetest/
│   │   ├── token-method.ts
│   │   └── script-method.ts
│   ├── aws-waf/
│   │   ├── token-method.ts
│   │   └── script-method.ts
│   ├── image-captcha/
│   │   └── token-method.ts
│   └── popularcaptcha/
│       ├── token-method.ts
│       └── script-method.ts
├── package.json
└── tsconfig.json

---

Requirements

• Node.js ≥ 18
• Playwright — installed automatically via npm install
• CaptchaSonic API key — get one here

---

Resources

• CaptchaSonic Documentation
• CaptchaSonic Dashboard
• Playwright Documentation
• Puppeteer TypeScript Examples
• Selenium Python Examples

---

License

MIT — free to use in commercial projects.