Skip to main content
TestDriver automatically provisions isolated cloud sandboxes for every test run, eliminating the need to manage browsers, VMs, or infrastructure.

​
Automatic Provisioning

Every test gets its own fresh sandbox environment: 
import { test } from 'vitest';
import { chrome } from 'testdriverai/presets';

test('automatic sandbox', async (context) => {
  // TestDriver automatically provisions a sandbox with Chrome
  const { testdriver } = await chrome(context, {
    url: 'https://example.com'
  });

  // Test runs in an isolated cloud environment
  await testdriver.find('button').click();
  await testdriver.assert('page loaded');
  
  // Sandbox automatically cleaned up after test
});
No setup required - sandboxes are created on-demand and destroyed after each test.

​
What’s Included

Each sandbox comes pre-configured with everything you need:

Operating Systems

  • Ubuntu Linux (default)
  • Windows 10/11
  • macOS (coming soon)

Browsers

  • Google Chrome
  • Chromium
  • Firefox (beta)
  • Edge (beta)

Desktop Apps

  • Any Linux application
  • Windows applications
  • Electron apps

Development Tools

  • VS Code
  • Node.js
  • Python
  • Common dev dependencies

​
Sandbox Configuration

Customize sandbox settings per test: 
import { chrome } from 'testdriverai/presets';

test('choose OS', async (context) => {
  const { testdriver } = await chrome(context, {
    url: 'https://example.com',
    os: 'windows' // 'linux', 'windows', or 'mac'
  });

  // Test runs on Windows sandbox
});

​
Persistent Sandboxes

Keep a sandbox alive across multiple tests for faster execution: 
import { test, beforeAll, afterAll } from 'vitest';
import { chrome } from 'testdriverai/presets';

let testdriver;

beforeAll(async () => {
  // Create persistent sandbox
  const result = await chrome({
    url: 'https://example.com',
    timeout: 600000  // 10 minutes
  });
  testdriver = result.testdriver;
});

test('first test', async () => {
  // Reuses existing sandbox
  await testdriver.find('login button').click();
});

test('second test', async () => {
  // Same sandbox, faster execution
  await testdriver.find('dashboard').click();
});

afterAll(async () => {
  // Clean up sandbox
  await testdriver.close();
});
Persistent sandboxes are faster for test suites but share state between tests. Use fresh sandboxes when test isolation is critical.

​
Sandbox Lifecycle

Understanding how sandboxes are managed:
1

Provisioning

When you call a preset (e.g., chrome()), TestDriver:
  • Allocates a cloud VM
  • Installs the OS and browser
  • Configures network and display
  • Returns ready-to-use testdriver instance
Time: 5-15 seconds
2

Active Testing

Your test runs in the isolated environment:
  • Full browser/desktop control
  • Network access
  • File system access
  • Video recording (Dashcam)
Time: Duration of your test
3

Cleanup

After the test completes:
  • Dashcam replay saved
  • Screenshots captured
  • Sandbox terminated
  • Resources released
Time: Automatic

​
Reconnect to Sandboxes

Debug failed tests by reconnecting to existing sandboxes: 
import { test } from 'vitest';
import { TestDriver } from 'testdriverai';

test('reconnectable sandbox', async () => {
  const testdriver = new TestDriver({
    apiKey: process.env.TD_API_KEY
  });

  const instance = await testdriver.connect();
  console.log('Sandbox ID:', instance.instanceId);
  
  // Save this ID for debugging
  // export TESTDRIVER_SANDBOX_ID=i-0abc123def
  
  await testdriver.find('button').click();
});
Then reconnect later: 
# Set sandbox ID
export TESTDRIVER_SANDBOX_ID=i-0abc123def

# Run debugging session
node debug-script.js

Debugging Guide

Complete guide to debugging with sandbox reconnection

​
Network Isolation

Each sandbox is network-isolated by default: 
import { chrome } from 'testdriverai/presets';

test('isolated network', async (context) => {
  const { testdriver } = await chrome(context, {
    url: 'https://example.com'
  });

  // Sandbox has its own IP address
  // No shared cookies or cache with other tests
  // Clean slate for every test run
});
Network isolation prevents test interference and ensures consistent results across runs.

​
Resource Limits

Understanding sandbox constraints:
  • CPU: 2 vCPUs per sandbox
  • Memory: 4GB RAM
  • Disk: 20GB storage
Sufficient for most testing scenarios including heavy web apps and desktop applications.
  • Speed: 100 Mbps connection
  • Timeout: 30s per network request
  • Proxies: Supported via environment variables
Fast enough for realistic load times and asset downloads.
  • Default: 2 minutes per test
  • Maximum: 30 minutes (configurable)
  • Idle timeout: 5 minutes of inactivity
Customize with the timeout option in preset configuration.
  • Free tier: 2 concurrent sandboxes
  • Pro tier: 10 concurrent sandboxes
  • Enterprise: Unlimited concurrent sandboxes
Run tests in parallel for faster CI/CD pipelines.

​
Cost & Billing

Sandboxes are billed based on usage:

Pricing Model

Sandbox time: Charged per minute of VM runtime
  • Provisioning: ~10 seconds (included)
  • Active testing: Pay per minute
  • Cleanup: Automatic (included)
Example costs:
  • 1-minute test: $0.02
  • 5-minute test: $0.10
  • 100 tests @ 2min each: $4.00
Optimization tips:
  • Use persistent sandboxes for test suites
  • Enable caching to reduce test duration
  • Run tests in parallel to maximize efficiency

​
Self-Hosted Sandboxes

For enterprise customers who need on-premise infrastructure:
docker-compose.yml
version: '3'
services:
  testdriver-runner:
    image: testdriver/runner:latest
    environment:
      - TD_API_KEY=${TD_API_KEY}
      - TD_RUNNER_MODE=self-hosted
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

Self-Hosting Guide

Complete guide to running TestDriver on your own infrastructure

​
Learn More

Debugging Guide

Debug tests with sandbox reconnection

Self-Hosting

Run sandboxes on your infrastructure

Performance Optimization

Optimize sandbox usage and costs

Enterprise Features

Enterprise sandbox capabilities