Testdriver:captcha Agent Skill

<!-- Generated from captcha.mdx. DO NOT EDIT. -->

Captcha Solving

TestDriver can automatically solve captchas during your tests using the 2captcha service. This feature works on both Linux and Windows sandboxes.

Quick Start

const result = await testdriver.captcha({
  apiKey: process.env.TWOCAPTCHA_API_KEY,
});

console.log(result.success); // true
console.log(result.token);   // The solved captcha token

That's it! TestDriver will automatically:

• Detect the captcha type on the page
• Extract the sitekey
• Solve the captcha via 2captcha
• Inject the token into the page
• Trigger any callbacks

Supported Captcha Types

| Type | Auto-Detected | Notes |

|------|---------------|-------|

| reCAPTCHA v2 | ✅ | Including invisible |

| reCAPTCHA v3 | ✅ | Action is auto-detected |

| hCaptcha | ✅ | |

| Cloudflare Turnstile | ✅ | |

Getting a 2captcha API Key

• Sign up at 2captcha.com
• Add funds to your account
• Copy your API key from the dashboard

Configuration Options

const result = await testdriver.captcha({
  // Required
  apiKey: '2CAPTCHA_API_KEY',

  // Optional - usually auto-detected
  sitekey: '6Le...',           // Override auto-detected sitekey
  type: 'recaptcha_v3',        // Override auto-detected type
  action: 'submit',            // reCAPTCHA v3 action

  // Timing
  timeout: 120000,             // Max wait time (default: 120s)
  pollInterval: 5000,          // Poll interval (default: 5s)
});

Full Example

import { describe, expect, it } from "vitest";
import { TestDriver } from "testdriver";

describe("Checkout flow", () => {
  it("should complete checkout with captcha", async (context) => {
    const testdriver = TestDriver(context);

    // Navigate to checkout page
    await testdriver.provision.chrome({
      url: 'https://example.com/checkout',
    });

    // Fill out form
    await testdriver.type({ text: 'John Doe', selector: '#name' });
    await testdriver.type({ text: '[email protected]', selector: '#email' });

    // Solve the captcha
    const result = await testdriver.captcha({
      apiKey: process.env.TWOCAPTCHA_API_KEY,
    });

    expect(result.success).toBe(true);

    // Submit the form
    await testdriver.click({ selector: '#submit' });

    // Verify success
    await testdriver.find({ text: 'Order confirmed' });
  }, 180000);
});

Environment Variables

You can set your API key as an environment variable:

export TWOCAPTCHA_API_KEY=your_api_key_here

Then use it in your tests:

const result = await testdriver.captcha({
  apiKey: process.env.TWOCAPTCHA_API_KEY,
});

GitHub Actions

Add the key to your repository secrets and expose it in your workflow:

- name: Run Tests
  run: vitest run
  env:
    TWOCAPTCHA_API_KEY: ${{ secrets.TWOCAPTCHA_API_KEY }}

How It Works

• Detection: Scans the page for captcha elements (data-sitekey, script tags, etc.)
• Submit: Sends the captcha challenge to 2captcha's solving service
• Poll: Waits for human solvers to complete the captcha
• Inject: Injects the solved token into the page's hidden fields
• Callback: Triggers any JavaScript callbacks the page expects

Troubleshooting

"Could not auto-detect captcha"

The captcha element wasn't found on the page. Try:

• Waiting for the page to fully load before calling captcha()
• Providing the sitekey and type manually

Timeout errors

Captcha solving typically takes 10-30 seconds. If you're getting timeouts:

• Increase the timeout option
• Check your 2captcha balance
• Verify the captcha type is correct

Token not working

Some sites validate tokens immediately. Make sure:

• The token is injected before form submission
• The captcha type matches what the site expects
• For reCAPTCHA v3, the action parameter matches the site's expected action

Requirements

• Chrome must be launched with remote debugging enabled (automatic on all sandboxes)
• A valid 2captcha API key with sufficient balance