Launch apps in the sandbox

Start Chrome, a Chrome extension, VS Code, an Electron app, or an installer in the sandbox.

Start the app you want to test with a provision method. Call one at the beginning of each test.

await testdriver.provision.chrome({ url: 'https://testdriver-sandbox.vercel.app/login' });

Every provision method:

• Launches or installs the app in the sandbox. The Chrome methods also wait until Chrome is ready.
• Starts the Dashcam recording, unless you turned it off with dashcam: false.
• Does nothing when the client was created with reconnect: true, because the app is already running.

Method	Use it to test
chrome()	A website
chromeExtension()	A Chrome extension
vscode()	VS Code or a VS Code extension
installer()	A desktop app you download and install
electron()	An Electron app
dashcam()	Custom recording settings

chrome(options)

Opens Chrome at a URL.

testdriver.provision.chrome(options?: ProvisionChromeOptions): Promise<void>

options · ProvisionChromeOptions

Show properties

url · string · default: "http://testdriver-sandbox.vercel.app/"

The page to open.

maximized · boolean · default: "true"

Start with the window maximized.

guest · boolean · default: "false"

Use Chrome’s guest profile, with no saved data.

Chrome also records the site’s network traffic in the Dashcam replay.

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

chromeExtension(options)

Opens Chrome with an extension loaded.

testdriver.provision.chromeExtension(options: ProvisionChromeExtensionOptions): Promise<void>

options · ProvisionChromeExtensionOptions · required

Pass either extensionId or extensionPath. It throws if you pass neither.

Show properties

extensionId · string

A Chrome Web Store extension ID. TestDriver downloads the extension into the sandbox.

extensionPath · string

The path to an unpacked extension inside the sandbox. Nothing is copied from your machine, so get the files there first, for example with exec().

maximized · boolean · default: "true"

Start with the window maximized.

From the Chrome Web Store:

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

From source:

await testdriver.exec({
  language: 'sh',
  code: 'git clone https://github.com/your-org/your-extension.git /tmp/your-extension',
});
await testdriver.provision.chromeExtension({ extensionPath: '/tmp/your-extension' });

vscode(options)

Opens VS Code, optionally with a folder and extensions.

testdriver.provision.vscode(options?: ProvisionVSCodeOptions): Promise<void>

options · ProvisionVSCodeOptions

Show properties

workspace · string

A folder or .code-workspace file in the sandbox to open.

extensions · string[] · default: "[]"

Marketplace extension IDs to install before VS Code opens.

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

installer(options)

Downloads a file into the sandbox, installs it, and returns the downloaded file’s path.

testdriver.provision.installer(options: ProvisionInstallerOptions): Promise<string>

options · ProvisionInstallerOptions · required

Show properties

url · string · required

Where to download the file from.

filename · string

The name to save the file as. By default, it comes from the download.

appName · string

The app to bring to the front after installing.

launch · boolean · default: "true"

Start the app after installing it.

• .deb on Linux: starts the app from its .desktop entry. If there isn’t one and you set appName, it starts the package’s first /usr/bin program.
• .sh scripts: runs the script.
• Everywhere: focuses appName, if you set it.

With false, packages are still installed, and a script is only made executable.

TestDriver picks the install method from the file extension:

OS	Extension	What happens
Windows	.msi	Installed quietly with msiexec
Windows	.exe	Run with /S for a silent install
Linux	.deb	Installed with dpkg. Missing dependencies are installed with apt-get, and the step fails if the package still isn’t fully installed
Linux	.rpm	Installed with rpm
Linux	.AppImage	Made executable
Linux	.sh	Made executable and run (only made executable with launch: false)
macOS	.dmg, .pkg	Copied to Applications, or installed with installer

Other file types are downloaded but not installed.

// Install bat, then check that it runs (bat has no window, so nothing is launched)
await testdriver.provision.installer({
  url: 'https://github.com/sharkdp/bat/releases/download/v0.24.0/bat_0.24.0_amd64.deb',
});
const output = await testdriver.exec({ language: 'sh', code: 'bat --version' });
console.log(output); // for example "bat 0.24.0"

Install a desktop app and start it:

// Installs Yaak and its dependencies, starts it, and brings its window to the front
await testdriver.provision.installer({
  url: 'https://github.com/mountain-loop/yaak/releases/download/v2026.9.0/yaak_2026.9.0_amd64.deb',
  appName: 'Yaak',
});

electron(options)

Opens an Electron app that’s already in the sandbox.

testdriver.provision.electron(options: ProvisionElectronOptions): Promise<void>

options · ProvisionElectronOptions · required

Show properties

appPath · string · required

The path to the app in the sandbox. It throws if this is missing.

args · string[] · default: "[]"

Extra command-line arguments for the app.

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

dashcam(options)

Starts the Dashcam recording with your own settings. The other provision methods start it for you, so call this only to change the log file, the log name, or the recording’s title.

testdriver.provision.dashcam(options?: ProvisionDashcamOptions): Promise<void>

options · ProvisionDashcamOptions

Show properties

logPath · string

A log file in the sandbox to include in the replay. Defaults to /tmp/testdriver.log on Linux, or C:\Users\testdriver\testdriver.log on Windows.

logName · string · default: "TestDriver Log"

The log’s name in the replay.

webLogs · boolean · default: "true"

Record network traffic. It covers the site opened with chrome(), or all traffic otherwise.

title · string

A title for the recording.

await testdriver.provision.dashcam({ title: 'Checkout flow', logPath: '/tmp/my-app.log', logName: 'App log' });

Complete example

tests/extension.test.mjs

import { describe, expect, it } from 'vitest';
import { TestDriver } from 'testdriverai/vitest/hooks';

describe('Loom extension', () => {
  it('appears in the extensions menu', async (context) => {
    const testdriver = TestDriver(context);

    await testdriver.provision.chromeExtension({
      extensionId: 'liecbddmkiiihnedobmlmillhodjkdmb',
    });

    await testdriver.find('puzzle-piece extensions icon in the Chrome toolbar').click();

    const loom = await testdriver.find('Loom in the extensions dropdown');
    expect(loom.found()).toBe(true);
  });
});

Related

• Client & connection: create and connect the client
• exec(): run commands in the sandbox, for example to fetch files before provisioning
• Dashcam: how runs are recorded
• Examples: complete tests that install and launch apps