Spawning a sandbox

Overview

The Provision API sets up applications in your sandbox before the tests run. It downloads, installs, and starts browsers, desktop apps, VS Code, Chrome extensions, and more. Use the provision methods through testdriver.provision.*:

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

Methods

chrome()

Start Google Chrome with an optional URL.

await testdriver.provision.chrome(options?)

ProvisionChromeOptions

Show properties

string

default:"http://testdriver-sandbox.vercel.app/"

The URL to go to after Chrome starts.

boolean

default:true

Start Chrome with the window at the maximum size.

boolean

default:false

Start Chrome in the guest profile mode.

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

// With guest mode
await testdriver.provision.chrome({
  url: 'https://example.com',
  guest: true,
  maximized: true,
});

chromeExtension()

Install and start a Chrome extension. You can install it from a local unpacked directory. Or you can install it from the Chrome Web Store by the extension ID.

await testdriver.provision.chromeExtension(options)

ProvisionChromeExtensionOptions

required

One of extensionPath or extensionId is required.

Show properties

string

Local path to an unpacked extension directory. The extension files are uploaded to the sandbox.

string

Chrome Web Store extension ID to install.

boolean

default:true

Launch Chrome in maximized window mode.

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

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

vscode()

Launch Visual Studio Code with an optional workspace and extensions.

await testdriver.provision.vscode(options?)

ProvisionVSCodeOptions

Show properties

string

Path to a workspace folder or .code-workspace file to open.

string[]

default:[]

Array of VS Code extension IDs to install before launching.

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

installer()

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

await testdriver.provision.installer(options)

ProvisionInstallerOptions

required

Show properties

string

required

Download URL for the installer.

string

Override the auto-detected filename from the URL.

string

Application name to focus after installation completes.

boolean

default:true

Whether to focus/launch the app after installation.

Behavior:

Downloads the installer from the URL
Auto-detects the install method based on file extension
Runs the appropriate install command (e.g., msiexec for .msi, dpkg for .deb)
Optionally focuses the installed application

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

electron()

Launch an Electron application.

await testdriver.provision.electron(options)

ProvisionElectronOptions

required

Show properties

string

required

Path to the Electron application directory or executable.

string[]

default:[]

Additional command-line arguments to pass to the Electron app.

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

dashcam()

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

await testdriver.provision.dashcam(options?)

ProvisionDashcamOptions

Show properties

string

Path to the TestDriver log file. Defaults to /tmp/testdriver.log (Linux) or C:\Users\testdriver\testdriver.log (Windows).

string

default:"TestDriver Log"

Display name for the log file in the Dashcam replay.

boolean

default:true

Enable web traffic log capture.

string

Recording title for the Dashcam session.

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

Types

interface ProvisionChromeOptions {
  url?: string;                    // Default: "http://testdriver-sandbox.vercel.app/"
  maximized?: boolean;             // Default: true
  guest?: boolean;                 // Default: false
}

interface ProvisionChromeExtensionOptions {
  extensionPath?: string;          // Local unpacked extension path
  extensionId?: string;            // Chrome Web Store ID
  maximized?: boolean;             // Default: true
}

interface ProvisionVSCodeOptions {
  workspace?: string;              // Workspace path
  extensions?: string[];           // Extension IDs to install
}

interface ProvisionInstallerOptions {
  url: string;                     // Download URL (required)
  filename?: string;               // Override filename
  appName?: string;                // App name to focus
  launch?: boolean;                // Default: true
}

interface ProvisionElectronOptions {
  appPath: string;                 // Path to Electron app (required)
  args?: string[];                 // Additional args
}

interface ProvisionDashcamOptions {
  logPath?: string;                // Log file path
  logName?: string;                // Default: "TestDriver Log"
  webLogs?: boolean;               // Default: true
  title?: string;                  // Recording title
}

Complete Example

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

Overview

Using TestDriver

Building & Maintaining Tests

Advanced Topics

Overview

Methods

chrome()

chromeExtension()

vscode()

installer()

electron()

dashcam()

Types

Complete Example

​Overview

​Methods

​chrome()

​chromeExtension()

​vscode()

​installer()

​electron()

​dashcam()

​Types

​Complete Example

Overview

Methods

chrome()

chromeExtension()

vscode()

installer()

electron()

dashcam()

Types

Complete Example