---
title: "Agent"
sidebarTitle: "Agent"
description: "The TestDriver test-creator agent that writes and debugs end-to-end tests for you"
icon: "robot"
---

## 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](/v7/ai/mcp).

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](/v7/ai/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](/v7/ai/skills) and the [MCP server](/v7/ai/mcp):

```bash
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:

| 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` |

To install for a specific client without the interactive picker:

```bash
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](/v7/ai/mcp) 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](https://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:

```text
@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.

## Related

- [Skills](/v7/ai/skills) — the building blocks the agent composes tests from
- [MCP Server](/v7/ai/mcp) — the tools the agent uses to drive your app
- [Generating tests](/v7/generating-tests) — how test generation works end-to-end
