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.

VS Code Extension
CLI Guided Setup
Manual Setup

Requires GitHub Copilot

Install the TestDriver Extension

Click the link below to install the TestDriver extension for VS Code:

Install TestDriver Extension

Get the TestDriver VS Code extension from the VS Code marketplace

Complete the Walkthrough

The TestDriver VS Code extension supercharges your workflow by setting up everything you need automatically:

Installs the TestDriver MCP Server

The extension installs the TestDriver MCP server into your editor, enabling AI agents like GitHub Copilot to interact with TestDriver tools directly. It configures the server with TD_PREVIEW=ide so live test previews open inside VS Code instead of an external browser.

Adds Agent Instructions

Copies a testdriver.agent.md file into .github/agents/ in your workspace. This file teaches GitHub Copilot how to use TestDriver — including how to provision sandboxes, find elements, make assertions, and write complete tests. It also sets up copilot-instructions.md if one doesn’t already exist.

Installs Skills

Copies a library of TestDriver skills into .github/skills/. These are structured knowledge files that give AI coding agents detailed, context-aware documentation on every TestDriver feature — from clicking and typing to CI/CD setup, caching, secrets management, and more.

Live Preview in VS Code

When a test runs, the extension opens a live preview panel inside VS Code showing a real-time view of the sandbox VM. You can watch your test execute step by step without leaving the editor. The panel title updates with the test status — [Running], [Passed], [Failed], or [Stopped].

Suggests Vitest

The extension bundles the Vitest Explorer extension so your tests are automatically discovered and runnable from the VS Code test panel. During project setup, it scaffolds a vitest.config.js, an example test file, and installs vitest as a dev dependency.

MCP Apps (Rich Visual Feedback)

Every TestDriver action (find, click, type, scroll, assert) returns rich visual UI to the AI agent’s chat. This includes annotated screenshots with element highlights, click markers, scroll indicators, confidence scores, and action timing — so the AI can see what happened after each step.

Chat with the TestDriver agent.

The TestDriver agent has been trained on how to write tests using TestDriver. You can ask it to write tests for you, or to help you debug your existing tests.Note that TestDriver setup will add the TestDriver agent to .github/agents/copilot-instructions.md. However, if that file exists already, it will be written to .github/agents/testdriver.agent.md instead and you will need to select it as the active agent manually.

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, and setting up your API key.

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,
    disableConsoleIntercept: true,
    maxConcurrency: 1, // this should match your plan's concurrency limit 
    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

Guides

AI

Queries

Mouse

Keyboard

System

Utilities

SDK

Infrastructure

Install TestDriver Extension

Get an API Key