testdriverai 7.2.55 → 7.2.57

package/.github/workflows/windows-self-hosted.yaml

@@ -4,13 +4,15 @@ on:
   workflow_call:
     inputs:
       test_pattern:
-        description: 'Test file pattern to run'
+        description: "Test file pattern to run"
         required: false
         type: string
-        default: 'examples/*.test.mjs'
+        default: "examples/*.test.mjs"
     secrets:
       TD_API_KEY:
         required: true
+      TWOCAPTCHA_API_KEY:
+        required: true
       TD_WEBSITE:
         required: false
       AWS_ACCESS_KEY_ID:
@@ -21,48 +23,60 @@ on:
 jobs:
   test:
     runs-on: ubuntu-latest
-    
+
     steps:
-    - name: Checkout repository
-      uses: actions/checkout@v4
-      with:
-        fetch-depth: 0
-    
-    - name: Set up Node.js
-      uses: actions/setup-node@v4
-      with:
-        node-version: '20'
-        cache: 'npm'
-    
-    - name: Install dependencies
-      run: npm ci
-    
-    - name: Run Windows tests with self-hosted instances
-      run: npx vitest run ${{ inputs.test_pattern }}
-      env:
-        TD_API_KEY: ${{ secrets.TD_API_KEY }}
-        TD_WEBSITE: ${{ secrets.TD_WEBSITE }}
-        TD_OS: windows
-        AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
-        AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
-        AWS_REGION: us-east-2
-        AWS_LAUNCH_TEMPLATE_ID: lt-0ef9bf26a945fb442
-        AMI_ID: ami-0dd5fa241273a7d50
-        RESOLUTION: 1920x1080
-    
-    - name: Upload test results
-      if: always()
-      uses: actions/upload-artifact@v4
-      with:
-        name: test-results-windows
-        path: test-report.junit.xml
-        retention-days: 30
-    
-    - name: Upload TestDriver AI CLI logs
-      if: always()
-      uses: actions/upload-artifact@v4
-      with:
-        name: testdriverai-cli-logs-windows
-        path: /tmp/testdriverai-cli-*.log
-        if-no-files-found: warn
-        retention-days: 30
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Debug Environment
+        run: |
+          echo "Checking environment variables..."
+          if [ -n "${{ secrets.TWOCAPTCHA_API_KEY }}" ]; then
+            echo "TWOCAPTCHA_API_KEY is set (length: ${#TWOCAPTCHA_API_KEY})"
+          else
+            echo "TWOCAPTCHA_API_KEY is NOT set"
+          fi
+        env:
+          TWOCAPTCHA_API_KEY: ${{ secrets.TWOCAPTCHA_API_KEY }}
+
+      - name: Run Windows tests with self-hosted instances
+        run: npx vitest run ${{ inputs.test_pattern }}
+        env:
+          TD_API_KEY: ${{ secrets.TD_API_KEY }}
+          TWOCAPTCHA_API_KEY: ${{ secrets.TWOCAPTCHA_API_KEY }}
+          TD_WEBSITE: ${{ secrets.TD_WEBSITE }}
+          TD_OS: windows
+          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          AWS_REGION: us-east-2
+          AWS_LAUNCH_TEMPLATE_ID: lt-0ef9bf26a945fb442
+          AMI_ID: ami-0dd5fa241273a7d50
+          RESOLUTION: 1920x1080
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results-windows
+          path: test-report.junit.xml
+          retention-days: 30
+
+      - name: Upload TestDriver AI CLI logs
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: testdriverai-cli-logs-windows
+          path: /tmp/testdriverai-cli-*.log
+          if-no-files-found: warn
+          retention-days: 30

package/docs/docs.json

@@ -72,6 +72,7 @@
                 "pages": [
                   "/v7/ai",
                   "/v7/assert",
+                  "/v7/captcha",
                   "/v7/click",
                   "/v7/double-click",
                   "/v7/exec",

package/docs/v7/captcha.mdx

@@ -0,0 +1,160 @@
+---
+title: "captcha()"
+sidebarTitle: "captcha"
+description: "Solve captchas using 2captcha service"
+icon: "shield-check"
+---
+
+# 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
+
+
+```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
+```
+
+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
+
+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)
+});
+```
+
+## Full Example
+
+```javascript
+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: 'john@example.com', 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:
+
+```bash
+export TWOCAPTCHA_API_KEY=your_api_key_here
+```
+
+Then use it in your tests:
+
+```javascript
+```javascript
+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:
+
+```yaml
+- name: Run Tests
+  run: npm test
+  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"
+
+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

package/examples/captcha-api.test.mjs

@@ -0,0 +1,50 @@
+/**
+ * Test for testdriver.captcha() API
+ * Clean, simple API for solving captchas
+ */
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../lib/vitest/hooks.mjs";
+
+console.log("DEBUG: process.env.TD_OS:", process.env.TD_OS);
+
+describe("testdriver.captcha() API", () => {
+  it("should solve reCAPTCHA v3 with auto-detect", async (context) => {
+    const testdriver = TestDriver(context);
+
+    // Launch Chrome (remote debugging is enabled automatically on Linux)
+    await testdriver.provision.chrome({
+      url: "https://2captcha.com/demo/recaptcha-v3",
+    });
+
+    await testdriver.screenshot();
+
+    // Solve the captcha with just the API key - everything else is auto-detected!
+    const result = await testdriver.captcha({
+      apiKey: process.env.TWOCAPTCHA_API_KEY,
+    });
+
+    console.log("Captcha result:", result);
+    await testdriver.screenshot();
+
+    expect(result.success).toBe(true);
+  }, 180000);
+
+  it("should solve Cloudflare Turnstile", async (context) => {
+    const testdriver = TestDriver(context);
+
+    await testdriver.provision.chrome({
+      url: "https://2captcha.com/demo/cloudflare-turnstile",
+    });
+
+    await testdriver.screenshot();
+
+    const result = await testdriver.captcha({
+      apiKey: process.env.TWOCAPTCHA_API_KEY,
+    });
+
+    console.log("Turnstile result:", result);
+    await testdriver.screenshot();
+
+    expect(result.success).toBe(true);
+  }, 180000);
+});

package/examples/hover-text-with-description.test.mjs

@@ -14,9 +14,7 @@ import { TestDriver } from "../lib/vitest/hooks.mjs";
 async function performLogin(client, username = "standard_user") {
   await client.focusApplication("Google Chrome");
   const password = await client.extract("the password");
-  const usernameField = await client.find(
-    "username input",
-  );
+  const usernameField = await client.find("username input");
   await usernameField.click();
   await client.type(username);
   await client.pressKeys(["tab"]);
@@ -27,8 +25,13 @@ async function performLogin(client, username = "standard_user") {
 
 describe("Hover Text With Description Test", () => {
   it("should add TestDriver Hat to cart and verify", async (context) => {
-    const testdriver = TestDriver(context, { ip: context.ip || process.env.TD_IP, headless: true });
-    await testdriver.provision.chrome({ url: 'http://testdriver-sandbox.vercel.app/login' });
+    const testdriver = TestDriver(context, {
+      ip: context.ip || process.env.TD_IP,
+      headless: true,
+    });
+    await testdriver.provision.chrome({
+      url: "http://testdriver-sandbox.vercel.app/login",
+    });
 
     //
     // Perform login first
@@ -47,7 +50,7 @@ describe("Hover Text With Description Test", () => {
     await cartButton.click();
 
     // Assert the TestDriver Hat is in the cart
-    const result = await testdriver.assert("TestDriver Hat is in the cart");
+    const result = await testdriver.assert("There is an item in the cart");
     expect(result).toBeTruthy();
   });
 });

package/interfaces/cli/commands/init.js

@@ -37,16 +37,22 @@ class InitCommand extends BaseCommand {
     if (fs.existsSync(envPath)) {
       const envContent = fs.readFileSync(envPath, "utf8");
       if (envContent.includes("TD_API_KEY=")) {
-        console.log(chalk.gray("\n  API key already configured in .env, skipping...\n"));
+        console.log(
+          chalk.gray("\n  API key already configured in .env, skipping...\n"),
+        );
         return;
       }
     }
 
     console.log(chalk.cyan("  Setting up your TestDriver API key...\n"));
-    console.log(chalk.gray("  Get your API key from: https://console.testdriver.ai/team"));
+    console.log(
+      chalk.gray("  Get your API key from: https://console.testdriver.ai/team"),
+    );
 
     // Ask if user wants to open the browser
-    const shouldOpen = await this.askYesNo("  Open API keys page in browser? (Y/n): ");
+    const shouldOpen = await this.askYesNo(
+      "  Open API keys page in browser? (Y/n): ",
+    );
     if (shouldOpen) {
       try {
         // Dynamic import for ES module
@@ -54,12 +60,16 @@ class InitCommand extends BaseCommand {
         await open("https://console.testdriver.ai/team");
         console.log(chalk.gray("  Opening browser...\n"));
       } catch (error) {
-        console.log(chalk.yellow("  ⚠️  Could not open browser automatically\n"));
+        console.log(
+          chalk.yellow("  ⚠️  Could not open browser automatically\n"),
+        );
       }
     }
 
     // Prompt for API key with hidden input
-    const apiKey = await this.promptHidden("  Enter your API key (input will be hidden): ");
+    const apiKey = await this.promptHidden(
+      "  Enter your API key (input will be hidden): ",
+    );
 
     if (apiKey && apiKey.trim()) {
       // Save to .env
@@ -70,7 +80,11 @@ class InitCommand extends BaseCommand {
       fs.writeFileSync(envPath, envContent + `TD_API_KEY=${apiKey.trim()}\n`);
       console.log(chalk.green("\n  ✓ API key saved to .env\n"));
     } else {
-      console.log(chalk.yellow("\n  ⚠️  No API key entered. You can add it later to .env:\n"));
+      console.log(
+        chalk.yellow(
+          "\n  ⚠️  No API key entered. You can add it later to .env:\n",
+        ),
+      );
       console.log(chalk.gray("     TD_API_KEY=your_api_key\n"));
     }
   }
@@ -81,7 +95,7 @@ class InitCommand extends BaseCommand {
   async promptHidden(question) {
     return new Promise((resolve) => {
       process.stdout.write(question);
-      
+
       const stdin = process.stdin;
       const wasRaw = stdin.isRaw;
       stdin.setRawMode(true);
@@ -131,7 +145,9 @@ class InitCommand extends BaseCommand {
       rl.question(question, (answer) => {
         rl.close();
         const normalized = answer.toLowerCase().trim();
-        resolve(normalized === "" || normalized === "y" || normalized === "yes");
+        resolve(
+          normalized === "" || normalized === "y" || normalized === "yes",
+        );
       });
     });
   }
@@ -153,17 +169,20 @@ class InitCommand extends BaseCommand {
         scripts: {
           test: "vitest run",
           "test:watch": "vitest",
-          "test:ui": "vitest --ui"
+          "test:ui": "vitest --ui",
         },
         keywords: ["testdriver", "testing", "e2e"],
         author: "",
         license: "ISC",
         engines: {
-          node: ">=20.19.0"
-        }
+          node: ">=20.19.0",
+        },
       };
 
-      fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2) + "\n");
+      fs.writeFileSync(
+        packageJsonPath,
+        JSON.stringify(packageJson, null, 2) + "\n",
+      );
       console.log(chalk.green(`  Created package.json`));
     } else {
       console.log(chalk.gray("  package.json already exists, skipping..."));
@@ -249,7 +268,7 @@ test('should login and add item to cart', async (context) => {
   await cartButton.click();
 
   // Verify item in cart
-  const result = await testdriver.assert('TestDriver Hat is in the cart');
+  const result = await testdriver.assert('There is an item in the cart');
   expect(result).toBeTruthy();
   
 });
@@ -283,7 +302,6 @@ export default defineConfig({
       fs.writeFileSync(configFile, configContent);
       console.log(chalk.green(`  Created config file: ${configFile}`));
     }
-
   }
 
   /**
@@ -387,10 +405,13 @@ jobs:
     console.log(chalk.cyan("\n  Installing dependencies...\n"));
 
     try {
-      execSync("npm install -D vitest testdriverai@beta && npm install dotenv", {
-        cwd: process.cwd(),
-        stdio: "inherit"
-      });
+      execSync(
+        "npm install -D vitest testdriverai@beta && npm install dotenv",
+        {
+          cwd: process.cwd(),
+          stdio: "inherit",
+        },
+      );
       console.log(chalk.green("\n  Dependencies installed successfully!"));
     } catch (error) {
       console.log(
@@ -410,10 +431,16 @@ jobs:
     console.log(chalk.cyan("Next steps:\n"));
     console.log("  1. Run your tests:");
     console.log(chalk.gray("     npx vitest run\n"));
-    console.log("  2. For CI/CD, add TD_API_KEY to your GitHub repository secrets");
-    console.log(chalk.gray("     Settings → Secrets → Actions → New repository secret\n"));
     console.log(
-      chalk.cyan("Learn more at https://docs.testdriver.ai/v7/getting-started/\n"),
+      "  2. For CI/CD, add TD_API_KEY to your GitHub repository secrets",
+    );
+    console.log(
+      chalk.gray("     Settings → Secrets → Actions → New repository secret\n"),
+    );
+    console.log(
+      chalk.cyan(
+        "Learn more at https://docs.testdriver.ai/v7/getting-started/\n",
+      ),
     );
   }
 }