Configure Your Agent

Use the TestDriver CLI to scaffold a project, connect your AI client, and run the example test. testdriverai init installs three things so you can write, run, and debug real end-to-end tests from chat:

The agent: an expert test-writer. It controls a live sandbox, writes code after each step, and re-runs the test until it passes.
Skills: small instruction files that teach the agent the correct syntax for each TestDriver capability (find, click, type, assert, and more).
The MCP server: exposes TestDriver’s computer-use tools through the Model Context Protocol so any MCP client can call them.

Prerequisites

Node.js 20.19 or later
A TestDriver account. Create one for free. You get 60 device minutes, no credit card required.

Scaffold a project

Make a new folder (or open an existing project) and run init:

mkdir my-tests && cd my-tests
npx testdriverai init

init asks two questions:

How to authenticate. Choose Login with browser to sign in and save your key automatically, or paste an API key from console.testdriver.ai/settings. Either way, it is saved to .env as TD_API_KEY.
Which AI clients to set up. Pick VS Code, Cursor, Claude Code, and others, or press Enter to skip. init detects the clients already present in your project and pre-selects them. You can run init again later to add more; it merges the TestDriver entry into your existing config and does not overwrite your other servers.

It then installs vitest and testdriverai and creates these files:

File	Purpose
`tests/example.test.js`	Example test: log in to a demo store and add an item to the cart
`tests/login.js`	Reusable login snippet imported by the example test
`vitest.config.js`	Vitest config with the TestDriver reporter and long timeouts
`.env`	Your `TD_API_KEY` (git-ignored)
`.github/workflows/testdriver.yml`	GitHub Actions workflow that runs your tests on every PR
`.github/agents/`, `.github/skills/`	Agent and skills for the AI clients you selected

Skip the prompts in CI or scripts with flags:

npx testdriverai init --client claude-code               # one client
npx testdriverai init --client claude-code,cursor,vscode # several
npx testdriverai init --client all                       # everything
npx testdriverai init --no-sample-test                   # no example files

Connect your AI client

init writes the agent, skills, and MCP server config in the format and location each client expects. Here is what it installs and where.

The agent

The TestDriver agent runs inside your AI client (Claude Code, Cursor, VS Code, and others). Unlike a chat assistant that only suggests code, it works iteratively on a live sandbox: it starts a session, performs each action, writes the code to your test file, confirms the result with a screenshot, and re-runs the test until it passes.

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`

Skills

Skills are small instruction files, one per TestDriver capability, in the Anthropic SKILL.md format. There are over 100, generated from this documentation, covering every action and concept: find, click, type, assert, check, scroll, press-keys, provision, caching, secrets, CI/CD, and more.

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

MCP server

The TestDriver MCP server exposes the computer-use tools (session_start, find, click, type, assert, check, screenshot, and more). It runs as a local stdio process and authenticates with your TD_API_KEY:

npx -p testdriverai testdriverai-mcp

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	—

Configure the MCP server by hand

Each client uses a different top-level key for MCP servers. The most common manual-config mistake is using mcpServers for VS Code (which needs servers), Codex (TOML [mcp_servers]), or Zed (context_servers).

Add this 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" }
    }
  }
}

Start Claude Desktop again after you save.

Add this 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 this 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/settings",
      "password": true
    }
  ]
}

Windsurf reads the MCP config globally. Add this 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 this 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 this 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, v0)

These run in the browser, so they cannot start the MCP server as a local process. Configure them through each product’s UI.Lovable

Connect your GitHub repo, then run npx testdriverai init --client lovable. This writes AGENTS.md and the skills into the repo so the Lovable agent can use them.
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 UI-only 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).

Verify 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 connected, the agent starts a sandbox session and you see screenshots as it works. It writes the steps into a test file in tests/ and runs it for you. If the tools do not appear, confirm that TD_API_KEY is set and restart the client.

Run the example test

TestDriver tests are plain Vitest tests. Run them with:

npm test

Here is what happens:

A cloud sandbox starts and opens Chrome at the demo app.
A live preview of the sandbox opens in your browser so you can watch.
The test finds the login form, types credentials, adds an item to the cart, and asserts the cart has an item.
The sandbox is torn down and results are uploaded.

At the end of the output, look for the run link:

TESTDRIVER_RUN_URL=https://console.testdriver.ai/runs/...

Open it to see the video recording, screenshots, and logs for each step.

The first run takes a minute or two while the sandbox boots. Later runs are faster because element locations are cached.

Read the example test

Open tests/example.test.js. Every TestDriver test follows the same shape: create an instance, provision an app, then find, act, and assert in natural language.

tests/example.test.js

import { test, expect } from 'vitest';
import { TestDriver } from 'testdriverai/vitest/hooks';
import { login } from './login.js';

test('should login and add item to cart', async (context) => {
  // Connects to a sandbox and records the session
  const testdriver = TestDriver(context);

  // Launch Chrome at the app under test
  await testdriver.provision.chrome({
    url: 'http://testdriver-sandbox.vercel.app/login',
  });

  // Reusable step from tests/login.js
  await login(testdriver);

  // Describe elements in plain English
  const addToCart = await testdriver.find('add to cart button under TestDriver Hat');
  await addToCart.click();

  const cart = await testdriver.find('cart button in the top right corner');
  await cart.click();

  // Assert with natural language, then use Vitest's expect
  const result = await testdriver.assert('There is an item in the cart');
  expect(result).toBeTruthy();
});

The pieces you will use most:

provision.chrome() starts a browser (or a desktop app) in the sandbox
find() locates an element by description; then call .click(), .hover(), and so on
type() and pressKeys() send keyboard input
assert() asks a yes/no question about the screen

Write your own test

The fastest way is to ask the agent:

@testdriver write a test that searches duckduckgo.com for "testdriver.ai" and verifies results appear

Or write it by hand. Create tests/search.test.js and point it at a site you want to test:

tests/search.test.js

import { test, expect } from 'vitest';
import { TestDriver } from 'testdriverai/vitest/hooks';

test('search shows results', async (context) => {
  const testdriver = TestDriver(context);

  await testdriver.provision.chrome({ url: 'https://duckduckgo.com' });

  const searchBox = await testdriver.find('search input field');
  await searchBox.click();
  await testdriver.type('testdriver.ai');
  await testdriver.pressKeys(['enter']);

  const result = await testdriver.assert('search results are displayed');
  expect(result).toBeTruthy();
});

Run just that file:

npx vitest run tests/search.test.js

Not sure how to describe an element? Say what a person sees: "blue Sign In button in the header" works better than "button". See Locating elements.

Run in CI

init already created .github/workflows/testdriver.yml. Push your project to GitHub, then add TD_API_KEY as a repository secret (Settings → Secrets and variables → Actions). Your tests now run on every pull request.See CI/CD for other providers and for keyless auth with the TestDriver GitHub App.

Troubleshooting

TD_API_KEY is not configured

The SDK reads TD_API_KEY from .env in the folder where you run vitest. Make sure the file exists and has this line:

.env

TD_API_KEY=your_api_key

You can also export it in your shell: export TD_API_KEY=your_api_key.

The agent or MCP tools do not appear in my client

Confirm TD_API_KEY is set, check that the MCP config uses the correct top-level key for your client (see the table above), and restart the client. Running npx testdriverai init --client <name> again rewrites the config in the correct format.

No test files found

Vitest only picks up files that match *.test.js, *.test.mjs, or *.spec.*. Check the file name and that the file is inside your project folder.

Test times out

Sandbox provisioning and teardown take time. init sets testTimeout and hookTimeout to 5 minutes in vitest.config.js. If you wrote the config by hand, add both values.

Next steps

Generating tests

Prompting patterns that get the best tests out of the agent.

Walkthrough

Provision apps, locate elements, perform actions, and make assertions.

Reusable code

Share login flows and other steps across tests.

Secrets

Keep passwords and tokens out of logs and recordings.

Overview

Using TestDriver

Building & Maintaining Tests

Advanced Topics

Configure Your Agent

The agent

Skills

MCP server

Verify the install

Troubleshooting

Next steps

Generating tests

Walkthrough

Reusable code

Secrets

​The agent

​Skills

​MCP server

​Verify the install

​Troubleshooting

​Next steps

Generating tests

Walkthrough

Reusable code

Secrets

The agent

Skills

MCP server

Verify the install

Troubleshooting

Next steps