Skip to main content

​
Overview

The Provision API sets up applications in your sandbox before tests run. It handles downloading, installing, and launching browsers, desktop apps, VS Code, Chrome extensions, and more. Access provision methods via testdriver.provision.*: 
await testdriver.provision.chrome({ url: 'https://example.com' });
When reconnect: true is set on the client, all provision methods are skipped since the application is assumed to already be running.

​
Methods

​
chrome()

Launch Google Chrome with an optional URL. 
await testdriver.provision.chrome(options?)
​
options
ProvisionChromeOptions
// 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 launch a Chrome extension. You can install from a local unpacked directory or from the Chrome Web Store by extension ID. 
await testdriver.provision.chromeExtension(options)
​
options
ProvisionChromeExtensionOptions
required
One of extensionPath or extensionId is required.
// 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?)
​
options
ProvisionVSCodeOptions
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)
​
options
ProvisionInstallerOptions
required
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)
​
options
ProvisionElectronOptions
required
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?)
​
options
ProvisionDashcamOptions
await testdriver.provision.dashcam({
  title: 'Login Flow Test',
  logPath: '/tmp/my-app.log',
  logName: 'Application Log',
  webLogs: true,
});

​
Reconnect Behavior

When reconnect: true is set on the client, all provision methods are wrapped in a Proxy that intercepts calls and skips them silently. This is because when reconnecting to an existing sandbox, the applications are already running. 
const testdriver = new TestDriver({
  reconnect: true,
});

await testdriver.ready();

// These calls are silently skipped:
await testdriver.provision.chrome({ url: 'https://example.com' });
await testdriver.provision.dashcam();

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