testdriver:device-config

<!-- Generated from device-config.mdx. DO NOT EDIT. -->

Provision methods are the starting point for most tests. They launch applications in your sandbox and prepare the environment for testing.

Chrome Browser

The most common starting point for web testing. Launches Chrome browser and navigates to a URL.

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

Options

Option	Type	Default	Description
url	string	'http://testdriver-sandbox.vercel.app/'	URL to navigate to
maximized	boolean	true	Start browser maximized
guest	boolean	false	Use guest mode (no profile)

Example: Basic Web Test

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();
  });
});

<Info> `provision.chrome()` automatically starts Dashcam recording and waits for Chrome to be ready before returning. </Info>

---

Chrome Extensions

Launch Chrome with a custom extension loaded. Supports both local extensions and Chrome Web Store extensions.

Load from Local Path

Clone or create an extension locally, then load it:

// First, get the extension onto the sandbox
await testdriver.exec(
  'sh',
  'git clone https://github.com/user/my-extension.git /tmp/my-extension',
  60000
);

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

Load from Chrome Web Store

Load any published extension by its Chrome Web Store ID:

await testdriver.provision.chromeExtension({
  extensionId: 'cjpalhdlnbpafiamejdnhcphjbkeiagm', // uBlock Origin
  url: 'https://example.com'
});

<Tip> Find the extension ID in the Chrome Web Store URL. For example, `https://chrome.google.com/webstore/detail/ublock-origin/cjpalhdlnbpafiamejdnhcphjbkeiagm` → ID is `cjpalhdlnbpafiamejdnhcphjbkeiagm` </Tip>

Options

Option	Type	Default	Description
extensionPath	string	-	Local path to unpacked extension directory
extensionId	string	-	Chrome Web Store extension ID
url	string	-	URL to navigate to after launch
maximized	boolean	true	Start browser maximized

<Warning> You must provide either `extensionPath` or `extensionId`, but not both. </Warning>

Example: Testing a Chrome Extension

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();
  });
});

---

Desktop Apps

Download and install desktop applications. Supports .deb, .rpm, .msi, .exe, .AppImage, .dmg, .pkg, and shell scripts.

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
});

Options

Option	Type	Default	Description
url	string	required	URL to download the installer from
filename	string	auto-detected	Filename to save as
appName	string	-	Application name to focus after install
launch	boolean	true	Launch the app after installation

Supported File Types

Extension	OS	Install Method
.deb	Linux	dpkg -i + apt-get install -f
.rpm	Linux	rpm -i
.AppImage	Linux	chmod +x
.sh	Linux	chmod +x + execute
.msi	Windows	msiexec /i /quiet
.exe	Windows	Silent install (/S)
.dmg	macOS	Mount + copy to Applications
.pkg	macOS	installer -pkg

Example: Install and Test a Desktop App

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');
  });
});

Example: Windows Installer

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();
  });
});

Manual Installation

Set launch: false to download without auto-installing:

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);

---

VS Code

Launch Visual Studio Code with optional workspace and extensions.

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

Options

Option	Type	Default	Description
workspace	string	-	Workspace folder to open
extensions	string[]	[]	Extensions to install (by ID)

Example: VS Code Extension Test

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();
  });
});

---

Choosing the Right Provision Method

Use Case	Method
Testing a website	provision.chrome
Testing a Chrome extension	provision.chromeExtension
Testing a desktop app (needs installation)	provision.installer
Testing VS Code or VS Code extensions	provision.vscode

<Tip> All provision methods automatically start Dashcam recording and wait for the application to be ready before returning. You don't need to call `dashcam.start()` manually. </Tip>