playwright-captcha

Playwright Captcha

A Python library that makes captcha solving simple and automated with Playwright and Playwright-based frameworks. Just a few lines of code, and you're ready to go!

✨ What it does

This framework helps you solve captchas in Playwright or Playwright-based frameworks (like Camoufox or Patchright) automatically. It will:

• Detect the captcha on your page
• Solve it using your preferred method
• Apply the solution automatically
• Submit the form (when needed & possible)

📸 Demonstration (recorded in headless mode)

Click Solver

Cloudflare Interstitial

https://github.com/user-attachments/assets/06c244ff-ba82-4d8a-9ef8-17ece400716c

Cloudflare Turnstile

https://github.com/user-attachments/assets/52b49abd-5aa4-4262-9cb6-a555a95330c9

TwoCaptcha Solver

Cloudflare Interstitial

https://github.com/user-attachments/assets/25a6233b-43fb-4164-b41c-ea80100b501d

Cloudflare Turnstile

https://github.com/user-attachments/assets/0f3f7999-1e0d-437e-9727-36a99a6c5abd

ReCaptcha V2

https://github.com/user-attachments/assets/37b5d9b0-7c32-49b3-9c22-ffe0258161d1

ReCaptcha V3

https://github.com/user-attachments/assets/7fc7d508-be87-4c60-aaf8-ab445601e69c

⚠️ LEGAL DISCLAIMER

THIS TOOL IS PROVIDED FOR EDUCATIONAL AND RESEARCH PURPOSES ONLY

This software is designed to demonstrate security concepts and should not be used to bypass protections on websites without explicit permission from the website owner. Using this tool against websites without authorization may violate:

• The Computer Fraud and Abuse Act (CFAA)
• Terms of Service agreements
• Various cybersecurity laws in your jurisdiction

🚀 Supported Captcha Types

Click Solver

Uses the browser's stealthiness to automatically click and solve captchas (works good only with playwright's stealthy patches e.g. camoufox/patchright):

• ✅ Cloudflare Interstitial
• ✅ Cloudflare Turnstile

TwoCaptcha Solver

Uses the 2Captcha.com API for solving:

• ✅ Cloudflare Interstitial
• ✅ Cloudflare Turnstile
• ✅ reCAPTCHA v2
• ✅ reCAPTCHA v3

More captcha types and solvers coming soon! Contributions welcome.

📦 Installation

pip install playwright-captcha

🔧 Quick Start

Check out the examples directory for detailed usage examples:

• Cloudflare Examples: Turnstile and Interstitial challenges
• reCAPTCHA Examples: v2 and v3 implementations

Each example includes configurations for Playwright, Patchright, and Camoufox.

Click Solver Example

import asyncio
from playwright.async_api import async_playwright
from playwright_captcha import CaptchaType, ClickSolver, FrameworkType

async def solve_captcha():
    async with async_playwright() as playwright:
        browser = await playwright.chromium.launch(headless=True)
        page = await browser.new_page()
        
        framework = FrameworkType.PLAYWRIGHT
        
        # Create solver before navigating to the page
        async with ClickSolver(framework=framework, page=page) as solver:
            # Navigate to your target page
            await page.goto('https://example.com/with-captcha')
            
            # Solve the captcha
            await solver.solve_captcha(
                captcha_container=page,
                captcha_type=CaptchaType.CLOUDFLARE_TURNSTILE
            )
        
        # Continue with your automation...

asyncio.run(solve_captcha())

TwoCaptcha Solver Example

import asyncio
import os
from playwright.async_api import async_playwright
from twocaptcha import AsyncTwoCaptcha
from playwright_captcha import CaptchaType, TwoCaptchaSolver, FrameworkType

async def solve_with_2captcha():
    # Initialize 2Captcha client
    captcha_client = AsyncTwoCaptcha(os.getenv('TWO_CAPTCHA_API_KEY'))
    
    async with async_playwright() as playwright:
        browser = await playwright.chromium.launch(headless=False)
        page = await browser.new_page()
                
        framework = FrameworkType.PLAYWRIGHT
        
        # Create solver before navigating to the page
        async with TwoCaptchaSolver(framework=framework, 
                                    page=page, 
                                    async_two_captcha_client=captcha_client) as solver:
            # Navigate to your target page
            await page.goto('https://example.com/with-recaptcha')
        
            # Solve reCAPTCHA v2
            await solver.solve_captcha(
                captcha_container=page,
                captcha_type=CaptchaType.RECAPTCHA_V2
            )
        
        # Continue with your automation...

asyncio.run(solve_with_2captcha())

🎯 How It Works

Click Solver Process:

• Find the captcha element on the page
• Click on it using browser automation
• Wait for successful completion

External Solver Process (e.g., TwoCaptcha):

• Find the captcha element
• Extract required data (site key, URL, etc.)
• Send to external solving service
• Apply the returned solution
• Submit the form (when applicable)

🗺️ TODO

🎯 Next Captcha Types

• hCaptcha

🔧 New Solver Types

• CapSolver
• AI Solver

Other

• Unit & Integration Tests

🌐 Browser Compatibility

Standard Playwright

Works with all standard Playwright browsers (Chrome, Firefox, Safari).

Stealth Browsers

For better success rates, especially with click-based solving:

Patchright

from patchright.async_api import async_playwright
from playwright_captcha import FrameworkType

async with async_playwright() as playwright:
    browser = await playwright.chromium.launch(channel="chrome", headless=False)
    
    framework = FrameworkType.PATCHRIGHT
    
    # ... rest of your code

Camoufox

from camoufox import AsyncCamoufox
from playwright_captcha.utils.camoufox_add_init_script.add_init_script import get_addon_path
from playwright_captcha import FrameworkType
import os

ADDON_PATH = get_addon_path()

async with AsyncCamoufox(
    headless=False,
    geoip=True,
    humanize=True,
    main_world_eval=True, # add this
    addons=[os.path.abspath(ADDON_PATH)] # add this
) as browser:
    context = await browser.new_context()
    page = await context.new_page()
    
    framework = FrameworkType.CAMOUFOX
    
    # ... rest of your code

Note: Camoufox currently has an issue with the add_init_script method. I've included a temporary workaround that's automatically used in the package. See the examples folder for details.

📁 Project Structure

playwright-captcha/
├── examples/                   # Usage examples
│   ├── cloudflare/             # Cloudflare captcha examples
│   └── recaptcha/              # reCAPTCHA examples
└── playwright_captcha/         # Main package
    ├── captchas/               # Captcha type implementations
    ├── solvers/                # Solver implementations
    ├── types/                  # Type definitions
    └── utils/                  # Utility functions

🔧 Configuration

Environment Variables

(Optional) Create a .env file for your API keys:

TWO_CAPTCHA_API_KEY=your_2captcha_api_key_here

Solver Options

# Click solver with custom settings
solver = ClickSolver(
    framework=framework, # Framework type (PLAYWRIGHT, PATCHRIGHT, CAMOUFOX)
    page=page,
    max_attempts=5,      # Number of solving attempts
    attempt_delay=3      # Delay between attempts (seconds)
)

# TwoCaptcha solver with custom settings  
solver = TwoCaptchaSolver(
    framework=framework, # Framework type (PLAYWRIGHT, PATCHRIGHT, CAMOUFOX)
    page=page,
    async_two_captcha_client=captcha_client,
    max_attempts=3,
    attempt_delay=10,
    
    # also you can specify the captcha data like sitekey manually if it fails to detect automatically
    sitekey='sitekey'
    # ...
)

🆘 Support

• 📖 Check the examples folder for usage patterns
• 🐛 Report issues or request features on GitHub Issues