@testdriverai/agent 7.11.229-canary → 7.11.232-test

package/docs/examples/assert.mdx

@@ -1,14 +1,14 @@
 ---
-title: "Assert Test Example"
+title: "Assert that a page loaded"
 sidebarTitle: "Assert"
-description: "Example test that uses assert to verify a page loads."
+description: "Open a login page in Chrome and use assert() to check that it loaded."
 icon: "check-circle"
 mode: "wide"
 ---
 
-## Demo Test Run
+This test opens a login page in Chrome, saves a screenshot, and asserts that the page loaded.
 
-Watch this test execute in a real sandbox environment:
+## Watch it run
 
 {/* assert.test.mjs output */}
 <iframe 
@@ -19,28 +19,21 @@ Watch this test execute in a real sandbox environment:
   allow="fullscreen"
 />
 
-## Source Code
-
-```javascript title="assert.test.mjs" {22-24}
-/**
- * TestDriver SDK - Assert Test (Vitest)
- * Converted from: testdriver/acceptance/assert.yaml
- */
+## The test
 
+```javascript title="assert.test.mjs"
 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
+    const testdriver = TestDriver(context);
+
     await testdriver.provision.chrome({
       url: 'http://testdriver-sandbox.vercel.app/login',
     });
 
-    // Take a screenshot
+    // Save a screenshot to .testdriver/screenshots for debugging
     await testdriver.screenshot();
 
     // Assert the TestDriver.ai Sandbox login page is displayed
@@ -50,38 +43,32 @@ describe("Assert Test", () => {
 
     expect(result).toBeTruthy();
   });
-  // it("should assert the testdriver login page shows 2", async (context) => {
-  //   const testdriver = TestDriver(context);
-    
-  //   // provision.chrome() automatically calls ready() and starts dashcam
-  //   await testdriver.provision.chrome({
-  //     url: 'http://testdriver-sandbox.vercel.app/login',
-  //   });
-
-  //   // 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
+## How it works
+
+- `provision.chrome({ url })` starts Chrome in the sandbox and opens the URL.
+- `screenshot()` saves the screen to `.testdriver/screenshots/` and returns the file path. Use it to debug failures later.
+- `assert()` asks the AI whether a statement about the screen is true.
+- `assert()` throws when the statement is false, so the test fails at that line.
+- The `expect()` after it makes the check explicit in the test.
+
+## Run it
+
+The test is in the [TestDriver SDK repository](https://github.com/testdriverai/testdriverai/tree/main/examples). Clone it, install dependencies, and run the file:
 
 ```bash
-# Clone the TestDriver repository
 git clone https://github.com/testdriverai/testdriverai
-
-# Install dependencies
 cd testdriverai
 npm install
-
-# Run this specific example
-vitest run examples/assert.test.mjs
+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>
+The test reads your API key from `TD_API_KEY`. Create a key at [console.testdriver.ai/team/api-keys](https://console.testdriver.ai/team/api-keys). Then set it in your environment or a `.env` file.
+
+## Related
+
+- [assert()](/assert)
+- [screenshot()](/screenshot)
+- [Make assertions](/making-assertions)

package/docs/examples/click-button.mdx

@@ -0,0 +1,71 @@
+---
+title: "Click a button by its label"
+sidebarTitle: "Click a button"
+description: "Click Sign In on an empty login form and assert that a validation error appears."
+icon: "hand-pointer"
+mode: "wide"
+---
+
+This test clicks **Sign In** on an empty login form and asserts that a "fields required" error appears.
+
+## Watch it run
+
+{/* click-button.test.mjs output */}
+<iframe 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/6ad6b60a022b6043aeec2bf1/replay" 
+  width="100%" 
+  height="390" 
+  style={{ border: "1px solid #333", borderRadius: "8px" }}
+  allow="fullscreen"
+/>
+
+## The test
+
+```javascript title="click-button.test.mjs"
+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);
+    await testdriver.provision.chrome({ url: 'http://testdriver-sandbox.vercel.app/login' });
+
+    // Submit the login form without filling it in
+    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();
+  });
+});
+```
+
+## How it works
+
+- The `find()` description gives the button's label, look, and position ("black button below the password field").
+- `click()` clicks the returned element. It throws if `find()` didn't locate it.
+- `assert()` describes the error in plain language, so the test doesn't depend on exact wording or markup.
+
+## Run it
+
+The test is in the [TestDriver SDK repository](https://github.com/testdriverai/testdriverai/tree/main/examples). Clone it, install dependencies, and run the file:
+
+```bash
+git clone https://github.com/testdriverai/testdriverai
+cd testdriverai
+npm install
+npx vitest run examples/click-button.test.mjs
+```
+
+The test reads your API key from `TD_API_KEY`. Create a key at [console.testdriver.ai/team/api-keys](https://console.testdriver.ai/team/api-keys). Then set it in your environment or a `.env` file.
+
+## Related
+
+- [find()](/find)
+- [click()](/click)
+- [assert()](/assert)

package/docs/examples/{hover-image.mdx → click-icon.mdx}

@@ -1,16 +1,16 @@
 ---
-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."
+title: "Click an icon"
+sidebarTitle: "Click an icon"
+description: "Log in to a demo store, click the cart icon, and assert that the cart is empty."
 icon: "hand-pointer"
 mode: "wide"
 ---
 
-## Demo Test Run
+This test logs in to a demo store, clicks the shopping cart icon, and asserts that the cart is empty.
 
-Watch this test execute in a real sandbox environment:
+## Watch it run
 
-{/* hover-image.test.mjs output */}
+{/* click-icon.test.mjs output */}
 <iframe 
   src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/6ad6b5f59af2067e32da0686/replay" 
   width="100%" 
@@ -19,20 +19,15 @@ Watch this test execute in a real sandbox environment:
   allow="fullscreen"
 />
 
-## Source Code
-
-```javascript title="hover-image.test.mjs" {40-42,47}
-/**
- * TestDriver SDK - Hover Image Test (Vitest)
- * Converted from: testdriver/acceptance/hover-image.yaml
- */
+## The test
 
+```javascript title="click-icon.test.mjs"
 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
+ * Log in to the TestDriver sandbox demo store.
+ * @param {object} client - TestDriver instance
  * @param {string} username - Username (default: 'standard_user')
  */
 async function performLogin(client, username = "standard_user") {
@@ -51,9 +46,8 @@ async function performLogin(client, username = "standard_user") {
 
 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});
-    
-    // provision.chrome() automatically calls ready() and starts dashcam
+    const testdriver = TestDriver(context);
+
     await testdriver.provision.chrome({
       url: 'http://testdriver-sandbox.vercel.app/login'
     });
@@ -76,20 +70,30 @@ describe("Hover Image Test", () => {
 });
 ```
 
-## Running This Example
+## How it works
+
+- `performLogin()` is a plain function that takes the TestDriver instance, so any test can reuse it.
+- The demo store shows its password on screen, so `extract()` reads it.
+- `type(password, { secret: true })` keeps the password out of logs.
+- `focusApplication('Google Chrome')` brings Chrome to the front before the test uses it.
+- The `find()` description names the icon and its position ("next to the Cart text in the top right corner"). This helps the AI pick the right one.
+
+## Run it
+
+The test is in the [TestDriver SDK repository](https://github.com/testdriverai/testdriverai/tree/main/examples). Clone it, install dependencies, and run the file:
 
 ```bash
-# Clone the TestDriver repository
 git clone https://github.com/testdriverai/testdriverai
-
-# Install dependencies
 cd testdriverai
 npm install
-
-# Run this specific example
-vitest run examples/hover-image.test.mjs
+npx vitest run examples/click-icon.test.mjs
 ```
 
-<Note>
-  Make sure you have `TD_API_KEY` set in your environment. Get one at [testdriver.ai](https://testdriver.ai).
-</Note>
+The test reads your API key from `TD_API_KEY`. Create a key at [console.testdriver.ai/team/api-keys](https://console.testdriver.ai/team/api-keys). Then set it in your environment or a `.env` file.
+
+## Related
+
+- [find()](/find)
+- [extract()](/extract)
+- [Reuse code across tests](/reusable-code)
+- [Secrets](/secrets)

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

@@ -1,14 +1,14 @@
 ---
-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."
+title: "Handle an element that isn't found"
+sidebarTitle: "Element not found"
+description: "See how find() returns an unfound element instead of throwing when nothing matches."
 icon: "crosshairs"
 mode: "wide"
 ---
 
-## Demo Test Run
+This test looks for an element that isn't on the page. Use this pattern when an element may not appear.
 
-Watch this test execute in a real sandbox environment:
+## Watch it run
 
 {/* element-not-found.test.mjs output */}
 <iframe 
@@ -19,24 +19,17 @@ Watch this test execute in a real sandbox environment:
   allow="fullscreen"
 />
 
-## Source Code
-
-```javascript title="element-not-found.test.mjs" {16-18}
-/**
- * TestDriver SDK - Element Not Found Test
- * Tests that finding a non-existent element returns properly without timing out
- */
+## The test
 
+```javascript title="element-not-found.test.mjs"
 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 });
+    const testdriver = TestDriver(context);
     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",
@@ -45,24 +38,32 @@ describe("Element Not Found Test", () => {
     // 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
+## How it works
+
+- By default, `find()` checks the screen every 5 seconds for up to 10 seconds.
+- When nothing matches, `find()` doesn't throw.
+- Instead, it returns an element whose `found()` is `false` and whose `coordinates` are `null`.
+- Calling `click()` on an unfound element throws an `ElementNotFoundError`.
+
+## Run it
+
+The test is in the [TestDriver SDK repository](https://github.com/testdriverai/testdriverai/tree/main/examples). Clone it, install dependencies, and run the file:
 
 ```bash
-# Clone the TestDriver repository
 git clone https://github.com/testdriverai/testdriverai
-
-# Install dependencies
 cd testdriverai
 npm install
-
-# Run this specific example
-vitest run examples/element-not-found.test.mjs
+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>
+The test reads your API key from `TD_API_KEY`. Create a key at [console.testdriver.ai/team/api-keys](https://console.testdriver.ai/team/api-keys). Then set it in your environment or a `.env` file.
+
+## Related
+
+- [find()](/find)
+- [Locate elements](/locating-elements)
+- [Errors](/errors)

package/docs/examples/findall-coffee-icons.mdx

@@ -1,20 +1,14 @@
 ---
-title: "FindAll Test Example"
-sidebarTitle: "Findall Coffee Icons"
-description: "TestDriver SDK - FindAll Coffee Icons Test Loads a random icon grid and uses findAll() to locate and click all 4 coffee cup icons."
-icon: "play"
+title: "Find and click every matching element"
+sidebarTitle: "Find all"
+description: "Use findAll() to locate every coffee cup icon in a grid and click each one."
+icon: "crosshairs"
 mode: "wide"
 ---
 
-## Overview
+This test uses `findAll()` to find every coffee cup in an icon grid, clicks each one, and asserts on the result.
 
-TestDriver SDK - FindAll Coffee Icons Test Loads a random icon grid and uses findAll() to locate and click all 4 coffee cup icons
-
-Review the source code below to understand the implementation details and patterns used.
-
-## Live Test Run
-
-Watch this test execute in a real sandbox environment:
+## Watch it run
 
 {/* findall-coffee-icons.test.mjs output */}
 <iframe 
@@ -25,22 +19,15 @@ Watch this test execute in a real sandbox environment:
   allow="fullscreen"
 />
 
-## Source Code
+## The test
 
 ```javascript title="findall-coffee-icons.test.mjs"
-/**
- * TestDriver SDK - FindAll Coffee Icons Test
- * Loads a random icon grid and uses findAll() to locate and click all 4 coffee cup icons
- */
-
 import { describe, expect, it } from "vitest";
 import { TestDriver } from "testdriverai/vitest/hooks";
 
 describe("FindAll Coffee Icons", () => {
   it("should find and click all 4 coffee cup icons", async (context) => {
-    const testdriver = TestDriver(context, { ip: context.ip || process.env.TD_IP,
-      headless: true,
-    });
+    const testdriver = TestDriver(context);
 
     await testdriver.provision.chrome({
       url: "https://v0-random-icon-grid.vercel.app/",
@@ -55,7 +42,7 @@ describe("FindAll Coffee Icons", () => {
       console.log(`  Icon ${i + 1}: (${icon.x}, ${icon.y}) center=(${icon.centerX}, ${icon.centerY})`);
     });
 
-    // Verify we found 3 or 4 coffee icons
+    // The grid has 4 coffee cups; allow one miss, matching the assertion below
     expect(coffeeIcons.length).toBeGreaterThanOrEqual(3);
     expect(coffeeIcons.length).toBeLessThanOrEqual(4);
 
@@ -70,20 +57,29 @@ describe("FindAll Coffee Icons", () => {
 });
 ```
 
-## Running This Example
+## How it works
+
+- `findAll()` returns an array with one element per match.
+- The description states how many to expect ("there are exactly 4 on the page").
+- Each element has its position in `x`, `y`, `centerX`, and `centerY`.
+- Each element has its own `click()`, so a `for...of` loop clicks them in turn.
+- The test and assertion accept 3 or 4 matches, so one missed icon doesn't fail the run.
+
+## Run it
+
+The test is in the [TestDriver SDK repository](https://github.com/testdriverai/testdriverai/tree/main/examples). Clone it, install dependencies, and run the file:
 
 ```bash
-# Clone the TestDriver repository
 git clone https://github.com/testdriverai/testdriverai
-
-# Install dependencies
 cd testdriverai
 npm install
-
-# Run this specific example
-vitest run examples/findall-coffee-icons.test.mjs
+npx vitest run examples/findall-coffee-icons.test.mjs
 ```
 
-<Note>
-  Make sure you have `TD_API_KEY` set in your environment. Get one at [testdriver.ai](https://testdriver.ai).
-</Note>
+The test reads your API key from `TD_API_KEY`. Create a key at [console.testdriver.ai/team/api-keys](https://console.testdriver.ai/team/api-keys). Then set it in your environment or a `.env` file.
+
+## Related
+
+- [find()](/find)
+- [click()](/click)
+- [assert()](/assert)

package/docs/examples/installer.mdx

@@ -1,14 +1,18 @@
 ---
-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."
+title: "Install a Linux package"
+sidebarTitle: "Linux installer"
+description: "Use provision.installer() to install command-line and desktop apps, and download a script, on Linux."
 icon: "download"
 mode: "wide"
 ---
 
-## Demo Test Run
+This file has three `provision.installer()` tests in a Linux sandbox:
 
-Watch this test execute in a real sandbox environment:
+- One installs a command-line tool from a `.deb` and runs it.
+- One installs a desktop app from a `.deb` and checks that its window opens.
+- One downloads a shell script without running it and checks that it exists.
+
+## Watch it run
 
 {/* installer.test.mjs output */}
 <iframe 
@@ -19,14 +23,9 @@ Watch this test execute in a real sandbox environment:
   allow="fullscreen"
 />
 
-## Source Code
-
-```javascript title="installer.test.mjs" {16-18}
-/**
- * TestDriver SDK - Installer Test (Vitest)
- * Tests the provision.installer() method for downloading and installing apps
- */
+## The test
 
+```javascript title="installer.test.mjs"
 import { describe, expect, it } from "vitest";
 import { TestDriver } from "testdriverai/vitest/hooks";
 
@@ -36,7 +35,7 @@ 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});
+      const testdriver = TestDriver(context);
       
       // Install bat (a cat clone with syntax highlighting) using provision.installer
       const filePath = await testdriver.provision.installer({
@@ -51,15 +50,41 @@ describe("Provision Installer", () => {
     },
   );
 
+  it.skipIf(!isLinux)(
+    "should install a .deb with missing dependencies and launch its window",
+    async (context) => {
+      const testdriver = TestDriver(context);
+
+      // Yaak is a Tauri app. Its .deb depends on WebKitGTK and libsoup,
+      // which aren't preinstalled, so dpkg alone leaves it unconfigured.
+      await testdriver.provision.installer({
+        url: 'https://github.com/mountain-loop/yaak/releases/download/v2026.9.0/yaak_2026.9.0_amd64.deb',
+        appName: 'Yaak',
+      });
+
+      // The package and its dependencies are fully installed
+      const status = await testdriver.exec(
+        'sh',
+        "dpkg-query -W -f='${Status}' yaak",
+        10000,
+      );
+      expect(status).toBe('install ok installed');
+
+      // launch: true (the default) started the app, so its window is on screen
+      const result = await testdriver.assert('The Yaak app window is open');
+      expect(result).toBeTruthy();
+    },
+  );
+
   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});
+      const testdriver = TestDriver(context);
       
       // 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
+        launch: false, // Download the script without running it
       });
 
       // Verify the file was downloaded
@@ -73,20 +98,31 @@ describe("Provision Installer", () => {
 });
 ```
 
-## Running This Example
+## How it works
+
+- `provision.installer({ url })` downloads the file, installs it by extension, and returns its path.
+- On Linux, a `.deb` is installed with `dpkg`, and missing dependencies are installed with `apt-get`. The step fails if the package still isn't fully installed.
+- With `launch: true` (the default), a `.deb` app is started from its `.desktop` entry, then `appName` is focused. That's how the Yaak window opens.
+- A `.sh` script is made executable and run.
+- `launch: false` makes a `.sh` script executable without running it. It also skips focusing the app when you pass `appName`.
+- With `launch: false`, packages such as `.deb` files are still installed.
+- `exec('sh', command, timeout)` runs a shell command and returns its output. The test uses it to check that `bat` is installed.
+- `it.skipIf(!isLinux)` skips every test when `TD_OS` is set to `windows`.
+
+## Run it
+
+The test is in the [TestDriver SDK repository](https://github.com/testdriverai/testdriverai/tree/main/examples). Clone it, install dependencies, and run the file:
 
 ```bash
-# Clone the TestDriver repository
 git clone https://github.com/testdriverai/testdriverai
-
-# Install dependencies
 cd testdriverai
 npm install
-
-# Run this specific example
-vitest run examples/installer.test.mjs
+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>
+The test reads your API key from `TD_API_KEY`. Create a key at [console.testdriver.ai/team/api-keys](https://console.testdriver.ai/team/api-keys). Then set it in your environment or a `.env` file.
+
+## Related
+
+- [Launch apps](/provision)
+- [exec()](/exec)