/testdriver-quickstart-cli

name: testdriver:quickstart-cli
description: Scaffold a project, connect TestDriver to your AI client, and run your first test.

<!-- Generated from quickstart-cli.mdx. DO NOT EDIT. -->

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](https://modelcontextprotocol.io) so any MCP client can call them.

<Info> **Prerequisites**

• [Node.js](https://nodejs.org) 20.19 or later
• A TestDriver account. [Create one for free](https://console.testdriver.ai/settings). You get 60 device minutes, no credit card required.

</Info>

<Steps> <Step title="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:

1. **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](https://console.testdriver.ai/settings). Either way, it is saved to `.env` as `TD_API_KEY`. 2. **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 |

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

</Tip>

</Step>

<Step title="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](https://code.claude.com/docs/en/skills). 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 | — |

<Accordion title="Configure the MCP server by hand"> <Note> 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`). </Note>

<Tabs> <Tab title="Claude Code"> Add this to `.mcp.json` at your project root (or `~/.claude.json` for all projects):

          {
            "mcpServers": {
              "testdriver": {