Playwright · Python
page.goto(target_url)
detect_captchas()
CAPTCHA detectedsupported challenge found on the page
solve_on_page(autofill=True)opt-in solving request · authorized workflow
result returned + autofilled
script continues
Agent Automation · Playwright
Add CAPTCHA solving to Playwright Agents
Give Playwright-based AI agents a way to handle supported CAPTCHAs. CapSolver Agent Tools can detect a challenge and, when solving is enabled, return and autofill the result so an authorized Python workflow can continue.
How it works
How CAPTCHA solving works with Playwright
Use CapSolver Agent Tools to detect supported CAPTCHAs, solve them when enabled, and autofill the result so your authorized Playwright workflow can continue.
01
Detect
CAPTCHA iframe or widget appears
02
Solve
createTask → getTaskResult
03
Inject
page.evaluate(token)
04
Continue
Submit form, proceed
When to use
Where Playwright-based AI agents use CapSolver
QA Test Automation
Handle CAPTCHAs in authorized staging and production tests to reduce interrupted test runs.
RPA Workflows
Keep data entry, order processing, reporting, and other browser workflows running when a CAPTCHA appears.
Data Extraction
Web scraping and data collection from sites with bot protection — public data that gets gated by reCAPTCHA or Cloudflare Turnstile.
Custom Browser Agents
Build custom AI browser agents with Playwright that can solve CAPTCHAs and continue their tasks.
Quick Start
Add CAPTCHA solving to Playwright
Choose automatic handling for a faster setup, or use token mode when you need more control over the CAPTCHA result.
playwright_sdk.py
# pip install capsolver-core playwright
# playwright install chromium
# export CAPSOLVER_API_KEY=CAP-XXXXXX
import asyncio
import os
from playwright.async_api import async_playwright
from capsolver_core import Capsolver, from_playwright_page
from _env import load_example_env # demo only: reads repo-root .env
load_example_env()
async def main():
async with async_playwright() as pw:
browser = await pw.chromium.launch(headless=False)
page = await browser.new_page()
await page.goto("https://www.google.com/recaptcha/api2/demo")
cap = Capsolver(api_key=os.environ["CAPSOLVER_API_KEY"])
driver = from_playwright_page(page) # wrap the live Playwright page
results = await cap.solve_on_page(driver) # detect -> solve -> autofill
for r in results:
status = "solved" if r.solution else "failed"
print(r.info.type.value, status, "filled:", r.filled)
await page.click('#recaptcha-demo-submit')
await page.wait_for_selector(".recaptcha-success")
print("Verification successful!")
await browser.close()
asyncio.run(main())
Token Injection
Different CAPTCHAs, different injection fields.
Each CAPTCHA type stores the token in a different DOM element. Here's how to inject for the most common types.
# pip install capsolver-core playwright
# playwright install chromium
# export CAPSOLVER_API_KEY=CAP-XXXXXX
#
# reCAPTCHA v2 token injection -> #g-recaptcha-response
# handler.fill() writes the token and fires the widget callback for you.
import asyncio
import os
from playwright.async_api import async_playwright
from capsolver_core import Capsolver, CaptchaInfo, CaptchaType, from_playwright_page
from _env import load_example_env # demo only: reads repo-root .env
load_example_env()
URL = "https://www.google.com/recaptcha/api2/demo"
SITE_KEY = "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
async def main():
async with async_playwright() as pw:
browser = await pw.chromium.launch(headless=False)
page = await browser.new_page()
await page.goto(URL)
cap = Capsolver(api_key=os.environ["CAPSOLVER_API_KEY"])
driver = from_playwright_page(page)
info = CaptchaInfo(
type=CaptchaType.RECAPTCHA_V2, website_url=URL, website_key=SITE_KEY
)
solution = await cap.solve(info)
filled = await cap.get_handler(info.type).fill(driver, solution, info)
print(f"filled={filled} token={solution.token[:40]}...")
await browser.close()
asyncio.run(main())CAPTCHA coverage
CAPTCHA types available for Playwright agents
Use CapSolver with Playwright to handle common reCAPTCHA and Cloudflare Turnstile challenges.
CAPTCHA type
Task type
Injection selector
Status
reCAPTCHA v2
ReCaptchaV2TaskProxyLess
#g-recaptcha-response
Supported
reCAPTCHA v3
ReCaptchaV3TaskProxyLess
submitted with request
Supported
reCAPTCHA Enterprise
ReCaptchaV2EnterpriseTaskProxyLess
#g-recaptcha-response
Supported
Cloudflare Turnstile
AntiTurnstileTaskProxyLess
[name="cf-turnstile-response"]
Supported
Production Best Practices
Tips for reliable CAPTCHA handling in production.
Check before solving
01Only call CapSolver when a CAPTCHA is actually present. Check for iframe or widget existence first.
Set a timeout
02Set a reasonable timeout (30-60s) and retry with backoff if getTaskResult takes too long.
Handle results clearly
03Apply the returned result correctly and define what the workflow should do when solving does not complete.
Respect rate limits
04When running parallel browser contexts, throttle CapSolver calls to stay within your plan's limits.
Log CAPTCHA encounters
05Record the task ID, CAPTCHA type, result status, and errors for each solve attempt.
Secure your API key
06Store your CapSolver API key in environment variables or a secret manager.
Responsible use
Use CapSolver for responsible automation
CapSolver is designed for authorized automation use cases: QA testing, RPA on systems you have permission to access, public data collection, and compliant automation tasks. We do not support or condone unauthorized access, credential stuffing, spam, or any activity that violates terms of service or applicable laws.
Many legitimate automated workflows are incorrectly flagged as bots. CapSolver helps you recover from false-positive CAPTCHA challenges when you have a valid reason to automate.
FAQ
Related Integrations
Explore more CapSolver integrations for your agent stack
Choose another integration to add CAPTCHA solving to your agent or browser workflow.
Add CAPTCHA solving to your Playwright agents
Get your API key, follow the Python integration guide, and add CapSolver to your Playwright workflow.