@testdriverai/agent 7.8.0-canary.10

package/docs/v7/examples/assert.mdx

@@ -0,0 +1,72 @@
+---
+title: "Assert Test Example"
+sidebarTitle: "Assert"
+description: "Example test that uses assert to verify a page loads."
+icon: "check-circle"
+mode: "wide"
+---
+
+## Demo Test Run
+
+Watch this test execute in a real sandbox environment:
+
+{/* assert.test.mjs output */}
+<iframe 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69bc951f36864abb362f8584/replay" 
+  width="100%" 
+  height="390" 
+  style={{ border: "1px solid #333", borderRadius: "8px" }}
+  allow="fullscreen"
+/>
+
+## Source Code
+
+```javascript title="assert.test.mjs" {22-24}
+/**
+ * TestDriver SDK - Assert Test
+ */
+
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "testdriverai/vitest/hooks";
+
+describe("Assert Test", () => {
+  it("should assert the testdriver login page shows", async (context) => {
+    const testdriver = TestDriver(context, {
+      ip: context.ip || process.env.TD_IP,
+    });
+    
+    // provision.chrome() automatically calls ready() and starts dashcam
+    await testdriver.provision.chrome({
+      url: 'http://testdriver-sandbox.vercel.app/login',
+    });
+
+    // Take a screenshot
+    await testdriver.screenshot();
+
+    // Assert the TestDriver.ai Sandbox login page is displayed
+    const result = await testdriver.assert(
+      "the TestDriver.ai Sandbox login page is displayed",
+    );
+
+    expect(result).toBeTruthy();
+  });
+});
+```
+
+## Running This Example
+
+```bash
+# Clone the TestDriver repository
+git clone https://github.com/testdriverai/testdriverai
+
+# Install dependencies
+cd testdriverai
+npm install
+
+# Run this specific example
+npx vitest run examples/assert.test.mjs
+```
+
+<Note>
+  Make sure you have `TD_API_KEY` set in your environment. Get one at [testdriver.ai](https://testdriver.ai).
+</Note>

package/docs/v7/examples/captcha-api.mdx

@@ -0,0 +1,92 @@
+---
+title: "Captcha Solving Example"
+sidebarTitle: "Captcha Solving"
+description: "Example test demonstrating automatic captcha solving with reCAPTCHA and Cloudflare Turnstile support."
+icon: "shield-check"
+mode: "wide"
+---
+
+## Demo Test Run
+
+Watch this test execute in a real sandbox environment:
+
+{/* captcha-api.test.mjs output */}
+<iframe 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/698f7fb0d3b320ad547d9d44/replay" 
+  width="100%" 
+  height="390" 
+  style={{ border: "1px solid #333", borderRadius: "8px" }}
+  allow="fullscreen"
+/>
+
+## Source Code
+
+```javascript title="captcha-api.test.mjs" {18-20}
+/**
+ * TestDriver SDK - Captcha Test
+ */
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "testdriverai/vitest/hooks";
+
+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);
+});
+```
+
+## Running This Example
+
+```bash
+# Clone the TestDriver repository
+git clone https://github.com/testdriverai/testdriverai
+
+# Install dependencies
+cd testdriverai
+npm install
+
+# Run this specific example
+npx vitest run examples/captcha-api.test.mjs
+```
+
+<Note>
+  Make sure you have `TD_API_KEY` set in your environment. Get one at [testdriver.ai](https://testdriver.ai).
+</Note>

package/docs/v7/examples/chrome-extension.mdx

@@ -0,0 +1,132 @@
+---
+title: "Chrome Extension Test Example"
+sidebarTitle: "Chrome Extension"
+description: "Example test showing how to load Chrome extensions from local paths or the Chrome Web Store."
+icon: "chrome"
+mode: "wide"
+---
+
+## Demo Test Run
+
+Watch this test execute in a real sandbox environment:
+
+{/* chrome-extension.test.mjs output */}
+<iframe 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69bc9507f14c7f71c46d6b77/replay" 
+  width="100%" 
+  height="390" 
+  style={{ border: "1px solid #333", borderRadius: "8px" }}
+  allow="fullscreen"
+/>
+
+## Source Code
+
+```javascript title="chrome-extension.test.mjs" {31-33}
+/**
+ * TestDriver SDK - Chrome Extension Test
+ */
+
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "testdriverai/vitest/hooks";
+
+describe("Chrome Extension Test", () => {
+  it("should load hello-world Chrome extension from local path", async (context) => {
+
+    console.log('connecting to', process.env.TD_IP)
+
+    const testdriver = TestDriver(context, { ip: context.ip || process.env.TD_IP, cacheKey: new Date().getTime().toString() });
+    
+    // Determine OS-specific paths and commands
+    const shell = testdriver.os === 'windows' ? 'pwsh' : 'sh';
+    const extensionsDir = testdriver.os === 'windows' 
+      ? 'C:\\Users\\testdriver\\Downloads\\chrome-extensions-samples'
+      : '/tmp/chrome-extensions-samples';
+    const extensionPath = testdriver.os === 'windows'
+      ? `${extensionsDir}\\functional-samples\\tutorial.hello-world`
+      : `${extensionsDir}/functional-samples/tutorial.hello-world`;
+    
+    // Clone the Chrome extensions samples repo
+    const cloneCmd = testdriver.os === 'windows'
+      ? `git clone --depth 1 https://github.com/GoogleChrome/chrome-extensions-samples.git "${extensionsDir}"`
+      : `git clone --depth 1 https://github.com/GoogleChrome/chrome-extensions-samples.git ${extensionsDir}`;
+    
+    await testdriver.exec(shell, cloneCmd, 60000, true);
+
+    // Launch Chrome with the hello-world extension loaded
+    await testdriver.provision.chromeExtension({
+      extensionPath: extensionPath
+    });
+
+    // Navigate to testdriver.ai (extensions don't load on New Tab)
+    const addressBar = await testdriver.find("Chrome address bar");
+    await addressBar.click();
+    await testdriver.type("testdriver.ai");
+    await testdriver.pressKeys(["enter"]);
+
+    // Wait for page to load
+    const pageResult = await testdriver.assert("I can see testdriver.ai");
+    expect(pageResult).toBeTruthy();
+
+    // The hello-world extension adds a puzzle piece icon to the toolbar
+    // When clicked, it shows a popup with "Hello Extensions"
+
+    // Click on the extensions button (puzzle piece icon) in Chrome toolbar
+    const extensionsButton = await testdriver.find("The extensions button in the Chrome toolbar", {zoom: true});
+    await extensionsButton.click();
+
+    // Look for the hello world extension in the extensions menu
+    const helloExtension = await testdriver.find("Hello Extensions extension in the extensions dropdown");
+    await helloExtension.click();
+
+    // Verify the extension popup shows "Hello Extensions" text
+    const popupResult = await testdriver.assert("a popup shows with the text 'Hello Extensions'");
+    expect(popupResult).toBeTruthy();
+  });
+
+  it("should load Loom from Chrome Web Store by extensionId", async (context) => {
+    const testdriver = TestDriver(context, { ip: context.ip || process.env.TD_IP });
+
+    // Launch Chrome with Loom loaded by its Chrome Web Store ID
+    // Loom ID: liecbddmkiiihnedobmlmillhodjkdmb
+    await testdriver.provision.chromeExtension({
+      extensionId: 'liecbddmkiiihnedobmlmillhodjkdmb'
+    });
+
+    // Navigate to testdriver.ai (extensions don't load on New Tab)
+    const addressBar = await testdriver.find("Chrome address bar");
+    await addressBar.click();
+    await testdriver.type("testdriver.ai");
+    await testdriver.pressKeys(["enter"]);
+
+    // Wait for page to load
+    const pageResult = await testdriver.assert("I can see testdriver.ai");
+    expect(pageResult).toBeTruthy();
+
+    // Click on the extensions button (puzzle piece icon) in Chrome toolbar
+    const extensionsButton = await testdriver.find("The puzzle-shaped icon in the Chrome toolbar.", {zoom: true});
+    await extensionsButton.click();
+
+    // Look for Loom in the extensions menu
+    const loomExtension = await testdriver.find("Loom extension in the extensions dropdown");
+    expect(loomExtension.found()).toBeTruthy();
+  });
+});
+```
+
+## Running This Example
+
+```bash
+# Clone the TestDriver repository
+git clone https://github.com/testdriverai/testdriverai
+
+# Install dependencies
+cd testdriverai
+npm install
+
+# Run this specific example
+npx vitest run examples/chrome-extension.test.mjs
+```
+
+<Note>
+  Make sure you have `TD_API_KEY` set in your environment. Get one at [testdriver.ai](https://testdriver.ai).
+</Note>

package/docs/v7/examples/drag-and-drop.mdx

@@ -0,0 +1,100 @@
+---
+title: "Drag and Drop Test Example"
+sidebarTitle: "Drag and Drop"
+description: "Example test demonstrating drag and drop interactions using mouseDown and mouseUp."
+icon: "arrows-up-down-left-right"
+mode: "wide"
+---
+
+## Demo Test Run
+
+Watch this test execute in a real sandbox environment:
+
+{/* drag-and-drop.test.mjs output */}
+<iframe 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69a62b42fc0ac3cc632a918b/replay" 
+  width="100%" 
+  height="390" 
+  style={{ border: "1px solid #333", borderRadius: "8px" }}
+  allow="fullscreen"
+/>
+
+## Source Code
+
+```javascript title="drag-and-drop.test.mjs" {33-34,38-39}
+/**
+ * TestDriver SDK - Drag and Drop Test
+ */
+
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "testdriverai/vitest/hooks";
+
+const isLinux = (process.env.TD_OS || "linux") === "linux";
+
+describe("Drag and Drop Test", () => {
+  it.skipIf(isLinux)(
+    'should drag "New Text Document" to "Recycle Bin"',
+    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' });
+
+      //
+      // Show the desktop
+      await testdriver.pressKeys(["win", "d"]);
+
+      // Open the context menu
+      await testdriver.pressKeys(["shift", "f10"]);
+
+      // Hover over "New" in the context menu
+      const newOption = await testdriver.find(
+        "New, new option in the open context menu on the desktop",
+      );
+      await newOption.hover();
+
+      // Click "Text Document" in the context menu
+      const textDocOption = await testdriver.find(
+        "Text Document, text document option in the new submenu of the desktop context menu",
+      );
+      await textDocOption.click();
+
+      // Unfocus the "Text Document" text field
+      await testdriver.pressKeys(["esc"]);
+
+      // Drag the "New Text Document" icon to the "Recycle Bin"
+      const textDoc = await testdriver.find(
+        "New Text Document, new text document icon in the center of the desktop",
+      );
+      await textDoc.mouseDown();
+
+      const recycleBin = await testdriver.find(
+        "Recycle Bin, recycle bin icon in the top left corner of the desktop",
+      );
+      await recycleBin.mouseUp();
+
+      // Assert "New Text Document" icon is not on the Desktop
+      const result = await testdriver.assert(
+        'the "New Text Document" icon is not visible on the Desktop',
+      );
+      expect(result).toBeTruthy();
+    },
+  );
+});
+```
+
+## Running This Example
+
+```bash
+# Clone the TestDriver repository
+git clone https://github.com/testdriverai/testdriverai
+
+# Install dependencies
+cd testdriverai
+npm install
+
+# Run this specific example
+npx vitest run examples/drag-and-drop.test.mjs
+```
+
+<Note>
+  Make sure you have `TD_API_KEY` set in your environment. Get one at [testdriver.ai](https://testdriver.ai).
+</Note>

package/docs/v7/examples/element-not-found.mdx

@@ -0,0 +1,67 @@
+---
+title: "Element Not Found Test"
+sidebarTitle: "Element Not Found"
+description: "Example test showing how to gracefully handle elements that don't exist on the page."
+icon: "crosshairs"
+mode: "wide"
+---
+
+## Demo Test Run
+
+Watch this test execute in a real sandbox environment:
+
+{/* element-not-found.test.mjs output */}
+<iframe 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69bc952af14c7f71c46d6b89/replay" 
+  width="100%" 
+  height="390" 
+  style={{ border: "1px solid #333", borderRadius: "8px" }}
+  allow="fullscreen"
+/>
+
+## Source Code
+
+```javascript title="element-not-found.test.mjs" {16-18}
+/**
+ * TestDriver SDK - Element Not Found Test
+ */
+
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "testdriverai/vitest/hooks";
+
+describe("Element Not Found Test", () => {
+  it("should handle non-existent element gracefully without timing out", 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' });
+
+    //
+
+    // Try to find an element that definitely doesn't exist
+    const element = await testdriver.find(
+      "a purple unicorn dancing on the moon",
+    );
+
+    // Should return an element that is not found
+    expect(element.found()).toBe(false);
+    expect(element.coordinates).toBeNull();
+  }); // 90 second timeout for the test (should complete much faster)
+});
+```
+
+## Running This Example
+
+```bash
+# Clone the TestDriver repository
+git clone https://github.com/testdriverai/testdriverai
+
+# Install dependencies
+cd testdriverai
+npm install
+
+# Run this specific example
+npx vitest run examples/element-not-found.test.mjs
+```
+
+<Note>
+  Make sure you have `TD_API_KEY` set in your environment. Get one at [testdriver.ai](https://testdriver.ai).
+</Note>

package/docs/v7/examples/exec-output.mdx

@@ -0,0 +1,85 @@
+---
+title: "Exec Output Test Example"
+sidebarTitle: "Exec Output"
+description: "Example test demonstrating how to capture and use output from PowerShell exec commands."
+icon: "terminal"
+mode: "wide"
+---
+
+## Demo Test Run
+
+Watch this test execute in a real sandbox environment:
+
+{/* exec-output.test.mjs output */}
+<iframe 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69bc95118797a8a13f4cbfa5/replay" 
+  width="100%" 
+  height="390" 
+  style={{ border: "1px solid #333", borderRadius: "8px" }}
+  allow="fullscreen"
+/>
+
+## Source Code
+
+```javascript title="exec-output.test.mjs" {22-27}
+/**
+ * TestDriver SDK - Exec Output Test (Vitest)
+ * Converted from: testdriver/acceptance/exec-output.yaml
+ */
+
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../lib/vitest/hooks.mjs";
+import { getDefaults } from "./config.mjs";
+
+describe.skip("Exec Output Test", () => {
+  it(
+    "should set date using PowerShell and navigate to calendar",
+    async (context) => {
+      const testdriver = TestDriver(context, { ...getDefaults(context), headless: true });
+      await testdriver.provision.chrome({ url: 'http://testdriver-sandbox.vercel.app/login' });
+
+      //
+      // Generate date in query string format
+      const queryString = await testdriver.exec(
+        "pwsh",
+        `
+$date = (Get-Date).AddMonths(1)
+Write-Output $date.ToString("yyyy-MM-dd")
+    `,
+        10000,
+      );
+
+      // Assert that the date is valid
+      const dateValidResult = await testdriver.assert(
+        `${queryString} is a valid date`,
+      );
+      expect(dateValidResult).toBeTruthy();
+
+      // Generate date in display format
+      const expectedDate = await testdriver.exec(
+        "pwsh",
+        `
+$date = (Get-Date).AddMonths(1)
+Write-Output $date.ToString("ddd MMM d yyyy")
+    `,
+        10000,
+      );
+
+      // Navigate to calendar with date parameter
+      await testdriver.focusApplication("Google Chrome");
+      await testdriver.pressKeys(["ctrl", "l"]);
+      await testdriver.type(
+        `https://teamup.com/ks48cf2135e7e080bc?view=d&date=${queryString}`,
+      );
+      await testdriver.pressKeys(["enter"]);
+
+      // Assert that the expected date shows
+      await testdriver.focusApplication("Google Chrome");
+      const result = await testdriver.assert(
+        `the text ${expectedDate} is visible on screen`,
+      );
+      expect(result).toBeTruthy();
+    },
+  );
+});
+```

package/docs/v7/examples/exec-pwsh.mdx

@@ -0,0 +1,83 @@
+---
+title: "Exec PowerShell Test Example"
+sidebarTitle: "Exec Pwsh"
+description: "Example test demonstrating how to generate dynamic data using PowerShell and use it in test interactions."
+icon: "terminal"
+mode: "wide"
+---
+
+## Demo Test Run
+
+Watch this test execute in a real sandbox environment:
+
+{/* exec-pwsh.test.mjs output */}
+<iframe 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69bc95088797a8a13f4cbfa2/replay" 
+  width="100%" 
+  height="390" 
+  style={{ border: "1px solid #333", borderRadius: "8px" }}
+  allow="fullscreen"
+/>
+
+## Source Code
+
+```javascript title="exec-pwsh.test.mjs" {20-38}
+/**
+ * TestDriver SDK - Exec Shell Test (Vitest)
+ * Converted from: testdriver/acceptance/exec-shell.yaml
+ */
+
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../lib/vitest/hooks.mjs";
+import { getDefaults } from "./config.mjs";
+
+describe.skip("Exec PowerShell Test", () => {
+  it(
+    "should generate random email using PowerShell and enter it",
+    async (context) => {
+      const testdriver = TestDriver(context, { ...getDefaults(context), headless: true });
+      await testdriver.provision.chrome({ url: 'http://testdriver-sandbox.vercel.app/login' });
+
+      //
+      // Generate random email using PowerShell
+      const randomEmail = await testdriver.exec({
+        language: "pwsh",
+        code: `
+# Random email generator in PowerShell
+
+# Arrays of possible names and domains
+$firstNames = @("john", "jane", "alex", "chris", "sara", "mike", "lisa", "david", "emma", "ryan")
+$lastNames = @("smith", "johnson", "williams", "brown", "jones", "garcia", "miller", "davis", "martin", "lee")
+$domains = @("example.com", "testmail.com", "mailinator.com", "demo.org", "company.net")
+
+# Random selection
+$first = Get-Random -InputObject $firstNames
+$last = Get-Random -InputObject $lastNames
+$domain = Get-Random -InputObject $domains
+$number = Get-Random -Minimum 1 -Maximum 1000
+
+# Generate the email
+$email = "$first.$last$number@$domain".ToLower()
+
+# Output
+Write-Output "$email"
+    `,
+        timeout: 10000,
+      });
+
+      // Enter the email in username field
+      const usernameField = await testdriver.find(
+        "Username, input field for username",
+      );
+      await usernameField.click();
+      await testdriver.type(randomEmail);
+
+      // Assert that the username field shows a valid email address
+      const result = await testdriver.assert(
+        `the username field contains ${randomEmail} which is a valid email address`,
+      );
+      expect(result).toBeTruthy();
+    },
+  );
+});
+```

package/docs/v7/examples/focus-window.mdx

@@ -0,0 +1,62 @@
+---
+title: "Focus Window Test Example"
+sidebarTitle: "Focus Window"
+description: "Example test demonstrating how to switch focus between application windows."
+icon: "window-maximize"
+mode: "wide"
+---
+
+## Demo Test Run
+
+Watch this test execute in a real sandbox environment:
+
+{/* focus-window.test.mjs output */}
+<iframe 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69bc9526f14c7f71c46d6b85/replay" 
+  width="100%" 
+  height="390" 
+  style={{ border: "1px solid #333", borderRadius: "8px" }}
+  allow="fullscreen"
+/>
+
+## Source Code
+
+```javascript title="focus-window.test.mjs" {23-25}
+/**
+ * TestDriver SDK - Focus Window Test (Vitest)
+ * Converted from: testdriver/acceptance/focus-window.yaml
+ */
+
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../lib/vitest/hooks.mjs";
+import { getDefaults } from "./config.mjs";
+
+describe("Focus Window Test", () => {
+  it.skip(
+    "should click Microsoft Edge icon and focus Google Chrome",
+    async (context) => {
+      const testdriver = TestDriver(context, { ...getDefaults(context), headless: true });
+      await testdriver.provision.chrome({ url: 'http://testdriver-sandbox.vercel.app/login' });
+
+      //
+      // Show desktop
+      await testdriver.pressKeys(["winleft", "d"]);
+
+      // Click on the Microsoft Edge icon
+      const edgeIcon = await testdriver.find(
+        "a blue and green swirl icon on the taskbar representing Microsoft Edge",
+      );
+      await edgeIcon.click();
+
+      // Focus Google Chrome
+      await testdriver.focusApplication("Google Chrome");
+
+      // Assert Chrome is focused (implicit through successful focus)
+      const result = await testdriver.assert(
+        "Google Chrome is the focused application",
+      );
+      expect(result).toBeTruthy();
+    },
+  );
+});
+```