testdriver:quickstart

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

TestDriver makes it easy to write automated computer-use tests for 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 testing for any GitHub repository. Mention `@testdriverai` anywhere in your repo and it writes UI tests and catches 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 and install TestDriver on the repositories you want to test.
      </Step>

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

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

        TestDriver spawns a sandbox, writes the test, and posts results right in the conversation.
      </Step>

      <Step title="Catch Regressions Automatically">
        Once your tests are committed, TestDriver runs them on every pull request and flags regressions before they merge.
      </Step>
    </Steps>

    Want to use TestDriver from GitHub Copilot or the GitHub Mobile app instead? See the full GitHub guide:

    <Card
      title="GitHub Integration Guide"
      icon="arrow-right"
      href="/v7/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">

    Get started quickly with the TestDriver CLI.

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

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

        ```bash
        npx testdriverai init
        ```

        This will walk you through creating a new project folder, installing dependencies, setting up your API key, and configuring MCP for your preferred AI assistant (VS Code, Cursor, Claude Desktop, etc.).

      </Step>
      
      <Step title="Run Your Test">

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

        This will spawn a sandbox, launch Chrome, and run the example test!

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

    Plug TestDriver into your AI client so you can write, run, and debug real end-to-end tests right from chat. There are three pieces, and `testdriverai init` installs all of them for you:

    - **The agent** — an expert test-creator that drives a live sandbox, writes code after each step, and reruns the test until it passes.
    - **Skills** — small instruction files that teach the agent the exact syntax for each TestDriver capability (`find`, `click`, `type`, `assert`, …).
    - **The MCP server** — exposes TestDriver's computer-use tools over the [Model Context Protocol](https://modelcontextprotocol.io) so any MCP-capable client can use them.

    ### Quick install (recommended)

    `testdriverai init` wires up the agent, skills, and MCP server for you, writing each client's config in the exact format and location it expects:

    ```bash
    # 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` detects clients already present in your project and pre-selects them in the picker. Re-running `init` is safe — it merges the TestDriver entry into existing config without overwriting your other servers.
    </Info>

    You'll 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`.

    ### The agent

    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.

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

    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.

    ### Skills

    **Skills** are small, focused instruction files — one per TestDriver capability — that teach your AI client exactly how to use each part of the TestDriver SDK and MCP tools. They follow the [Anthropic `SKILL.md` format](https://code.claude.com/docs/en/skills): a folder per skill, each containing a `SKILL.md`