testdriverai 7.3.4 → 7.3.6

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://testdriver-api.onrender.com/api/v1/testdriver/testcase/698b7da36513c6b23f858eee/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 "../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);
+});
+```
+
+## 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://testdriver-api.onrender.com/api/v1/testdriver/testcase/698b7ca711cc20acdd4ac83d/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 "../lib/vitest/hooks.mjs";
+
+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://testdriver-api.onrender.com/api/v1/testdriver/testcase/698b7bd411cc20acdd4ac828/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 "../lib/vitest/hooks.mjs";
+
+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://testdriver-api.onrender.com/api/v1/testdriver/testcase/698b7dd44f24dc8fa701f5fc/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 "../lib/vitest/hooks.mjs";
+
+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/hover-image.mdx

@@ -0,0 +1,94 @@
+---
+title: "Clicking Image Example"
+sidebarTitle: "Clicking on an Image"
+description: "Example test that finds and clicks on an image element using AI-powered visual recognition."
+icon: "hand-pointer"
+mode: "wide"
+---
+
+## Demo Test Run
+
+Watch this test execute in a real sandbox environment:
+
+{/* hover-image.test.mjs output */}
+<iframe 
+  src="https://testdriver-api.onrender.com/api/v1/testdriver/testcase/698b7c9211cc20acdd4ac83c/replay" 
+  width="100%" 
+  height="390" 
+  style={{ border: "1px solid #333", borderRadius: "8px" }}
+  allow="fullscreen"
+/>
+
+## Source Code
+
+```javascript title="hover-image.test.mjs" {40-42,47}
+/**
+ * TestDriver SDK - Hover Image Test
+ */
+
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../lib/vitest/hooks.mjs";
+
+/**
+ * Perform login flow for SauceLabs demo app
+ * @param {import('../../sdk.js').default} client - TestDriver client instance
+ * @param {string} username - Username (default: 'standard_user')
+ */
+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",
+  );
+  await usernameField.click();
+  await client.type(username);
+  await client.pressKeys(["tab"]);
+  await client.type(password, { secret: true });
+  await client.pressKeys(["tab"]);
+  await client.pressKeys(["enter"]);
+}
+
+describe("Hover Image Test", () => {
+  it("should click on shopping cart icon and verify empty cart", async (context) => {
+    const testdriver = TestDriver(context, { ip: context.ip || process.env.TD_IP, redraw: false });
+    
+    // provision.chrome() automatically calls ready() and starts dashcam
+    await testdriver.provision.chrome({
+      url: 'http://testdriver-sandbox.vercel.app/login'
+    });
+
+    // Perform login first
+    await performLogin(testdriver);
+
+    // Click on the shopping cart icon
+    await testdriver.focusApplication("Google Chrome");
+    const cartIcon = await testdriver.find(
+      "shopping cart icon next to the Cart text in the top right corner",
+    );
+
+    await cartIcon.click();
+
+    // Assert that you see an empty shopping cart
+    const result = await testdriver.assert("Your cart is empty");
+    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/hover-image.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/hover-text.mdx

@@ -0,0 +1,69 @@
+---
+title: "Clicking on Text Example"
+sidebarTitle: "Hover Text"
+description: "Example test that finds and clicks on text elements using natural language descriptions."
+icon: "hand-pointer"
+mode: "wide"
+---
+
+## Demo Test Run
+
+Watch this test execute in a real sandbox environment:
+
+{/* hover-text.test.mjs output */}
+<iframe 
+  src="https://testdriver-api.onrender.com/api/v1/testdriver/testcase/698b7e186513c6b23f858efc/replay" 
+  width="100%" 
+  height="390" 
+  style={{ border: "1px solid #333", borderRadius: "8px" }}
+  allow="fullscreen"
+/>
+
+## Source Code
+
+```javascript title="hover-text.test.mjs" {13-15,18-20}
+/**
+ * TestDriver SDK - Hover Text Test
+ */
+
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../lib/vitest/hooks.mjs";
+
+describe("Hover Text Test", () => {
+  it("should click Sign In and verify error message", async (context) => {
+    const testdriver = TestDriver(context, { ip: context.ip || process.env.TD_IP });
+    await testdriver.provision.chrome({ url: 'http://testdriver-sandbox.vercel.app/login' });
+
+    // Click on Sign In button using new find() API
+
+    const signInButton = await testdriver.find(
+      "Sign In, black button below the password field",
+    );
+    await signInButton.click();
+
+    // Assert that an error shows that fields are required
+    const result = await testdriver.assert(
+      "an error shows that fields are required",
+    );
+    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/hover-text.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/installer.mdx

@@ -0,0 +1,91 @@
+---
+title: "Linux App Installation Test Example"
+sidebarTitle: "Linux Installer"
+description: "Example test demonstrating how to download and install .deb packages and shell scripts on Linux."
+icon: "download"
+mode: "wide"
+---
+
+## Demo Test Run
+
+Watch this test execute in a real sandbox environment:
+
+{/* installer.test.mjs output */}
+<iframe 
+  src="https://testdriver-api.onrender.com/api/v1/testdriver/testcase/698b7ce511cc20acdd4ac844/replay" 
+  width="100%" 
+  height="390" 
+  style={{ border: "1px solid #333", borderRadius: "8px" }}
+  allow="fullscreen"
+/>
+
+## Source Code
+
+```javascript title="installer.test.mjs" {16-18}
+/**
+ * TestDriver SDK - Installer Test
+ */
+
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../lib/vitest/hooks.mjs";
+
+const isLinux = (process.env.TD_OS || "linux") === "linux";
+
+describe("Provision Installer", () => {
+  it.skipIf(!isLinux)(
+    "should download and install a .deb package on Linux",
+    async (context) => {
+      const testdriver = TestDriver(context, { ip: context.ip || process.env.TD_IP });
+      
+      // Install bat (a cat clone with syntax highlighting) using provision.installer
+      const filePath = await testdriver.provision.installer({
+        url: 'https://github.com/sharkdp/bat/releases/download/v0.24.0/bat_0.24.0_amd64.deb',
+      });
+
+      // Verify the file was downloaded
+      expect(filePath).toContain('bat');
+
+      // Verify bat was installed by running it
+      await testdriver.exec('sh', 'bat --version', 10000);
+    },
+  );
+
+  it.skipIf(!isLinux)(
+    "should download a shell script and verify it exists",
+    async (context) => {
+      const testdriver = TestDriver(context, { ip: context.ip || process.env.TD_IP });
+      
+      // Download a shell script (nvm installer)
+      const filePath = await testdriver.provision.installer({
+        url: 'https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh',
+        launch: false, // Don't auto-run the script
+      });
+
+      // Verify the file was downloaded
+      expect(filePath).toContain('install.sh');
+
+      // Verify the file is executable
+      const result = await testdriver.exec('sh', `ls -la "${filePath}"`, 10000);
+      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/installer.test.mjs
+```
+
+<Note>
+  Make sure you have `TD_API_KEY` set in your environment. Get one at [testdriver.ai](https://testdriver.ai).
+</Note>