@testdriverai/agent 7.11.229-canary → 7.11.231-test

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

@@ -1,14 +1,14 @@
 ---
-title: "Launching VS Code Test Example"
+title: "Launch VS Code"
 sidebarTitle: "Launch VS Code"
-description: "Example test demonstrating how to launch VS Code and install extensions on Linux."
-icon: "play"
+description: "Launch VS Code in a Linux sandbox and check that its window opens."
+icon: "code"
 mode: "wide"
 ---
 
-## Demo Test Run
+This test launches VS Code with `provision.vscode()` and waits for its window to appear.
 
-Watch this test execute in a real sandbox environment:
+## Watch it run
 
 {/* launch-vscode-linux.test.mjs output */}
 <iframe 
@@ -19,9 +19,9 @@ Watch this test execute in a real sandbox environment:
   allow="fullscreen"
 />
 
-## Source Code
+## The test
 
-```javascript title="launch-vscode-linux.test.mjs" {13,27-29}
+```javascript title="launch-vscode-linux.test.mjs"
 import { describe, expect, it } from "vitest";
 import { TestDriver } from "testdriverai/vitest/hooks";
 
@@ -31,12 +31,11 @@ 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
+      const testdriver = TestDriver(context);
+
       await testdriver.provision.vscode();
 
-      // Wait for VS Code to launch (polls every 5s until found or timeout)
+      // Poll for up to 60 seconds while VS Code starts
       const vsCodeWindow = await testdriver.find(
         "Visual Studio Code window",
         { timeout: 60000 }
@@ -45,53 +44,31 @@ describe("Launch VS Code on Linux", () => {
     },
   );
 
-  // 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
+## How it works
+
+- `provision.vscode()` starts VS Code in the sandbox.
+- `timeout: 60000` makes `find()` keep checking for up to 60 seconds. This gives VS Code time to start.
+- `found()` returns `true` once the window is on screen.
+- `it.skipIf(!isLinux)` skips the 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/launch-vscode-linux.test.mjs
+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>
+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
+
+- [Provision apps](/provision)
+- [find()](/find)
+- [Waiting for elements](/guide/best-practices-polling)

package/docs/examples/navigate-and-scroll.mdx

@@ -0,0 +1,82 @@
+---
+title: "Navigate with the address bar and scroll"
+sidebarTitle: "Address bar and scroll"
+description: "Navigate by typing in Chrome's address bar, then scroll and assert on the result."
+icon: "scroll"
+mode: "wide"
+---
+
+This test types a URL into Chrome's address bar, scrolls down, and asserts that the heading is out of view.
+
+## Watch it run
+
+{/* navigate-and-scroll.test.mjs output */}
+<iframe 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/6ad6b600022b6043aeec2bf0/replay" 
+  width="100%" 
+  height="390" 
+  style={{ border: "1px solid #333", borderRadius: "8px" }}
+  allow="fullscreen"
+/>
+
+## The test
+
+```javascript title="navigate-and-scroll.test.mjs"
+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);
+    await testdriver.provision.chrome({ url: 'http://testdriver-sandbox.vercel.app/login' });
+
+    // Navigate to https://www.webhamster.com/ through the address bar
+    await testdriver.focusApplication("Google Chrome");
+    const urlBar = await testdriver.find(
+      "the URL in the omnibox", {zoom: true}
+    );
+    await urlBar.click();
+    await testdriver.pressKeys(["ctrl", "a"]);
+    await testdriver.type("https://www.webhamster.com/");
+    await testdriver.pressKeys(["enter"]);
+
+    // Click the page so it has focus, then scroll down
+    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();
+  });
+});
+```
+
+## How it works
+
+- `find()` with `zoom: true` locates the element in two passes for extra precision. This helps with small targets like the address bar.
+- `pressKeys(['ctrl', 'a'])` selects the current URL so `type()` replaces it.
+- The test clicks the page before scrolling so the page, not the address bar, gets the scroll.
+- `scroll('down', { amount: 1000 })` scrolls down with the mouse wheel.
+
+## 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/navigate-and-scroll.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
+
+- [scroll()](/scroll)
+- [find()](/find)
+- [focusApplication()](/focus-application)

package/docs/examples/parse.mdx

@@ -1,20 +1,14 @@
 ---
-title: "Parse Test Example"
+title: "List the elements on screen"
 sidebarTitle: "Parse"
-description: "TestDriver SDK - Parse Test (Vitest) Opens Airbnb and runs the .parse() SDK command to analyze the screen."
-icon: "play"
+description: "Open a website and use parse() to list the UI elements on screen."
+icon: "table-list"
 mode: "wide"
 ---
 
-## Overview
+This test opens Airbnb in Chrome and calls `parse()` to detect every UI element on screen.
 
-TestDriver SDK - Parse Test (Vitest) Opens Airbnb and runs the .parse() SDK command to analyze the screen.
-
-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
 
 {/* parse.test.mjs output */}
 <iframe 
@@ -25,20 +19,15 @@ Watch this test execute in a real sandbox environment:
   allow="fullscreen"
 />
 
-## Source Code
+## The test
 
 ```javascript title="parse.test.mjs"
-/**
- * TestDriver SDK - Parse Test (Vitest)
- * Opens Airbnb and runs the .parse() SDK command to analyze the screen.
- */
-
 import { describe, it } from "vitest";
 import { TestDriver } from "testdriverai/vitest/hooks";
 
 describe("Parse Test", () => {
   it("should open Airbnb and parse the screen", async (context) => {
-    const testdriver = TestDriver(context, { ip: context.ip || process.env.TD_IP});
+    const testdriver = TestDriver(context);
     await testdriver.provision.chrome({ url: "https://www.airbnb.com" });
 
     // The SDK automatically outputs elements as a formatted table
@@ -48,20 +37,27 @@ describe("Parse Test", () => {
 });
 ```
 
-## Running This Example
+## How it works
+
+- `parse()` analyzes the screen and resolves to an object. Its `elements` array lists each detected element.
+- The result also has `annotatedImageUrl`, a screenshot with the elements marked.
+- It also has `imageWidth` and `imageHeight`.
+- Use parsing to explore an unfamiliar screen before you write `find()` descriptions.
+
+## 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/parse.test.mjs
+npx vitest run examples/parse.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
+
+- [parse()](/parse)
+- [Locate elements](/locating-elements)

package/docs/examples/press-keys.mdx

@@ -1,14 +1,14 @@
 ---
-title: "Pressing Keys Test Example"
-sidebarTitle: "Pressing Keys"
-description: "Example test demonstrating keyboard shortcuts and key combinations for browser navigation."
+title: "Use keyboard shortcuts"
+sidebarTitle: "Press keys"
+description: "Use pressKeys() to open a tab, open DevTools, and navigate in Chrome."
 icon: "keyboard"
 mode: "wide"
 ---
 
-## Demo Test Run
+This test drives Chrome with keyboard shortcuts to open tabs and DevTools, then types a URL.
 
-Watch this test execute in a real sandbox environment:
+## Watch it run
 
 {/* press-keys.test.mjs output */}
 <iframe 
@@ -19,20 +19,15 @@ Watch this test execute in a real sandbox environment:
   allow="fullscreen"
 />
 
-## Source Code
-
-```javascript title="press-keys.test.mjs" {17,24,36}
-/**
- * TestDriver SDK - Press Keys Test (Vitest)
- * Converted from: testdriver/acceptance/press-keys.yaml
- */
+## The test
 
+```javascript title="press-keys.test.mjs"
 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 });
+    const testdriver = TestDriver(context);
     await testdriver.provision.chrome({ url: 'http://testdriver-sandbox.vercel.app/login' });
 
     const signInButton = await testdriver.find(
@@ -43,7 +38,7 @@ describe("Press Keys Test", () => {
     // Open new tab
     await testdriver.pressKeys(["ctrl", "t"]);
 
-    // Poll for "Learn more" to appear
+    // Wait for the new tab page to load
     let imagesLink = await testdriver.find("Images", {timeout: 5000});
 
     expect(imagesLink.found()).toBeTruthy();
@@ -51,7 +46,7 @@ describe("Press Keys Test", () => {
     // Open DevTools
     await testdriver.pressKeys(["ctrl", "shift", "i"]);
 
-    // Poll for "Elements" to appear
+    // Wait for the DevTools Elements panel
     let elements = await testdriver.find("Elements", {timeout: 5000});
     expect(elements.found()).toBeTruthy();
 
@@ -67,20 +62,28 @@ describe("Press Keys Test", () => {
 });
 ```
 
-## Running This Example
+## How it works
+
+- `pressKeys()` presses an array of keys together.
+- `['ctrl', 't']` opens a new tab, and `['ctrl', 'shift', 'i']` opens DevTools.
+- After each shortcut, `find()` with a short `timeout` waits for what the shortcut should reveal. This confirms the shortcut worked.
+- `type()` types into the focused element, here the new tab's address bar.
+
+## 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/press-keys.test.mjs
+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>
+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
+
+- [pressKeys()](/press-keys)
+- [type()](/type)
+- [find()](/find)

package/docs/examples/scroll.mdx

@@ -1,14 +1,14 @@
 ---
-title: "Scrolling Test Example"
-sidebarTitle: "Scrolling"
-description: "Example test demonstrating page scrolling with configurable direction and scroll amount."
+title: "Scroll a page"
+sidebarTitle: "Scroll"
+description: "Scroll a page down and assert that its heading has scrolled out of view."
 icon: "scroll"
 mode: "wide"
 ---
 
-## Demo Test Run
+This test opens a page, scrolls down, and asserts that the page heading is no longer visible.
 
-Watch this test execute in a real sandbox environment:
+## Watch it run
 
 {/* scroll.test.mjs output */}
 <iframe 
@@ -19,26 +19,18 @@ Watch this test execute in a real sandbox environment:
   allow="fullscreen"
 />
 
-## Source Code
-
-```javascript title="scroll.test.mjs" {29}
-/**
- * TestDriver SDK - Scroll Test (Vitest)
- * Converted from: testdriver/acceptance/scroll.yaml
- * 
- * UPDATED: Now using chrome preset for automatic setup
- */
+## The test
 
+```javascript title="scroll.test.mjs"
 import { describe, expect, it } from "vitest";
 import { TestDriver } from "testdriverai/vitest/hooks";
 
 describe("Scroll Test", () => {
   it("should navigate and scroll down the page", 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://www.webhamster.com/' });
 
-
-    // Wait for page to load and click heading
+    // Click the page so it has focus before scrolling
     const heading = await testdriver.find(
       "The Hamster Dance, large heading at top of page",
     );
@@ -54,20 +46,26 @@ describe("Scroll Test", () => {
 });
 ```
 
-## Running This Example
+## How it works
+
+- The test clicks the heading first so the page has focus and gets the scroll.
+- `scroll('down', { amount: 1000 })` scrolls down with the mouse wheel. The default amount is 300.
+- The assertion adds an exception ("It's ok if it's visible in the tab title"). This stops the AI from counting the tab title as the heading.
+
+## 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/scroll.test.mjs
+npx vitest run examples/scroll.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
+
+- [scroll()](/scroll)
+- [assert()](/assert)

package/docs/examples/type.mdx

@@ -1,14 +1,14 @@
 ---
-title: "Typing Test Example"
-sidebarTitle: "Typing"
-description: "Example test demonstrating how to type text into input fields and verify the content."
+title: "Type into a form"
+sidebarTitle: "Type"
+description: "Type into a login form and assert on the validation message for a missing password."
 icon: "keyboard"
 mode: "wide"
 ---
 
-## Demo Test Run
+This file has two login form tests. One types a username and checks the field. The other submits without a password and checks the browser's validation message.
 
-Watch this test execute in a real sandbox environment:
+## Watch it run
 
 {/* type.test.mjs output */}
 <iframe 
@@ -19,18 +19,17 @@ Watch this test execute in a real sandbox environment:
   allow="fullscreen"
 />
 
-## Source Code
+## The test
 
-```javascript title="type.test.mjs" {13}
+```javascript title="type.test.mjs"
 import { describe, expect, it } from "vitest";
 import { TestDriver } from "testdriverai/vitest/hooks";
 
 describe("Type Test", () => {
   it("should enter standard_user in username field", 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' });
 
-    //
     const usernameField = await testdriver.find(
       "Username, input field for username",
     );
@@ -44,7 +43,7 @@ describe("Type Test", () => {
   });
 
   it("should show validation message when clicking Sign In without password", 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' });
 
     // First fill in username
@@ -54,7 +53,6 @@ describe("Type Test", () => {
     await usernameField.click();
     await testdriver.type("standard_user");
 
-    //
     const signInButton = await testdriver.find(
       "Sign in, black button below the password field",
     );
@@ -69,20 +67,27 @@ describe("Type Test", () => {
 });
 ```
 
-## Running This Example
+## How it works
+
+- `type()` types into the focused element, so each test clicks the username field first.
+- `assert()` can check a field's contents (`the username field contains "standard_user"`) as well as on-screen messages.
+- The second test calls `focusApplication('Google Chrome')` before asserting. This keeps Chrome in front when the validation tooltip appears.
+
+## 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/type.test.mjs
+npx vitest run examples/type.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
+
+- [type()](/type)
+- [click()](/click)
+- [assert()](/assert)