Quick Start - TestDriver

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!

Add to GitHub
CLI
AI Setup
Manual

Drop-in UI testing for any GitHub repository. Mention @testdriverai anywhere in your repo and it writes UI tests and catches regressions before they merge.

Add to GitHub

Install the TestDriver GitHub app and start testing in minutes — no setup required.

Install the GitHub App

Click Add to GitHub above and install TestDriver on the repositories you want to test.

Mention @testdriverai

Open a pull request or issue and mention @testdriverai to have it write and run UI tests:

@testdriverai Write a test that verifies the homepage loads and the signup button works.

TestDriver spawns a sandbox, writes the test, and posts results right in the conversation.

Catch Regressions Automatically

Once your tests are committed, TestDriver runs them on every pull request and flags regressions before they merge.

Want to use TestDriver from GitHub Copilot or the GitHub Mobile app instead? See the full GitHub guide:

GitHub Integration Guide

Use TestDriver from GitHub web, Copilot chat, PR reviews, and mobile.

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!

Plug TestDriver into your AI client so you can write, run, and debug real end-to-end tests right from chat. There are three pieces, and testdriverai init installs all of them for you:

The agent — an expert test-creator that drives a live sandbox, writes code after each step, and reruns the test until it passes.
Skills — small instruction files that teach the agent the exact syntax for each TestDriver capability (find, click, type, assert, …).
The MCP server — exposes TestDriver’s computer-use tools over the Model Context Protocol so any MCP-capable client can use them.

Quick install (recommended)

testdriverai init wires up the agent, skills, and MCP server for you, writing each client’s config in the exact format and location it expects:

# interactive — pick your client(s)
npx testdriverai init

# one client
npx testdriverai init --client claude-code

# several
npx testdriverai init --client claude-code,cursor,vscode

# everything
npx testdriverai init --client all

init detects clients already present in your project and pre-selects them in the picker. Re-running init is safe — it merges the TestDriver entry into existing config without overwriting your other servers.

You’ll need a TestDriver API key. Create one at console.testdriver.ai/team and init will save it to .env as TD_API_KEY.

The agent

The TestDriver agent is an expert test-creator that runs inside your AI client (Claude Code, Cursor, VS Code, and others). It writes, runs, and debugs real end-to-end tests by driving your app the same way a person would — using AI vision to find elements, click, type, and assert — through the TestDriver MCP server.Unlike a chat assistant that only suggests code, the agent works iteratively against a live sandbox: it starts a session, performs each action, writes the generated code to your test file, verifies the result with a screenshot, and reruns the test until it passes.During init you’ll be asked which AI client(s) to install into. The agent is written to the location each client expects:

Client	Agent location
Claude Code	`.claude/agents/testdriver.md`
VS Code (Copilot)	`.github/agents/testdriver.agent.md`
Cursor	`.cursor/rules/testdriver.mdc`
Windsurf	`.windsurf/rules/testdriver.md`
Codex	`AGENTS.md`
Zed	`.rules`

Once installed, invoke it from your client’s chat:

@testdriver write a test that logs in and verifies the dashboard loads

The agent will spin up a sandbox, perform the steps live, write them into a test file under tests/, and run it for you.

Skills

Skills are small, focused instruction files — one per TestDriver capability — that teach your AI client exactly how to use each part of the TestDriver SDK and MCP tools. They follow the Anthropic SKILL.md format: a folder per skill, each containing a SKILL.md with YAML frontmatter and a markdown body.There are 106 skills, generated directly from the TestDriver documentation, covering every action and concept: find, click, type, assert, check, scroll, press-keys, provision, caching, secrets, CI/CD, and more. They’re written to the directory each client expects:

Client	Skills location
Claude Code	`.claude/skills/<name>/SKILL.md`
Zed	`.agents/skills/<name>/SKILL.md`
Codex	referenced from `AGENTS.md`
VS Code · Cursor · Windsurf	folded into the agent rules/instructions

Skills are generated, not hand-edited — each is built from a .mdx docs page and carries a DO NOT EDIT marker. To change a skill, edit the corresponding documentation page and run node docs/_scripts/generate-skills.js.

MCP server

The TestDriver MCP server exposes TestDriver’s computer-use tools — session_start, find, click, type, assert, check, screenshot, and more — over the Model Context Protocol. It runs as a local stdio process:

npx -p testdriverai testdriverai-mcp

and authenticates with your TD_API_KEY. testdriverai init configures it for you, but you can also wire it up by hand:

Client	Auto-install	MCP config file	Config key
Claude Code	✅	`.mcp.json`	`mcpServers`
Claude Desktop	✅	OS-specific	`mcpServers`
Cursor	✅	`.cursor/mcp.json`	`mcpServers`
VS Code (Copilot)	✅	`.vscode/mcp.json`	`servers`
Windsurf	✅	`~/.codeium/windsurf/mcp_config.json`	`mcpServers`
Codex	✅	`~/.codex/config.toml`	`[mcp_servers]`
Zed	✅	`.zed/settings.json`	`context_servers`
Lovable	⚙️ partial	GitHub `AGENTS.md` + UI	—
Replit	⚙️ partial	`replit.md` + UI	—
v0 (Vercel)	📝 manual	web UI only	—

Each client uses a different top-level key for MCP servers. The most common mistake when configuring by hand is using mcpServers for VS Code (it wants servers), Codex (TOML [mcp_servers]), or Zed (context_servers).

Add to .mcp.json at your project root (or ~/.claude.json for all projects):

{
  "mcpServers": {
    "testdriver": {
      "type": "stdio",
      "command": "npx",
      "args": ["-p", "testdriverai", "testdriverai-mcp"],
      "env": { "TD_API_KEY": "${TD_API_KEY}" }
    }
  }
}

Edit the Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "testdriver": {
      "command": "npx",
      "args": ["-p", "testdriverai", "testdriverai-mcp"],
      "env": { "TD_API_KEY": "your_api_key" }
    }
  }
}

Restart Claude Desktop after saving.

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "testdriver": {
      "type": "stdio",
      "command": "npx",
      "args": ["-p", "testdriverai", "testdriverai-mcp"],
      "env": { "TD_API_KEY": "${TD_API_KEY}" }
    }
  }
}

Add to .vscode/mcp.json. VS Code uses the servers key and an inputs prompt for secrets:

{
  "servers": {
    "testdriver": {
      "type": "stdio",
      "command": "npx",
      "args": ["-p", "testdriverai", "testdriverai-mcp"],
      "env": { "TD_API_KEY": "${input:testdriver-api-key}" }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "testdriver-api-key",
      "description": "TestDriver API Key From https://console.testdriver.ai/team",
      "password": true
    }
  ]
}

Windsurf reads MCP config globally. Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "testdriver": {
      "command": "npx",
      "args": ["-p", "testdriverai", "testdriverai-mcp"],
      "env": { "TD_API_KEY": "${TD_API_KEY}" }
    }
  }
}

Codex uses TOML. Add to ~/.codex/config.toml:

[mcp_servers.testdriver]
command = "npx"
args = ["-p", "testdriverai", "testdriverai-mcp"]
env = { TD_API_KEY = "${TD_API_KEY}" }

Zed calls them “context servers”. Add to .zed/settings.json (project) or ~/.config/zed/settings.json (global):

{
  "context_servers": {
    "testdriver": {
      "command": "npx",
      "args": ["-p", "testdriverai", "testdriverai-mcp"],
      "env": { "TD_API_KEY": "${TD_API_KEY}" }
    }
  }
}

Web-based clients — Lovable, Replit, and v0 run in the browser, so the MCP server can’t be launched as a local process. Configure them through each product’s UI:

Lovable

Connect your GitHub repo and run npx testdriverai init --client lovable — this writes AGENTS.md and the skills into the repo so Lovable’s agent picks them up.
In Lovable, open Settings → MCP and add the TestDriver server.

Replit

Run npx testdriverai init --client replit to write replit.md with the TestDriver agent guidance.
In Replit, open Tools → Integrations → MCP and add a custom MCP server.

v0 (Vercel)

v0 is fully UI-driven and does not read repo files.

Open v0.app/chat/settings/mcp-connections and add the TestDriver MCP connection.
Paste the agent guidance into Instructions (the + in the prompt bar).

Verifying the install

Open your client’s chat and ask the agent to write a test:

@testdriver write a test that opens the homepage and asserts the title

If the MCP server is wired up correctly, the agent will start a session and you’ll see screenshots come back as it works. If tools don’t appear, check that TD_API_KEY is set and restart the client.

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!

Add to GitHub

GitHub Integration Guide

​Quick install (recommended)

​The agent

​Skills

​MCP server

​Verifying the install

Get an API Key

Quick install (recommended)

The agent

Skills

MCP server

Verifying the install