Skip to main content

​
Overview

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.

​
What it does

  • Builds tests from scratch using TestDriver skills and best practices.
  • Drives a live sandbox via MCP tools (session_start, find, click, type, assert, check, …), getting a screenshot and generated code after every action.
  • Writes code immediately to the test file after each successful step — never all at once at the end.
  • Verifies visually with check to confirm each action did what was intended.
  • Runs the test itself with vitest run and iterates until it passes reliably.
  • Shares the run report — after each run it surfaces the TESTDRIVER_RUN_URL so you can watch the recording.

​
Installation

The agent is installed automatically by testdriverai init, alongside the skills and the MCP server: 
npx testdriverai init
During init you’ll be asked which AI client(s) to install into. The agent is written to the location each client expects:
ClientAgent 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
CodexAGENTS.md
Zed.rules
To install for a specific client without the interactive picker: 
npx testdriverai init --client claude-code
# or several at once
npx testdriverai init --client claude-code,cursor,vscode
# or everything
npx testdriverai init --client all
See the MCP Server page for the full client matrix, including web-based clients (Lovable, Replit, v0) that require a few manual steps.

​
Prerequisites

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

​
Using the agent

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 — the building blocks the agent composes tests from
  • MCP Server — the tools the agent uses to drive your app
  • Generating tests — how test generation works end-to-end