@testdriverai/agent 7.8.0-canary.10

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://api-test.testdriver.ai/api/v1/testdriver/testcase/69bc95138797a8a13f4cbfa6/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 "testdriverai/vitest/hooks";
+
+/**
+ * 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://api-test.testdriver.ai/api/v1/testdriver/testcase/69bc952e8797a8a13f4cbfc1/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 "testdriverai/vitest/hooks";
+
+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://api-test.testdriver.ai/api/v1/testdriver/testcase/69bc951636864abb362f857c/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 "testdriverai/vitest/hooks";
+
+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>

package/docs/v7/examples/launch-vscode-linux.mdx

@@ -0,0 +1,101 @@
+---
+title: "Launching VS Code Example"
+sidebarTitle: "Launch VS Code"
+description: "Example test demonstrating how to launch VS Code and install extensions on Linux."
+icon: "play"
+mode: "wide"
+---
+
+## Demo Test Run
+
+Watch this test execute in a real sandbox environment:
+
+{/* launch-vscode-linux.test.mjs output */}
+<iframe 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69bc950e8797a8a13f4cbfa4/replay" 
+  width="100%" 
+  height="390" 
+  style={{ border: "1px solid #333", borderRadius: "8px" }}
+  allow="fullscreen"
+/>
+
+## Source Code
+
+```javascript title="launch-vscode-linux.test.mjs" {13,27-29}
+/**
+ * TestDriver SDK - Launch VS Code Test
+ */
+
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "testdriverai/vitest/hooks";
+
+const isLinux = (process.env.TD_OS || "linux") === "linux";
+
+describe("Launch VS Code on Linux", () => {
+  it.skipIf(!isLinux)(
+    "should launch VS Code on Debian/Ubuntu",
+    async (context) => {
+      const testdriver = TestDriver(context, { ip: context.ip || process.env.TD_IP });
+      
+      // provision.vscode() automatically calls ready() and starts dashcam
+      await testdriver.provision.vscode();
+
+      // Wait for VS Code to launch (polls every 5s until found or timeout)
+      const vsCodeWindow = await testdriver.find(
+        "Visual Studio Code window",
+        { timeout: 60000 }
+      );
+      expect(vsCodeWindow.found()).toBeTruthy();
+    },
+  );
+
+  it.skipIf(!isLinux)(
+    "should install and use a VS Code extension",
+    async (context) => {
+      const testdriver = TestDriver(context, { ip: context.ip || process.env.TD_IP });
+      
+      // Launch VS Code with the Prettier extension installed
+      await testdriver.provision.vscode({
+        extensions: ["esbenp.prettier-vscode"],
+      });
+
+      const vsCodeWindow = await testdriver.find(
+        "Visual Studio Code window",
+        { timeout: 60000 }
+      );
+
+      expect(vsCodeWindow.found()).toBeTruthy();
+
+      // Open the extensions panel to verify Prettier is installed
+      await testdriver.pressKeys(["ctrl", "shift", "x"]);
+      
+      // Wait for extensions panel to open
+      await new Promise((resolve) => setTimeout(resolve, 2000));
+
+      // Assert that Prettier extension is visible in the installed extensions
+      const prettierVisible = await testdriver.assert(
+        "Prettier extension is visible in the extensions panel or sidebar",
+      );
+      expect(prettierVisible).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/launch-vscode-linux.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/match-image.mdx

@@ -0,0 +1,96 @@
+---
+title: "Matching an Image By Pixel"
+sidebarTitle: "Pixel Based Match"
+description: "Example test demonstrating pixel-based image matching to locate UI elements."
+icon: "image"
+mode: "wide"
+---
+
+## Demo Test Run
+
+Watch this test execute in a real sandbox environment:
+
+{/* match-image.test.mjs output */}
+<iframe 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69bc950af14c7f71c46d6b78/replay" 
+  width="100%" 
+  height="390" 
+  style={{ border: "1px solid #333", borderRadius: "8px" }}
+  allow="fullscreen"
+/>
+
+## Source Code
+
+```javascript title="match-image.test.mjs" {42}
+/**
+ * TestDriver SDK - Match Image Test
+ */
+
+import path, { dirname } from "path";
+import { fileURLToPath } from "url";
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "testdriverai/vitest/hooks";
+
+/**
+ * Perform login flow for SauceLabs demo app
+ * @param {TestDriver} client - TestDriver client
+ * @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"]);
+}
+
+// Get the directory of the current module
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+describe("Match Image Test", () => {
+  it.skip("should match shopping cart image and verify empty cart", 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' });
+
+    //
+    // Perform login first
+    await performLogin(testdriver);
+
+    // Match and click the shopping cart icon
+    const cartImagePath = path.resolve(
+      __dirname,
+      "../../_testdriver/acceptance/screenshots/cart.png",
+    );
+    await testdriver.matchImage(cartImagePath, "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/match-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/press-keys.mdx

@@ -0,0 +1,92 @@
+---
+title: "Pressing Keys Test"
+sidebarTitle: "Pressing Keys"
+description: "Example test demonstrating keyboard shortcuts and key combinations for browser navigation."
+icon: "keyboard"
+mode: "wide"
+---
+
+## Demo Test Run
+
+Watch this test execute in a real sandbox environment:
+
+{/* press-keys.test.mjs output */}
+<iframe 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69bc951df14c7f71c46d6b84/replay" 
+  width="100%" 
+  height="390" 
+  style={{ border: "1px solid #333", borderRadius: "8px" }}
+  allow="fullscreen"
+/>
+
+## Source Code
+
+```javascript title="press-keys.test.mjs" {17,24,36}
+/**
+ * TestDriver SDK - Press Keys Test
+ */
+
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "testdriverai/vitest/hooks";
+
+describe("Press Keys Test", () => {
+  it("should create tabs and navigate using keyboard shortcuts", 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 signInButton = await testdriver.find(
+      "Sign In, black button below the password field",
+    );
+    await signInButton.click();
+
+    // Open new tab
+    await testdriver.pressKeys(["ctrl", "t"]);
+
+    // Poll for "Learn more" to appear
+    let learnMore = await testdriver.find("Learn more");
+    for (let i = 0; i < 10; i++) {
+      learnMore = await learnMore.find();
+      if (learnMore.found()) break;
+      await new Promise((resolve) => setTimeout(resolve, 500));
+    }
+
+    // Open DevTools
+    await testdriver.pressKeys(["ctrl", "shift", "i"]);
+
+    // Poll for "Elements" to appear
+    let elements = await testdriver.find("Elements");
+    for (let i = 0; i < 10; i++) {
+      elements = await elements.find();
+      if (elements.found()) break;
+      await new Promise((resolve) => setTimeout(resolve, 500));
+    }
+
+    // Open another tab and navigate
+    await testdriver.pressKeys(["ctrl", "t"]);
+    await testdriver.type("google.com");
+    await testdriver.pressKeys(["enter"]);
+
+    // Assert Google appears
+    const result = await testdriver.assert("google appears");
+    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/press-keys.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/scroll-keyboard.mdx

@@ -0,0 +1,79 @@
+---
+title: "Scrolling with Keyboard Test"
+sidebarTitle: "Scrolling with Keyboard"
+description: "Example test demonstrating page scrolling using keyboard-based scroll controls."
+icon: "scroll"
+mode: "wide"
+---
+
+## Demo Test Run
+
+Watch this test execute in a real sandbox environment:
+
+{/* scroll-keyboard.test.mjs output */}
+<iframe 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69bc951b8797a8a13f4cbfa7/replay" 
+  width="100%" 
+  height="390" 
+  style={{ border: "1px solid #333", borderRadius: "8px" }}
+  allow="fullscreen"
+/>
+
+## Source Code
+
+```javascript title="scroll-keyboard.test.mjs" {26}
+/**
+ * TestDriver SDK - Scroll Keyboard Test
+ */
+
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "testdriverai/vitest/hooks";
+
+describe("Scroll Keyboard Test", () => {
+  it("should navigate to webhamster.com and scroll with keyboard", 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' });
+
+    //
+    // Navigate to https://www.webhamster.com/
+    await testdriver.focusApplication("Google Chrome");
+    const urlBar = await testdriver.find(
+      "testdriver-sandbox.vercel.app/login, the URL in the omnibox showing the current page", {zoom: true}
+    );
+    await urlBar.click();
+    await testdriver.pressKeys(["ctrl", "a"]);
+    await testdriver.type("https://www.webhamster.com/");
+    await testdriver.pressKeys(["enter"]);
+
+    // Scroll down with keyboard 1000 pixels
+    const heading = await testdriver.find(
+      "The Hamster Dance, large heading at top of page",
+    );
+    await heading.click();
+    await testdriver.scroll("down", { amount: 1000 });
+
+    // Assert the page is scrolled down
+    const result = await testdriver.assert("The text 'The Hamster Dance' is not visible on the webpage content. It's ok if it's visible in the tab title.");
+
+    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/scroll-keyboard.test.mjs
+```
+
+<Note>
+  Make sure you have `TD_API_KEY` set in your environment. Get one at [testdriver.ai](https://testdriver.ai).
+</Note>