TestDriver.ai

https://docs.testdriver.ai/
Admin
TestDriver makes it easy to write automated computer-use tests for web browsers, desktop apps, and...
Tokens:89,772
Snippets:999
Trust Score:8.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Running the Example

Source: https://docs.testdriver.ai/v7/examples/scroll-keyboard

Commands to clone the repository, install dependencies, and execute the test file.

```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
```

--------------------------------

### Running the Typing Example

Source: https://docs.testdriver.ai/v7/examples/type

Commands to clone the repository, install dependencies, and execute the test file.

```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/type.test.mjs
```

--------------------------------

### Running the Test Example

Source: https://docs.testdriver.ai/v7/examples/hover-image

Commands to clone the repository, install dependencies, and execute the test suite.

```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
```

--------------------------------

### Running the Hover Text Example

Source: https://docs.testdriver.ai/v7/examples/hover-text

Commands to clone the repository, install dependencies, and execute the test script.

```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
```

--------------------------------

### Running the Assert Example

Source: https://docs.testdriver.ai/v7/examples/assert

Commands to clone the repository, install dependencies, and execute the test using Vitest.

```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
```

--------------------------------

### Run TestDriver Example Commands

Source: https://docs.testdriver.ai/v7/examples/findall-coffee-icons

Commands to clone the repository, install dependencies, and execute the specific test file.

```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/findall-coffee-icons.test.mjs
```

--------------------------------

### Run the Press Keys Example

Source: https://docs.testdriver.ai/v7/examples/press-keys

Commands to clone the repository, install dependencies, and execute the test file using Vitest.

```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
```

--------------------------------

### Running the AI Test Example

Source: https://docs.testdriver.ai/v7/examples/ai

Commands to clone the repository, install dependencies, and execute the AI test script.

```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/ai.test.mjs
```

--------------------------------

### Run the parse example via CLI

Source: https://docs.testdriver.ai/v7/examples/parse

Commands to clone the repository, install dependencies, and execute the specific test file.

```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/parse.test.mjs
```

--------------------------------

### Manual Installation Workflow

Source: https://docs.testdriver.ai/v7/copilot/running-tests

Download an installer without auto-launching to perform custom installation commands.

```javascript
const filePath = await testdriver.provision.installer({
  url: 'https://example.com/custom-script.sh',
  launch: false,
});

// Run custom install commands
await testdriver.exec('sh', `chmod +x "${filePath}"`, 5000);
await testdriver.exec('sh', `"${filePath}" --custom-flag`, 60000);
```

--------------------------------

### Run the element not found example

Source: https://docs.testdriver.ai/v7/examples/element-not-found

Commands to clone the repository, install dependencies, and execute the specific test file.

```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
```

--------------------------------

### Install a Windows Application

Source: https://docs.testdriver.ai/v7/copilot/running-tests

Shows how to provision an MSI installer on Windows and perform custom installation steps using PowerShell.

```javascript
import { describe, expect, it } from "vitest";
import { TestDriver } from "testdriverai/vitest/hooks";

describe("Windows App Test", () => {
  it("should install on Windows", async (context) => {
    const testdriver = TestDriver(context, { 
      os: 'windows'
    });

    // Download MSI installer
    const installerPath = await testdriver.provision.installer({
      url: 'https://example.com/app.msi',
      launch: false,  // Don't auto-launch
    });

    // Custom installation if needed
    await testdriver.exec(
      'pwsh',
      `Start-Process msiexec.exe -ArgumentList "/i", "${installerPath}", "/qn" -Wait`,
      120000
    );

    // Verify installation
    const result = await testdriver.assert("application is installed");
    expect(result).toBeTruthy();
  });
});
```

--------------------------------

### Running the Scroll Example

Source: https://docs.testdriver.ai/v7/examples/scroll

Commands to clone the repository, install dependencies, and execute the scroll test using Vitest.

```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.test.mjs
```

--------------------------------

### Install and Test a Desktop App

Source: https://docs.testdriver.ai/v7/copilot/running-tests

Demonstrates installing a .deb package and verifying the installation via command execution.

```javascript
import { describe, expect, it } from "vitest";
import { TestDriver } from "testdriverai/vitest/hooks";

describe("Desktop App Test", () => {
  it("should install and launch app", async (context) => {
    const testdriver = TestDriver(context);

    // Download and install
    const installerPath = await testdriver.provision.installer({
      url: 'https://github.com/sharkdp/bat/releases/download/v0.24.0/bat_0.24.0_amd64.deb',
    });

    // Verify installation
    const output = await testdriver.exec('sh', 'bat --version', 5000);
    expect(output).toContain('bat');
  });
});
```

--------------------------------

### Run Chrome Extension Test Example

Source: https://docs.testdriver.ai/v7/examples/chrome-extension

Commands to clone the repository, install dependencies, and execute the test suite. Ensure TD_API_KEY is configured in your environment before running.

```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
```

--------------------------------

### Complete Interaction Test Suite

Source: https://docs.testdriver.ai/v7/click

A full example demonstrating setup, authentication, and various interaction types within a Vitest suite.

```javascript
import { beforeAll, afterAll, describe, it } from 'vitest';
import TestDriver from 'testdriverai';

describe('Click Interactions', () => {
  let testdriver;

  beforeAll(async () => {
    client = new TestDriver(process.env.TD_API_KEY);
    await testdriver.auth();
    await testdriver.connect();
  });

  afterAll(async () => {
    await testdriver.disconnect();
  });

  it('should perform various click actions', async () => {
    await testdriver.focusApplication('Google Chrome');
    
    // Regular click
    const loginBtn = await testdriver.find('login button');
    await loginBtn.click();
    
    // Right-click for context menu
    const profileIcon = await testdriver.find('profile icon');
    await profileIcon.rightClick();
    
    const settingsOption = await testdriver.find('Settings menu option');
    await settingsOption.click();
    
    // Double-click to edit
    const nameField = await testdriver.find('name display field');
    await nameField.doubleClick();
    
    // Verify state
    await testdriver.assert('name field is now editable');
  });

  it('should perform drag and drop', async () => {
    const item = await testdriver.find('draggable item');
    await item.mouseDown();
    
    // Drag to new location
    const dropTarget = await testdriver.find('drop area');
    await dropTarget.hover();
    await dropTarget.mouseUp();
    
    // Verify
    await testdriver.assert('item is in the drop area');
  });
});
```

--------------------------------

### Download and run installers

Source: https://docs.testdriver.ai/v7/copilot/running-tests

Downloads and executes installers for Linux and Windows environments.

```javascript
// Linux
await testdriver.exec("sh", `
  curl -L https://example.com/installer.sh -o /tmp/installer.sh
  chmod +x /tmp/installer.sh
  /tmp/installer.sh --silent
`, 300000);

// Windows
await testdriver.exec("pwsh", `
  Invoke-WebRequest -Uri "https://example.com/installer.exe" -OutFile "$env:TEMP\\installer.exe"
  Start-Process "$env:TEMP\\installer.exe" -ArgumentList "/S" -Wait
`, 300000);
```

--------------------------------

### Run Linux setup script

Source: https://docs.testdriver.ai/v7/copilot/running-tests

Executes a shell script to perform setup tasks like resetting a test database.

```javascript
await testdriver.provision.chrome({ url: "https://myapp.com" });

// Run a setup script from your repo
await testdriver.exec("sh", `
  curl -s https://myapp.com/api/reset-test-db -X POST
  echo "Test DB reset"
`, 30000);
```

--------------------------------

### Run application installer

Source: https://docs.testdriver.ai/v7/provision

Downloads and executes an application installer, supporting various formats like .msi, .exe, .deb, and .dmg.

```javascript
await testdriver.provision.installer(options)
```

```javascript
// Windows MSI installer
await testdriver.provision.installer({
  url: 'https://example.com/app-setup.msi',
  appName: 'MyApp',
});

// Linux DEB package
await testdriver.provision.installer({
  url: 'https://example.com/app.deb',
  appName: 'MyApp',
  launch: true,
});
```

--------------------------------

### dashcam.start()

Source: https://docs.testdriver.ai/v7/dashcam

Starts the recording process for the test session.

```APIDOC
## dashcam.start()

### Description
Starts recording the screen and logs for the current test session.
```

--------------------------------

### Provision a Desktop Application

Source: https://docs.testdriver.ai/v7/copilot/running-tests

Use the installer method to download and optionally launch a desktop application.

```javascript
const filePath = await testdriver.provision.installer({
  url: 'https://example.com/app.deb',
  appName: 'MyApp',  // Focus this app after install
  launch: true,      // Auto-launch after install
});
```

--------------------------------

### Start Recording

Source: https://docs.testdriver.ai/v7/dashcam

Initiates a new recording session.

```javascript
await dashcam.start()
```

```javascript
await dashcam.start();
console.log('Recording started');
```

--------------------------------

### Provision a Windows machine

Source: https://docs.testdriver.ai/v7/copilot/running-tests

Basic setup for provisioning a Windows VM environment.

```javascript
const testdriver = TestDriver(context, {
  os: "windows",
});

await testdriver.provision.chrome({ url: "https://example.com" });
```

--------------------------------

### Coordinate Hover Examples

Source: https://docs.testdriver.ai/v7/hover

Examples demonstrating how to hover at specific screen coordinates.

```javascript
// Hover at coordinates
await testdriver.hover(500, 300);

// Hover and wait
await testdriver.hover(500, 300);
await new Promise(r => setTimeout(r, 1000));
```

--------------------------------

### Install Node.js tools

Source: https://docs.testdriver.ai/v7/copilot/running-tests

Installs global npm packages via the shell.

```javascript
await testdriver.exec("sh", "npm install -g @playwright/test", 60000);
```

--------------------------------

### Element Hover Examples

Source: https://docs.testdriver.ai/v7/hover

Examples demonstrating how to find an element and hover over it to reveal dynamic content.

```javascript
// Find and hover
const tooltip = await testdriver.find('info icon');
await tooltip.hover();

// Wait to see tooltip
await new Promise(r => setTimeout(r, 1000));

// Hover over menu to reveal submenu
const menu = await testdriver.find('Products menu');
await menu.hover();

const submenu = await testdriver.find('Laptops submenu item');
await submenu.click();
```

--------------------------------

### testdriver.provision.installer()

Source: https://docs.testdriver.ai/v7/provision

Downloads and runs an application installer from a URL, supporting various package formats.

```APIDOC
## testdriver.provision.installer(options)

### Description
Download and run an application installer. Supports .msi, .exe, .deb, .rpm, .appimage, .sh, .dmg, and .pkg formats.

### Parameters
- **options** (ProvisionInstallerOptions) - Required
  - **url** (string) - Required - Download URL for the installer.
  - **filename** (string) - Optional - Override the auto-detected filename.
  - **appName** (string) - Optional - Application name to focus after installation.
  - **launch** (boolean) - Optional - Whether to focus/launch the app after installation (default: true).

### Request Example
await testdriver.provision.installer({ url: 'https://example.com/app-setup.msi', appName: 'MyApp' });
```

--------------------------------

### Install Linux apt packages

Source: https://docs.testdriver.ai/v7/copilot/running-tests

Uses apt-get to install system-level dependencies.

```javascript
await testdriver.exec("sh", `
  sudo apt-get update -qq
  sudo apt-get install -y ffmpeg imagemagick
`, 120000);
```

--------------------------------

### Initialize TestDriver Project

Source: https://docs.testdriver.ai

Run this command to set up a new project, install dependencies, and configure the MCP server.

```bash
npx testdriverai init
```

--------------------------------

### Basic Web Test Example

Source: https://docs.testdriver.ai/v7/copilot/running-tests

A complete test suite example using Vitest to perform a login flow.

```javascript
import { describe, expect, it } from "vitest";
import { TestDriver } from "testdriverai/vitest/hooks";

describe("Login Flow", () => {
  it("should log in successfully", async (context) => {
    const testdriver = TestDriver(context);
    
    await testdriver.provision.chrome({
      url: 'https://myapp.com/login',
    });

    await testdriver.find("Email input").click();
    await testdriver.type("user@example.com");
    
    await testdriver.find("Password input").click();
    await testdriver.type("password123");
    
    await testdriver.find("Sign In button").click();
    
    const result = await testdriver.assert("the dashboard is visible");
    expect(result).toBeTruthy();
  });
});
```

--------------------------------

### Environment Variable Setup

Source: https://docs.testdriver.ai/v7/captcha

Setting the API key via shell and accessing it in JavaScript.

```bash
export TWOCAPTCHA_API_KEY=your_api_key_here
```

```javascript
const result = await testdriver.captcha({
  apiKey: process.env.TWOCAPTCHA_API_KEY,
});
```

--------------------------------

### Basic Typing Examples

Source: https://docs.testdriver.ai/v7/type

Demonstrates typing strings, numbers, and using delay options.

```javascript
// Type text
await testdriver.type('hello@example.com');

// Type numbers
await testdriver.type(12345);

// Type with custom delay (legacy syntax)
await testdriver.type('slow typing', 500); // 500ms between each character

// Type with options object
await testdriver.type('text', { delay: 500 });
```

--------------------------------

### Test VS Code Extensions

Source: https://docs.testdriver.ai/v7/copilot/running-tests

Example of setting up a project, launching VS Code with extensions, and interacting with the editor.

```javascript
import { describe, expect, it } from "vitest";
import { TestDriver } from "testdriverai/vitest/hooks";

describe("VS Code Test", () => {
  it("should open workspace with extensions", async (context) => {
    const testdriver = TestDriver(context);

    // Create a test project
    await testdriver.exec('sh', 'mkdir -p /tmp/test-project && echo "print(1)" > /tmp/test-project/test.py', 10000);

    // Launch VS Code
    await testdriver.provision.vscode({
      workspace: '/tmp/test-project',
      extensions: ['ms-python.python'],
    });

    // Verify VS Code is ready
    const result = await testdriver.assert("VS Code is open with the project");
    expect(result).toBeTruthy();

    // Open the Python file
    await testdriver.find("test.py in the explorer").click();
  });
});
```

--------------------------------

### Auto-screenshot file examples

Source: https://docs.testdriver.ai/v7/screenshots

Examples of generated filenames based on the auto-screenshot naming convention.

```text
001-find-before-L15-login-button.png
002-find-after-L15-login-button.png
003-click-before-L16-login-button.png
004-click-after-L16-login-button.png
005-type-before-L18-username-field.png
006-type-error-L18-username-field.png
```

--------------------------------

### testdriver.provision.dashcam(options?)

Source: https://docs.testdriver.ai/v7/provision

Starts a Dashcam recording session with custom configuration options.

```APIDOC
## testdriver.provision.dashcam(options?)

### Description
Start Dashcam recording with custom options. Usually called automatically by other provision methods, but can be called directly for custom configurations.

### Parameters
- **options** (ProvisionDashcamOptions) - Optional
  - **logPath** (string) - Optional - Path to the TestDriver log file.
  - **logName** (string) - Optional - Display name for the log file in the Dashcam replay.
  - **webLogs** (boolean) - Optional - Enable web traffic log capture.
  - **title** (string) - Optional - Recording title for the Dashcam session.

### Example
```javascript
await testdriver.provision.dashcam({
  title: 'Login Flow Test',
  logPath: '/tmp/my-app.log',
  logName: 'Application Log',
  webLogs: true,
});
```
```

--------------------------------

### Install and launch Chrome extension

Source: https://docs.testdriver.ai/v7/provision

Installs a Chrome extension from a local directory or the Chrome Web Store using an extension ID.

```javascript
await testdriver.provision.chromeExtension(options)
```

```javascript
// From local directory
await testdriver.provision.chromeExtension({
  extensionPath: './my-extension',
});

// From Chrome Web Store
await testdriver.provision.chromeExtension({
  extensionId: 'abcdefghijklmnop',
});
```

--------------------------------

### Screenshot filename examples

Source: https://docs.testdriver.ai/v7/screenshots

Demonstrates default, custom, and explicit extension naming conventions for screenshots.

```javascript
// Default filename
await testdriver.screenshot();
// → .testdriver/screenshots/my-test/screenshot-1719849312345.png

// Custom filename
await testdriver.screenshot('login-page');
// → .testdriver/screenshots/my-test/login-page.png

// With .png extension
await testdriver.screenshot('dashboard-loaded.png');
// → .testdriver/screenshots/my-test/dashboard-loaded.png
```

--------------------------------

### Install Windows software via winget

Source: https://docs.testdriver.ai/v7/copilot/running-tests

Uses winget to install Windows applications silently.

```javascript
await testdriver.exec("pwsh", `
  winget install --id=7zip.7zip -e --silent
`, 120000);
```

--------------------------------

### Configure Linux machine options

Source: https://docs.testdriver.ai/v7/copilot/running-tests

Example of passing configuration options to the TestDriver instance for Linux environments.

```javascript
const testdriver = TestDriver(context, {
  os: "linux",
  resolution: "1920x1080",
  keepAlive: 5 * 60 * 1000, // keep alive 5 minutes
});
```

--------------------------------

### Install Software via PowerShell

Source: https://docs.testdriver.ai/v7/exec

Use testdriver.exec to run package managers or installers within the Windows environment.

```javascript
// Install npm package globally
await testdriver.exec('pwsh', 'npm install -g http-server', 30000);

// Install via Chocolatey
await testdriver.exec('pwsh', 'choco install firefox -y', 60000);

// Download and run installer
await testdriver.exec('pwsh', `
  Invoke-WebRequest -Uri "https://example.com/setup.exe" -OutFile "C:\\setup.exe"
  Start-Process -FilePath "C:\\setup.exe" -ArgumentList "/S" -Wait
`, 120000);
```

--------------------------------

### testdriver.provision.dashcam

Source: https://docs.testdriver.ai/v7/provision

Configures and starts the Dashcam recording service.

```APIDOC
## testdriver.provision.dashcam(options)

### Description
Configures and starts the Dashcam recording service with custom log and title settings.

### Parameters
- **options** (ProvisionDashcamOptions) - Required
  - **logPath** (string) - Optional - Log file path
  - **logName** (string) - Optional - Default: "TestDriver Log"
  - **webLogs** (boolean) - Optional - Default: true
  - **title** (string) - Optional - Recording title
```

--------------------------------

### Run Windows setup script

Source: https://docs.testdriver.ai/v7/copilot/running-tests

Executes a PowerShell script to configure environment variables.

```javascript
await testdriver.provision.chrome({ url: "https://myapp.com" });

await testdriver.exec("pwsh", `
  $env:API_URL = "https://staging.myapp.com"
  Write-Host "Environment configured"
`, 15000);
```

--------------------------------

### Launch Visual Studio Code

Source: https://docs.testdriver.ai/v7/provision

Starts VS Code with a specified workspace and pre-installed extensions.

```javascript
await testdriver.provision.vscode(options?)
```

```javascript
await testdriver.provision.vscode({
  workspace: '/home/testdriver/project',
  extensions: ['ms-python.python', 'esbenp.prettier-vscode'],
});
```

--------------------------------

### Manual Dashcam Setup

Source: https://docs.testdriver.ai/v7/dashcam

Initialize a Dashcam instance manually for granular control over authentication and recording lifecycle.

```javascript
import TestDriver from 'testdriverai';
import Dashcam from 'testdriverai/lib/core/Dashcam.js';

const client = await TestDriver.create({ os: 'linux' });
const dashcam = new Dashcam(client, {
  apiKey: process.env.DASHCAM_API_KEY
});

await dashcam.auth();
await dashcam.start();

// Run your tests

const url = await dashcam.stop();
console.log('Replay URL:', url);
```

--------------------------------

### Example usage of find()

Source: https://docs.testdriver.ai/v7/elements

Demonstrates finding elements using various descriptive strategies.

```javascript
// Find a button
const submitButton = await testdriver.find('the submit button');

// Find an input field with context
const emailField = await testdriver.find('email input field in the login form');

// Find an element by visual characteristics
const redButton = await testdriver.find('red button in the top right corner');
```

--------------------------------

### testdriver.provision.chromeExtension()

Source: https://docs.testdriver.ai/v7/provision

Installs and launches a Chrome extension from a local path or the Chrome Web Store.

```APIDOC
## testdriver.provision.chromeExtension(options)

### Description
Install and launch a Chrome extension. One of extensionPath or extensionId is required.

### Parameters
- **options** (ProvisionChromeExtensionOptions) - Required
  - **extensionPath** (string) - Optional - Local path to an unpacked extension directory.
  - **extensionId** (string) - Optional - Chrome Web Store extension ID to install.
  - **maximized** (boolean) - Optional - Launch Chrome in maximized window mode (default: true)

### Request Example
await testdriver.provision.chromeExtension({ extensionId: 'abcdefghijklmnop' });
```

--------------------------------

### Basic scrolling examples

Source: https://docs.testdriver.ai/v7/scroll

Demonstrates scrolling up or down with optional pixel amounts.

```javascript
// Scroll down (default)
await testdriver.scroll();

// Scroll down 5 clicks
await testdriver.scroll('down', { amount: 5 });

// Scroll up
await testdriver.scroll('up');

// Scroll up 2 clicks
await testdriver.scroll('up', { amount: 2 });
```

--------------------------------

### Configure Windows machine options

Source: https://docs.testdriver.ai/v7/copilot/running-tests

Example of passing configuration options to the TestDriver instance for Windows environments.

```javascript
const testdriver = TestDriver(context, {
  os: "windows",
  resolution: "1920x1080",
  keepAlive: 10 * 60 * 1000, // keep alive 10 minutes
});
```

--------------------------------

### Implement Full Screenshot Workflow

Source: https://docs.testdriver.ai/v7/screenshots

Example of enabling auto-screenshots and manually capturing specific moments during a test flow.

```javascript
import { describe, it, beforeAll, afterAll } from 'vitest';
import TestDriver from 'testdriverai';

describe('Screenshot Example', () => {
  let testdriver;

  beforeAll(async () => {
    testdriver = new TestDriver({
      autoScreenshots: true,   // capture every step
    });
    await testdriver.ready();
    await testdriver.provision.chrome({ url: 'https://example.com' });
  });

  afterAll(async () => {
    await testdriver.disconnect();
  });

  it('captures the login flow', async () => {
    // Auto-screenshots capture before/after each command

    // Manual screenshot for a specific moment
    await testdriver.screenshot('initial-page-load');

    const username = await testdriver.find('username input');
    await username.click();
    await testdriver.type('testuser@example.com');

    await testdriver.screenshot('after-username-entry');

    const password = await testdriver.find('password input');
    await password.click();
    await testdriver.type('password123');

    await testdriver.find('login button').click();

    await testdriver.screenshot('after-login-click');
  });
});
```

--------------------------------

### Example screenshot metadata response

Source: https://docs.testdriver.ai/v7/debugging-with-screenshots

Sample JSON output returned by the list_local_screenshots command.

```json
// Basic listing
[
  {
    "path": "/Users/user/project/.testdriver/screenshots/login.test/001-click-before-L42-submit-button.png",
    "relativePath": "login.test/001-click-before-L42-submit-button.png",
    "name": "001-click-before-L42-submit-button.png",
    "sizeBytes": 145632,
    "modified": "2026-01-23T10:00:00.000Z",
    "sequence": 1,
    "action": "click",
    "phase": "before",
    "lineNumber": 42,
    "description": "submit-button"
  }
]
```

--------------------------------

### View Screenshot Directory Output

Source: https://docs.testdriver.ai/v7/screenshots

Example of the file structure generated in the screenshot directory after a test run.

```text
.testdriver/screenshots/login-flow.test/
├── initial-page-load.png
├── 001-find-before-L18-username-input.png
├── 002-find-after-L18-username-input.png
├── 003-click-before-L19-username-input.png
├── 004-click-after-L19-username-input.png
├── 005-type-before-L20-testuser-example-com.png
├── 006-type-after-L20-testuser-example-com.png
├── after-username-entry.png
├── 007-find-before-L24-password-input.png
├── ...
```

--------------------------------

### Launch Vitest UI

Source: https://docs.testdriver.ai/v7/copilot/running-tests

Starts the interactive web-based UI for debugging and monitoring test execution.

```bash
vitest --ui
```

--------------------------------

### Example Test Code for Screenshots

Source: https://docs.testdriver.ai/v7/screenshot

A sample test sequence that triggers automatic screenshot generation for each command.

```javascript
// Line 15: Find email input
const emailInput = await testdriver.find("email input");
// Line 16: Click it
await emailInput.click();
// Line 17: Type email
await testdriver.type("user@example.com");
```

--------------------------------

### Start a machine with keepAlive

Source: https://docs.testdriver.ai/v7/copilot/running-tests

Configures a sandbox to persist for a specified duration after the test completes.

```javascript
// first.test.mjs
const testdriver = TestDriver(context, {
  os: "windows",
  keepAlive: 30 * 60 * 1000, // keep alive 30 minutes after this test ends
});

await testdriver.provision.chrome({ url: "https://example.com" });
// ... your test steps
```

--------------------------------

### Coordinate Click Examples

Source: https://docs.testdriver.ai/v7/click

Demonstrates performing different click actions at specific X and Y coordinates.

```javascript
// Click at coordinates
await testdriver.click(500, 300);

// Double-click at coordinates
await testdriver.click(500, 300, 'double-click');

// Right-click at coordinates
await testdriver.click(500, 300, 'right-click');
```

--------------------------------

### Multi-Application Workflow Example

Source: https://docs.testdriver.ai/v7/focus-application

Demonstrates switching between a web browser and system applications like Notepad, including handling dialogs and tab navigation.

```javascript
import { beforeAll, afterAll, describe, it } from 'vitest';
import TestDriver from 'testdriverai';

describe('Multi-Application Workflow', () => {
  let testdriver;

  beforeAll(async () => {
    client = new TestDriver(process.env.TD_API_KEY);
    await testdriver.auth();
    await testdriver.connect();
  });

  afterAll(async () => {
    await testdriver.disconnect();
  });

  it('should work across multiple applications', async () => {
    // Start in browser
    await testdriver.focusApplication('Google Chrome');
    
    // Get data from web page
    const orderNumber = await testdriver.extract('the order number');
    console.log('Order:', orderNumber);
    
    // Open Notepad
    await testdriver.exec('pwsh', 'Start-Process notepad', 5000);
    await new Promise(r => setTimeout(r, 1500));
    
    // Focus Notepad and save data
    await testdriver.focusApplication('Notepad');
    await testdriver.type(`Order Number: ${orderNumber}`);
    await testdriver.type('\n');
    await testdriver.type(`Date: ${new Date().toISOString()}`);
    
    // Save file
    await testdriver.pressKeys(['ctrl', 's']);
    await new Promise(r => setTimeout(r, 500));
    
    await testdriver.type('C:\\order-info.txt');
    await testdriver.pressKeys(['enter']);
    
    // Return to browser
    await testdriver.focusApplication('Google Chrome');
    
    const confirmButton = await testdriver.find('confirm order button');
    await confirmButton.click();
    
    await testdriver.assert('order confirmed');
  });

  it('should switch between browser tabs', async () => {
    await testdriver.focusApplication('Google Chrome');
    
    // Open new tab
    await testdriver.pressKeys(['ctrl', 't']);
    await new Promise(r => setTimeout(r, 500));
    
    // Navigate to URL
    await testdriver.pressKeys(['ctrl', 'l']);
    await testdriver.type('https://example.com');
    await testdriver.pressKeys(['enter']);
    
    await new Promise(r => setTimeout(r, 2000));
    
    // Ensure Chrome is still focused
    await testdriver.focusApplication('Google Chrome');
    
    await testdriver.assert('example.com page is loaded');
  });

  it('should handle dialog boxes', async () => {
    await testdriver.focusApplication('Google Chrome');
    
    const deleteButton = await testdriver.find('delete account button');
    await deleteButton.click();
    
    await new Promise(r => setTimeout(r, 500));
    
    // Dialog appears - make sure it's focused
    await testdriver.focusApplication('Google Chrome');
    
    const confirmBtn = await testdriver.find('confirm deletion button');
    await confirmBtn.click();
  });
});
```

--------------------------------

### Listen to Sandbox Events

Source: https://docs.testdriver.ai/v7/events

Subscribe to sandbox lifecycle events to track connection status and setup progress.

```javascript
testdriver.emitter.on('sandbox:connected', () => {
  console.log('Connected to sandbox');
});

testdriver.emitter.on('sandbox:progress', ({ step, message }) => {
  console.log(`Sandbox: [${step}] ${message}`);
});
```

--------------------------------

### Listen to command start events

Source: https://docs.testdriver.ai/v7/events

Access the emitter via testdriver.emitter to subscribe to specific lifecycle events.

```javascript
testdriver.emitter.on('command:start', (data) => {
  console.log(`Running: ${data.command}`);
});
```

--------------------------------

### Run a test on Linux

Source: https://docs.testdriver.ai/v7/copilot/running-tests

Basic setup for running a test on a Linux VM using the TestDriver Vitest hook.

```javascript
import { describe, expect, it } from "vitest";
import { TestDriver } from "testdriverai/vitest/hooks";

describe("My Test", () => {
  it("runs on Linux", async (context) => {
    const testdriver = TestDriver(context);

    await testdriver.provision.chrome({ url: "https://example.com" });

    const result = await testdriver.assert("the page loaded successfully");
    expect(result).toBeTruthy();
  });
});
```

--------------------------------

### Launch VS Code Test Script

Source: https://docs.testdriver.ai/v7/examples/launch-vscode-linux

Uses the TestDriver provision hook to launch VS Code and verify the window is active. The example includes commented-out logic for installing and verifying extensions.

```javascript
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();
  //   },
  // );
});
```

--------------------------------

### Full Checkout Flow Example

Source: https://docs.testdriver.ai/v7/captcha

Complete test case demonstrating captcha integration within a Vitest checkout flow.

```javascript
import { describe, expect, it } from "vitest";
import { TestDriver } from "testdriver";

describe("Checkout flow", () => {
  it("should complete checkout with captcha", async (context) => {
    const testdriver = TestDriver(context);

    // Navigate to checkout page
    await testdriver.provision.chrome({
      url: 'https://example.com/checkout',
    });

    // Fill out form
    await testdriver.type({ text: 'John Doe', selector: '#name' });
    await testdriver.type({ text: 'john@example.com', selector: '#email' });

    // Solve the captcha
    const result = await testdriver.captcha({
      apiKey: process.env.TWOCAPTCHA_API_KEY,
    });

    expect(result.success).toBe(true);

    // Submit the form
    await testdriver.click({ selector: '#submit' });

    // Verify success
    await testdriver.find({ text: 'Order confirmed' });
  }, 180000);
});
```

--------------------------------

### Configure API keys via environment variables

Source: https://docs.testdriver.ai/v7/client

Demonstrates the required .env configuration and the corresponding client initialization without explicit key passing.

```bash
TD_API_KEY=your_api_key_here
```

```javascript
// API key is loaded automatically - no need to pass it!
const testdriver = new TestDriver();
```

--------------------------------

### Install Windows software via Chocolatey

Source: https://docs.testdriver.ai/v7/copilot/running-tests

Uses Chocolatey to install Windows applications.

```javascript
await testdriver.exec("pwsh", `
  choco install googlechrome --yes --no-progress
`, 180000);
```

--------------------------------

### Install TestDriver Dependencies

Source: https://docs.testdriver.ai

Install the required Vitest and TestDriver packages as development dependencies.

```bash
npm install --save-dev vitest testdriverai
```

--------------------------------

### new Dashcam(client, options)

Source: https://docs.testdriver.ai/v7/dashcam

Initializes a new Dashcam instance to manage test recording.

```APIDOC
## new Dashcam(client, options)

### Description
Creates a new Dashcam instance to handle test recording and log aggregation.

### Parameters
- **client** (TestDriver) - Required - The TestDriver client instance.
- **options** (object) - Optional - Configuration options.
  - **apiKey** (string) - Optional - Dashcam API key for authentication.
  - **autoStart** (boolean) - Optional - Automatically start recording after authentication (default: false).
  - **logs** (array) - Optional - Log configurations to add automatically (default: []).
```

--------------------------------

### Verify TestDriver Installation

Source: https://docs.testdriver.ai

Test the installation by requesting the agent to write a test in the chat interface.

```text
@testdriver write a test that opens the homepage and asserts the title
```

--------------------------------

### Chrome Extension Test Example

Source: https://docs.testdriver.ai/v7/copilot/running-tests

A complete test suite example for interacting with a loaded Chrome extension.

```javascript
import { describe, expect, it } from "vitest";
import { TestDriver } from "testdriverai/vitest/hooks";

describe("Chrome Extension Test", () => {
  it("should load and interact with extension", async (context) => {
    const testdriver = TestDriver(context);

    // Clone extension from GitHub
    await testdriver.exec(
      'sh',
      'git clone https://github.com/user/my-extension.git /tmp/my-extension',
      60000,
      true
    );

    // Launch Chrome with extension loaded
    await testdriver.provision.chromeExtension({
      extensionPath: '/tmp/my-extension',
      url: 'https://testdriver.ai'
    });

    // Click extensions puzzle icon
    const extensionsButton = await testdriver.find("puzzle-shaped icon in Chrome toolbar");
    await extensionsButton.click();

    // Interact with your extension
    const myExtension = await testdriver.find("My Extension in the dropdown");
    await myExtension.click();

    const result = await testdriver.assert("extension popup is visible");
    expect(result).toBeTruthy();
  });
});
```

--------------------------------

### Launch Electron Application

Source: https://docs.testdriver.ai/v7/provision

Initializes an Electron application using the specified path and optional command-line arguments.

```javascript
await testdriver.provision.electron(options)
```

```javascript
await testdriver.provision.electron({
  appPath: '/home/testdriver/my-electron-app',
  args: ['--no-sandbox'],
});
```

--------------------------------

### Implement Chrome Extension Test Suite

Source: https://docs.testdriver.ai/v7/provision

A complete example demonstrating how to initialize TestDriver, provision a Chrome extension, and configure Dashcam logging within a Vitest test suite.

```javascript
import { describe, it, beforeAll, afterAll } from 'vitest';
import TestDriver from 'testdriverai';

describe('Chrome Extension Test', () => {
  let testdriver;

  beforeAll(async () => {
    testdriver = new TestDriver({
      os: 'linux',
      resolution: '1920x1080',
    });
    
    await testdriver.ready();
    
    // Install extension and open Chrome
    await testdriver.provision.chromeExtension({
      extensionPath: './my-extension',
    });
    
    // Start Dashcam with custom logs
    await testdriver.provision.dashcam({
      title: 'Extension Test',
      webLogs: true,
    });
  });

  afterAll(async () => {
    await testdriver.disconnect();
  });

  it('tests the extension popup', async () => {
    await testdriver.find('extension icon').click();
    await testdriver.find('popup content').click();
  });
});
```

--------------------------------

### Initialize and connect the TestDriver client

Source: https://docs.testdriver.ai/v7/client

Sets up the client with OS and resolution preferences, attaches event listeners, and manages the connection lifecycle within a test suite.

```javascript
import { beforeAll, afterAll, describe, it } from 'vitest';
import TestDriver from 'testdriverai';

describe('My Test Suite', () => {
  let testdriver;

  beforeAll(async () => {
    // Initialize client - API key loaded automatically from .env
    testdriver = new TestDriver({
      os: 'windows',
      resolution: '1366x768',
      logging: true
    });
    
    // Set up event listeners
    const emitter = testdriver.getEmitter();
    emitter.on('log:info', (msg) => console.log('[INFO]', msg));
    
    // Authenticate and connect
    await testdriver.auth();
    const instance = await testdriver.connect();
    
    console.log('Connected to sandbox:', instance.instanceId);
  });

  afterAll(async () => {
    await testdriver.disconnect();
  });

  it('runs a test', async () => {
    // Your test code here
  });
});
```

--------------------------------

### testdriver.provision.electron(options)

Source: https://docs.testdriver.ai/v7/provision

Launches an Electron application using the specified path and command-line arguments.

```APIDOC
## testdriver.provision.electron(options)

### Description
Launch an Electron application.

### Parameters
- **options** (ProvisionElectronOptions) - Required
  - **appPath** (string) - Required - Path to the Electron application directory or executable.
  - **args** (string[]) - Optional - Additional command-line arguments to pass to the Electron app.

### Example
```javascript
await testdriver.provision.electron({
  appPath: '/home/testdriver/my-electron-app',
  args: ['--no-sandbox'],
});
```
```

--------------------------------

### testdriver.provision.chromeExtension

Source: https://docs.testdriver.ai/v7/provision

Provisions a Chrome browser instance with a specific extension installed.

```APIDOC
## testdriver.provision.chromeExtension(options)

### Description
Provisions a Chrome browser instance with a specific extension installed.

### Parameters
- **options** (ProvisionChromeExtensionOptions) - Required
  - **extensionPath** (string) - Optional - Local unpacked extension path
  - **extensionId** (string) - Optional - Chrome Web Store ID
  - **maximized** (boolean) - Optional - Default: true
```

--------------------------------

### Provide Guidance

Source: https://docs.testdriver.ai/v7/generating-tests

Instructions provided to the agent during execution to handle UI elements like modals.

```text
The login modal appeared. Use test@example.com and password123
```

--------------------------------

### Configure Cache Thresholds

Source: https://docs.testdriver.ai/v7/cache

Examples of setting cache thresholds via per-command options, legacy arguments, and global constructor configuration.

```javascript
find(desc, { cache: { thresholds: { screen: 0.1 } } })
```

```javascript
find(desc, 0.1)
```

```javascript
new TestDriver({ cache: { thresholds: { find: { screen: 0.1 } } } })
```

--------------------------------

### Finding Multiple Items

Source: https://docs.testdriver.ai/v7/find

Example of locating list items and accessing them by index.

```javascript
// Find all list items
const items = await testdriver.findAll('list item');

// Find specific item by index
const thirdItem = items[2];
await thirdItem.click();

// Check all items
for (let i = 0; i < items.length; i++) {
  console.log(`Item ${i + 1}: ${items[i].text || 'No text'}`);
}
```

--------------------------------

### Demonstrate basic caching behavior

Source: https://docs.testdriver.ai/v7/caching

Shows how the first call to find an element builds the cache, while subsequent calls result in an instant match.

```javascript
// First run: builds cache
await testdriver.find('submit button');

// Second run: exact match
await testdriver.find('submit button');
```

--------------------------------

### Form Filling Workflow

Source: https://docs.testdriver.ai/v7/type

Example of navigating through a form and typing into multiple fields.

```javascript
// Focus field and type
const emailField = await testdriver.find('email input');
await emailField.click();
await testdriver.type('user@example.com');

// Tab to next field and type
await testdriver.pressKeys(['tab']);
await testdriver.type('John Doe');

// Type password securely
await testdriver.pressKeys(['tab']);
await testdriver.type('MySecureP@ssw0rd', { secret: true });
```

--------------------------------

### Configure keepAlive duration

Source: https://docs.testdriver.ai/v7/copilot/running-tests

Examples of setting different keepAlive durations in milliseconds.

```javascript
const testdriver = TestDriver(context, {
  keepAlive: 0,           // currently uses the default 1 minute grace period
  // keepAlive: 60000,    // default — 1 minute
  // keepAlive: 600000,   // 10 minutes
  // keepAlive: 3600000,  // 1 hour
});
```

--------------------------------

### Configure Auto-start Recording

Source: https://docs.testdriver.ai/v7/dashcam

Initialize the Dashcam with auto-start enabled and pre-configured log paths.

```javascript
test('auto-start recording', async () => {
  const client = await TestDriver.create({ os: 'linux' });
  const dashcam = new Dashcam(client, {
    autoStart: true,
    logs: [
      {
        name: 'App Log',
        type: 'file',
        path: '/tmp/app.log'
      }
    ]
  });
  
  await dashcam.auth(); // Automatically starts recording
  
  // Test execution
  await client.find('submit button').then(el => el.click());
  
  const url = await dashcam.stop();
  console.log('Replay:', url);
  
  await client.cleanup();
});
```

--------------------------------

### Example Conversation Log

Source: https://docs.testdriver.ai/v7/generating-tests

A transcript showing the interaction between the user and the agent during test generation.

```text
You: Create a test for the login flow at https://console.testdriver.ai

Agent: I'll create a test for the login flow. Starting a session...
       [Screenshot: Login page loaded]

       I can see the login page. Let me find the email input.
       [Screenshot: Email input highlighted]

       Now I'll type the email and find the password field...

You: Use test@example.com for the email

Agent: Got it. Typing test@example.com...
       [Screenshot: Email entered]

       Now entering the password and clicking Sign In...
       [Screenshot: Dashboard loaded]

       ✅ Login successful! I've written the test to tests/login.test.mjs
```

--------------------------------

### Element Property Output

Source: https://docs.testdriver.ai/v7/making-assertions

Example of the object structure returned when inspecting a found element.

```javascript
{
  description: 'submit button',
  found: true,
  x: 150,
  y: 300,
  coordinates: { x: 150, y: 300, centerX: 200, centerY: 320 },
  threshold: 0.8,
  confidence: 0.95,
  similarity: 0.92,
  selector: 'button[type="submit"]',
  cache: {
    hit: true,
    strategy: 'pixel-diff',
    createdAt: '2025-01-15T10:30:00Z',
    diffPercent: 0.02,
    imageUrl: 'https://...'
  }
}
```

--------------------------------

### testdriver.provision.chrome()

Source: https://docs.testdriver.ai/v7/provision

Launches Google Chrome in the sandbox with optional configuration for URL, window state, and profile mode.

```APIDOC
## testdriver.provision.chrome(options?)

### Description
Launch Google Chrome with an optional URL and configuration settings.

### Parameters
- **options** (ProvisionChromeOptions) - Optional
  - **url** (string) - Optional - URL to navigate to after launch (default: http://testdriver-sandbox.vercel.app/)
  - **maximized** (boolean) - Optional - Launch Chrome in maximized window mode (default: true)
  - **guest** (boolean) - Optional - Launch Chrome in guest profile mode (default: false)

### Request Example
await testdriver.provision.chrome({ url: 'https://example.com', guest: true, maximized: true });
```
Tokens:
Raw