Installation

Get started with TestDriver in just a few steps. This guide will have you running your first AI-powered test in under 2 minutes.

Fastest Way to Get Started: Use testdriverai init to scaffold a complete project automatically:

npm install -g testdriverai
testdriverai init

This creates everything you need: package.json, test files, Vitest config, GitHub Actions workflow, and prompts for your API key. Then just run npm test!For manual setup, continue with the steps below.

Prerequisites

Node.js

Node.js 18 or higher

node --version
# v18.0.0 or higher

Package Manager

npm, yarn, or pnpm

npm --version
# or
yarn --version
# or
pnpm --version

Step 1: Install TestDriver

Install TestDriver and Vitest test runner:

npm install --save-dev testdriverai vitest

TestDriver works with any test framework (Vitest, Jest, Mocha), but we recommend Vitest for the best experience.

Step 2: Get Your API Key

Visit console.testdriver.ai and create a free account.

Generate API Key

Navigate to Settings → API Keys and generate a new key.The key will look like: tdai-1234567890abcdef1234567890abcdef

Save API Key

Create a .env file in your project root:

.env

TD_API_KEY=tdai-your-api-key-here

Add .env to your .gitignore to avoid committing secrets!

Step 3: Create Your First Test

Create a test file test.test.js:

test.test.js

import { test } from 'vitest';
import { chrome } from 'testdriverai/presets';

test('my first test', async (context) => {
  const { testdriver } = await chrome(context, {
    url: 'https://example.com'
    // apiKey automatically read from process.env.TD_API_KEY
  });

  await testdriver.find('More information link').click();
  await testdriver.assert('IANA page is visible');
});

That’s it! TestDriver automatically handles authentication, browser launch, navigation, video recording, and cleanup.

Step 4: Run Your Test

Run your test with Vitest:

npx vitest run

You should see output like:

✓ test.test.js (1)
  ✓ my first test (12.3s)

Test Files  1 passed (1)
Tests  1 passed (1)
Duration  12.45s

📹 Replay: https://console.testdriver.ai/dashcam/abc123

Click the Dashcam replay URL to watch a video of your test execution!

Optional: Configure Vitest

For a better experience, create a vitest.config.mjs:

vitest.config.mjs

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    testTimeout: 120000,  // 2 minutes per test (TestDriver tests can take longer)
    hookTimeout: 120000,  // 2 minutes for setup/teardown
  },
});

Installation Options

TypeScript Setup

TestDriver includes TypeScript definitions out of the box:

test.test.ts

import { test } from 'vitest';
import { chrome } from 'testdriverai/presets';

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

  const element = await testdriver.find('button');
  // element has full type information
  console.log(element.coordinates.x);
});

No additional setup needed!

Global Installation (Optional)

Install TestDriver CLI globally for project scaffolding and sandbox management:

npm install -g testdriverai

This gives you access to commands like:

# Initialize a new project (recommended!)
testdriverai init

# Spawn a sandbox
testdriverai sandbox spawn

# List active sandboxes
testdriverai sandbox list

# Stop a sandbox
testdriverai sandbox stop i-abc123

The testdriverai init command is the fastest way to start a new project. It creates:

package.json with test scripts
Vitest configuration with TestDriver plugin
Example test file using the chrome preset
GitHub Actions workflow for CI/CD
.gitignore to protect secrets
Installs all dependencies
Prompts for your API key and saves to .env

Learn more about sandbox management

Monorepo Setup

For monorepos, install TestDriver in the root and reference it from test packages:

package.json (root)

{
  "workspaces": ["packages/*"],
  "devDependencies": {
    "testdriverai": "^7.0.0",
    "vitest": "^1.0.0"
  }
}

packages/app/package.json

{
  "scripts": {
    "test": "vitest run"
  }
}

Alternative Test Frameworks

While we recommend Vitest, TestDriver works with any test framework:

Vitest (Recommended)
Jest
Mocha
Node (No Framework)

import { test } from 'vitest';
import { chrome } from 'testdriverai/presets';

test('my test', async (context) => {
  const { testdriver } = await chrome(context, { url });
  // Test code
});

Verify Installation

Run this quick verification to ensure everything is set up correctly:

verify.test.js

import { test } from 'vitest';
import { chrome } from 'testdriverai/presets';

test('verify installation', async (context) => {
  console.log('✓ TestDriver SDK imported');

  const { testdriver, dashcam } = await chrome(context, {
    url: 'https://example.com'
  });
  console.log('✓ Connected to TestDriver sandbox');
  console.log('✓ Chrome browser launched');

  const element = await testdriver.find('More information link');
  console.log('✓ AI vision working');
  console.log('✓ Element found:', element.text);

  await element.click();
  console.log('✓ Click action successful');

  await testdriver.assert('IANA page is visible');
  console.log('✓ AI assertion passed');

  console.log('✓ Dashcam recording:', dashcam.url);
  console.log('\n✅ Installation verified successfully!');
});

Run it:

npx vitest run verify.test.js

Troubleshooting

API Key Not Found

Error: TestDriver API key not foundSolutions:

Check .env file exists in project root
Verify key format: TD_API_KEY=tdai-...
Restart your terminal/IDE to reload environment
Or pass API key directly:

const { testdriver } = await chrome(context, {
  url: 'https://example.com',
  apiKey: 'tdai-your-key-here'
});

Module Not Found

Error: Cannot find module 'testdriverai'Solutions:

Ensure you’re in the correct directory
Run npm install again
Check package.json includes testdriverai
Delete node_modules and reinstall:

rm -rf node_modules package-lock.json
npm install

Test Timeout

Error: Test timed out after 5000msSolution: Increase timeout in vitest config:

vitest.config.mjs

export default defineConfig({
  test: {
    testTimeout: 120000, // 2 minutes
  },
});

TestDriver tests can take longer than unit tests due to AI analysis and browser automation.

TypeScript Errors

Error: Cannot find type definitionsSolution: TestDriver includes types by default, but ensure your tsconfig.json is correct:

tsconfig.json

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "node",
    "esModuleInterop": true
  }
}

Network/Firewall Issues

Error: Failed to connect to TestDriver APISolution:

Check your internet connection
Verify firewall allows outbound HTTPS
If behind corporate proxy, configure:

.env

HTTP_PROXY=http://proxy.company.com:8080
HTTPS_PROXY=http://proxy.company.com:8080

For on-premise deployment, see self-hosting guide.

Next Steps

Now that you have TestDriver installed:

Write Your First Test

Learn how to write effective TestDriver tests

Generate Tests with AI

Use Claude to generate tests automatically

View Examples

See TestDriver in action with examples

API Reference

Explore all available methods

Getting Help

Discord

Join our community

GitHub

Report issues

Documentation

Troubleshooting guide

Overview

Getting Started

Examples

Actions

API Reference

Prerequisites

Node.js

Package Manager

Step 1: Install TestDriver

Step 2: Get Your API Key

Step 3: Create Your First Test

Step 4: Run Your Test

Optional: Configure Vitest

Installation Options

TypeScript Setup

Global Installation (Optional)

Monorepo Setup

Alternative Test Frameworks

Verify Installation

Troubleshooting

Next Steps

Write Your First Test

Generate Tests with AI

View Examples

API Reference

Getting Help

Discord

GitHub

Documentation

Overview

Getting Started

Examples

Actions

API Reference

​Prerequisites

Node.js

Package Manager

​Step 1: Install TestDriver

​Step 2: Get Your API Key

​Step 3: Create Your First Test

​Step 4: Run Your Test

​Optional: Configure Vitest

​Installation Options

​TypeScript Setup

​Global Installation (Optional)

​Monorepo Setup

​Alternative Test Frameworks

​Verify Installation

​Troubleshooting

​Next Steps

Write Your First Test

Generate Tests with AI

View Examples

API Reference

​Getting Help

Discord

GitHub

Documentation

Prerequisites

Step 1: Install TestDriver

Step 2: Get Your API Key

Step 3: Create Your First Test

Step 4: Run Your Test

Optional: Configure Vitest

Installation Options

TypeScript Setup

Global Installation (Optional)

Monorepo Setup

Alternative Test Frameworks

Verify Installation

Troubleshooting

Next Steps

Getting Help