@testdriverai/agent 7.11.229-canary → 7.11.231-test

package/docs/captcha.mdx

@@ -1,159 +1,174 @@
 ---
 title: "captcha()"
 sidebarTitle: "captcha"
-description: "Solve captchas using 2captcha service"
+description: "Solve a reCAPTCHA, hCaptcha, or Cloudflare Turnstile on the page with the 2captcha service."
 icon: "shield-check"
 ---
 
-# Captcha Solving
-
-TestDriver can solve captchas automatically during your tests. It uses the 2captcha service. This feature works on **Linux** sandboxes and **Windows** sandboxes.
-
-## Quick Start
-
+Solve a captcha on the current page so your test can get past it. TestDriver uses the [2captcha](https://2captcha.com) solving service, so you need a 2captcha account and API key.
 
 ```javascript
-const result = await testdriver.captcha({
-  apiKey: process.env.TWOCAPTCHA_API_KEY,
-});
-
-console.log(result.success); // true
-console.log(result.token);   // The solved captcha token
+const result = await testdriver.captcha({ apiKey: process.env.TWOCAPTCHA_API_KEY });
 ```
 
-That is all. TestDriver does these automatically:
-- Finds the captcha type on the page
-- Gets the sitekey
-- Solves the captcha with 2captcha
-- Puts the token into the page
-- Starts the callbacks
+With no other options, `captcha()`:
 
-## Supported Captcha Types
+- Finds the captcha on the page and reads its sitekey.
+- Sends it to 2captcha and waits for the solution.
+- Puts the token into the page and calls the page's captcha callbacks.
+- Clicks the form's submit button.
 
-| Type | Auto-Detected | Notes |
-|------|---------------|-------|
-| reCAPTCHA v2 | ✅ | Including invisible |
-| reCAPTCHA v3 | ✅ | Action is auto-detected |
-| hCaptcha | ✅ | |
-| Cloudflare Turnstile | ✅ | |
+It works on Linux and Windows sandboxes, in Chrome opened with [`provision.chrome()`](/provision#chrome-options).
 
-## Getting a 2captcha API Key
+## Signature
 
-1. Sign up at [2captcha.com](https://2captcha.com)
-2. Add funds to your account
-3. Copy your API key from the dashboard
-
-## Configuration Options
-
-```javascript
-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)
-});
+```typescript
+testdriver.captcha(options: CaptchaOptions): Promise<CaptchaResult>
 ```
 
-## Full Example
-
-```javascript
-import { describe, expect, it } from "vitest";
-import { TestDriver } from "testdriver";
-
-describe("Checkout flow", () => {
-  it("should complete checkout with captcha", async (context) => {
+## Parameters
+
+<ParamField path="options" type="CaptchaOptions" required>
+  <Expandable title="properties">
+    <ParamField path="apiKey" type="string" required>
+      Your 2captcha API key. `captcha()` throws if it's missing.
+    </ParamField>
+    <ParamField path="sitekey" type="string">
+      The captcha's sitekey. When you leave it out, TestDriver finds the captcha and its type on the page. When you set it, also set `type`.
+    </ParamField>
+    <ParamField path="type" type="string" default="recaptcha_v3">
+      `'recaptcha_v2'`, `'recaptcha_v3'`, `'hcaptcha'`, or `'turnstile'`. Only used when you set `sitekey`. Otherwise the detected type is used.
+    </ParamField>
+    <ParamField path="action" type="string" default="verify">
+      The reCAPTCHA v3 action. Detected from the page when possible.
+    </ParamField>
+    <ParamField path="autoSubmit" type="boolean" default="true">
+      Click the form's submit button after the captcha is solved.
+    </ParamField>
+    <ParamField path="timeout" type="number" default="120000">
+      How long to wait for 2captcha's solution, in milliseconds.
+    </ParamField>
+    <ParamField path="pollInterval" type="number" default="5000">
+      How often to check 2captcha for the solution, in milliseconds.
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+### Captchas it detects
+
+| Captcha | Detected from |
+| --- | --- |
+| reCAPTCHA v2, including invisible | The `g-recaptcha` element |
+| reCAPTCHA v3 | `grecaptcha.execute()` or the `render=` script parameter, including the action |
+| hCaptcha | The `h-captcha` element |
+| Cloudflare Turnstile | The `cf-turnstile` element |
+
+## Returns
+
+<ResponseField name="CaptchaResult" type="object">
+  <Expandable title="properties">
+    <ResponseField name="success" type="boolean">
+      Whether the captcha was solved.
+    </ResponseField>
+    <ResponseField name="token" type="string | null">
+      The solved token.
+    </ResponseField>
+    <ResponseField name="message" type="string">
+      `"Captcha solved successfully"` or `"Captcha solving failed"`.
+    </ResponseField>
+    <ResponseField name="output" type="string">
+      The solver's full log, for debugging.
+    </ResponseField>
+  </Expandable>
+</ResponseField>
+
+## Errors
+
+`captcha()` throws when:
+
+- `apiKey` is missing.
+- No captcha is found on the page and you didn't set `sitekey`. The message is `Could not auto-detect captcha. Please provide sitekey manually.`
+- The solver reports an error, for example a 2captcha error or a timeout. The message starts with `[captcha]`.
+
+## Examples
+
+### Solve a captcha before submitting a form
+
+```javascript tests/signup.test.mjs
+import { describe, expect, it } from 'vitest';
+import { TestDriver } from 'testdriverai/vitest/hooks';
+
+describe('Signup', () => {
+  it('gets past the captcha', async (context) => {
     const testdriver = TestDriver(context);
+    await testdriver.provision.chrome({ url: 'https://example.com/signup' });
 
-    // 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: 'john@example.com', selector: '#email' });
-
-    // Solve the captcha
-    const result = await testdriver.captcha({
-      apiKey: process.env.TWOCAPTCHA_API_KEY,
-    });
+    await testdriver.find('Email input field').click();
+    await testdriver.type('user@example.com');
 
+    // Solves the captcha, then clicks the form's submit button
+    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);
+    await testdriver.assert('a confirmation message is shown');
+  });
 });
 ```
 
-## Environment Variables
-
-You can set your API key as an environment variable:
+### Submit the form yourself
 
-```bash
-export TWOCAPTCHA_API_KEY=your_api_key_here
+```javascript
+await testdriver.captcha({ apiKey: process.env.TWOCAPTCHA_API_KEY, autoSubmit: false });
+await testdriver.find('Create account button').click();
 ```
 
-Then use it in your tests:
+### Set the sitekey and type
 
 ```javascript
-const result = await testdriver.captcha({
+await testdriver.captcha({
   apiKey: process.env.TWOCAPTCHA_API_KEY,
+  sitekey: '6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI',
+  type: 'recaptcha_v2',
 });
 ```
 
-### GitHub Actions
+## Set up the API key
 
-Add the key to your repository secrets and expose it in your workflow:
+Sign up at [2captcha.com](https://2captcha.com), add funds, and copy your API key. Keep it out of your test code: put it in `.env` locally, and in a secret in CI.
 
-```yaml
-- name: Run Tests
-  run: vitest run
+```bash .env
+TWOCAPTCHA_API_KEY=your_2captcha_key
+```
+
+```yaml .github/workflows/testdriver.yml
+- name: Run TestDriver tests
+  run: npx vitest run
   env:
     TWOCAPTCHA_API_KEY: ${{ secrets.TWOCAPTCHA_API_KEY }}
 ```
 
-## How It Works
-
-1. **Detection**: Scans the page for captcha elements (`data-sitekey`, script tags, etc.)
-2. **Submit**: Sends the captcha challenge to 2captcha's solving service
-3. **Poll**: Waits for human solvers to complete the captcha
-4. **Inject**: Injects the solved token into the page's hidden fields
-5. **Callback**: Triggers any JavaScript callbacks the page expects
-
 ## Troubleshooting
 
-### "Could not auto-detect captcha"
+<AccordionGroup>
+  <Accordion title="Could not auto-detect captcha">
+
+    The captcha wasn't on the page when `captcha()` ran. Wait for it to load first, for example with `find()` and a `timeout`. If it still isn't detected, pass `sitekey` and `type`.
 
-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
+  </Accordion>
+  <Accordion title="The solve times out">
 
-### Timeout errors
+    2captcha's workers usually take 10 to 30 seconds. Raise `timeout`, and check that your 2captcha account has funds.
 
-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
+  </Accordion>
+  <Accordion title="The site rejects the token">
 
-### Token not working
+    Check that `type` matches the captcha on the page. For reCAPTCHA v3, check that `action` matches the action the site uses.
 
-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
+  </Accordion>
+</AccordionGroup>
 
-## Requirements
+## Related
 
-- Chrome must be launched with remote debugging enabled (automatic on all sandboxes)
-- A valid 2captcha API key with sufficient balance
+- [Launch apps](/provision): open Chrome before solving
+- [Secrets](/secrets): keep API keys out of your tests
+- [type()](/type) and [find()](/find): fill in the rest of the form