/testdriver-quickstart

name: testdriver:quickstart
description: Run your first computer-use test in minutes.

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

TestDriver makes it easy to write automated computer-use tests. You can test web browsers, desktop apps, and more. Follow the directions below to run your first TestDriver test.

<Tip><a href="https://discord.com/invite/cWDFW8DzPm" target="_blank" rel="noreferrer">Join our Discord</a> if you have any questions or need help getting started!</Tip>

<Tabs> <Tab title="Add to GitHub" icon="github">

Drop-in UI tests for any GitHub repository. Mention `@testdriverai` in your repo. It writes UI tests and it finds regressions before they merge.

<Card title="Add to GitHub" icon="github" href="https://go.testdriver.ai/github" arrow horizontal > Install the TestDriver GitHub app and start testing in minutes — no setup required. </Card>

<Steps> <Step title="Install the GitHub App"> Click **Add to GitHub** above. Then install TestDriver on the repositories that you want to test. </Step>

<Step title="Mention @testdriverai"> Open a pull request or an issue. Mention `@testdriverai` to make it write and run UI tests:

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

TestDriver starts a sandbox, writes the test, and shows the results in the conversation. </Step>

<Step title="Catch Regressions Automatically"> After you commit your tests, TestDriver runs them on each pull request. It shows regressions before they merge. </Step> </Steps>

Do you want to use TestDriver from GitHub Copilot or the GitHub Mobile app? Read the full GitHub guide:

<Card title="GitHub Integration Guide" icon="arrow-right" href="/copilot/auto-healing#use-testdriver-in-github" arrow horizontal > Use TestDriver from GitHub web, Copilot chat, PR reviews, and mobile. </Card>

</Tab> <Tab title="CLI" icon="terminal">

Start quickly with the TestDriver CLI.

<Steps> <Step title="Install TestDriver">

Use `npx` to set up an example project quickly:

        npx testdriverai init

This helps you to make a new project folder, install dependencies, set up your API key, and configure MCP for your AI assistant (VS Code, Cursor, Claude Desktop, and others).

</Step>

<Step title="Run Your Test">

TestDriver uses Vitest as the test runner. To run your test, use:

        vitest run

This starts a sandbox, starts Chrome, and runs the example test.

</Step> </Steps> </Tab> <Tab title="AI Setup" icon="robot">

Connect TestDriver to your AI client. Then you can write, run, and debug real end-to-end tests from chat. There are three parts. `testdriverai init` installs all of them for you:

• **The agent**. This is an expert test-creator. It controls a live sandbox, writes code after each step, and runs the test again until the test passes.
• **Skills**. These are small instruction files. They teach the agent the correct syntax for each TestDriver capability (`find`, `click`, `type`, `assert`, and more).
• **The MCP server**. This gives the computer-use tools of TestDriver through the [Model Context Protocol](https://modelcontextprotocol.io). Then an MCP client can use them.

Quick install (recommended)

`testdriverai init` connects the agent, skills, and MCP server for you. It writes the config of each client in the correct format and location:

    # 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

<Info> `init` finds the clients that are in your project. It selects them in the picker. To run `init` again is safe. It merges the TestDriver entry into the config that exists. It does not write over your other servers. </Info>

You need a TestDriver API key. Create one at [console.testdriver.ai/settings](https://console.testdriver.ai/settings). Then `init` saves it to `.env` as `TD_API_KEY`.

The agent

The **TestDriver agent** is an expert test-creator. It runs in your AI client (Claude Code, Cursor, VS Code, and others). It writes, runs, and debugs real end-to-end tests. It controls your app the same as a person. It uses AI vision to find elements, click, type, and assert, through the TestDriver MCP server.

Unlike a chat assistant only suggests code, the agent works **iteratively on a live sandbox**. It starts a session, does each action, writes the code to your test file, makes sure of the result with a screenshot, and runs the test again until the test passes.

In init, the tool asks which AI clients to install into. The agent is written to the location that 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` |

After you install it, start it from the chat of your client:

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

The agent starts a sandbox, does the steps live, writes them into a test file in `tests/`, and runs it for you.

Skills

**Skills** are small instruction files. There is one skill for each TestDriver capability. They teach your AI client how to use each part of the TestDriver SDK and the MCP tools. They obey the [Anthropic `SKILL.md` format](https://code.cl