Quick Start

TestDriver makes it easy to write automated computer-use tests for web browsers, desktop apps, and more. Follow the directions below to run your first TestDriver test.

Join our Discord if you have any questions or need help getting started!

Automatic Setup
Manual Setup

Get started quickly with the TestDriver CLI.

Install TestDriver

Use npx to quickly set up an example project:

npx testdriverai init

This will walk you through creating a new project folder, installing dependencies, setting up your API key, and configuring MCP for your preferred AI assistant (VS Code, Cursor, Claude Desktop, etc.).

Run Your Test

TestDriver uses Vitest as the test runner. To run your test, use:

vitest run

This will spawn a sandbox, launch Chrome, and run the example test!

Install TestDriver and manually create the files yourself.

Create a TestDriver Account

You will need a TestDriver account to get an API key.

Get an API Key

Start with 60 free device minutes, no credit-card required!

Install Dependencies

Install Vitest and TestDriver as dev dependencies:

npm install --save-dev vitest testdriverai

Create a vitest.config.js File

In your project root, create a vitest.config.js file with the following content:

vitest.config.js

import TestDriver from 'testdriverai/vitest';
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    testTimeout: 900000,
    hookTimeout: 900000,
    reporters: [
      'default',
      TestDriver()
    ],
    setupFiles: ['testdriverai/vitest/setup'],
  },
});

Create an Example Test File

Add your API key to the example test file below and save it as test.mjs in your project root.

test.mjs

import { describe, expect, it } from "vitest";
// Import TestDriver from the vitest hooks
import { TestDriver } from "testdriverai/vitest/hooks";

describe("Google Search Example", () => {
  it("should search for TestDriver", async (context) => {
    // Create TestDriver instance - automatically connects to sandbox
    const testdriver = TestDriver(context, {
      apiKey: 'YOUR_API_KEY_HERE' // supply your API key here 
    });

    // Provision Chrome browser with a URL
    // This also starts dashcam recording automatically
    await testdriver.provision.chrome({ url: "https://duckduckgo.com" });

    // Find and interact with elements using natural language
    const searchBox = await testdriver.find("DuckDuckGo search input field");
    await searchBox.click();

    // Type into the focused element
    await testdriver.type("testdriver.ai");

    // Press Enter to search
    await testdriver.pressKeys(["enter"]);

    // Assert something is visible on the page
    const result = await testdriver.assert("search results are displayed");
    expect(result).toBeTruthy();
  });
});

Run Your Test

TestDriver uses Vitest as the test runner. To run your test, use:

vitest run

This will spawn a sandbox, launch Chrome, and run the example test!

Overview

Creating Tests

Running Tests

Scaling

Actions

SDK

Get an API Key