Testdriver Quickstart Manual

---
name: testdriver:quickstart-manual
description: Add TestDriver to an existing project by hand.
---
<!-- Generated from quickstart-manual.mdx. DO NOT EDIT. -->

Add TestDriver to an existing project without the `init` scaffold. This is useful when you already have a Vitest setup or want full control over each file.

<Tip>
If you are starting from scratch, the [CLI quickstart](/quickstart-cli) does all of this for you with one command.
</Tip>

<Steps>
  <Step title="Get an API key">

    <Card
      title="Get an API Key"
      icon="user-plus"
      href="https://console.testdriver.ai/settings"
      arrow
      horizontal
    >
      Start with 60 free device minutes, no credit card required.
    </Card>

    Save the key in a `.env` file at your project root. The SDK loads it automatically:

    ```bash .env
    TD_API_KEY=your_api_key
    ```

    Add `.env` to `.gitignore` so the key is not committed.

  </Step>
  <Step title="Install dependencies">

    Install Vitest and TestDriver as dev dependencies:

    ```bash
    npm install --save-dev vitest testdriverai
    ```

    <Note>
    TestDriver requires Node.js 20.19 or later and only runs on [Vitest](https://vitest.dev). Jest, Mocha, and other runners are not supported.
    </Note>

  </Step>
  <Step title="Configure Vitest">

    Create `vitest.config.js` at your project root (or add these settings to an existing one):

    ```js vitest.config.js
    import { defineConfig } from 'vitest/config';
    import TestDriver from 'testdriverai/vitest';

    export default defineConfig({
      test: {
        // Sandboxes take time to boot and tear down. Both values are required.
        testTimeout: 300000,
        hookTimeout: 300000,
        reporters: ['default', TestDriver()],
        setupFiles: ['testdriverai/vitest/setup'],
      },
    });
    ```

    - `TestDriver()` reporter uploads results, recordings, and screenshots to the console.
    - `setupFiles` registers the hooks that connect each test to a sandbox and clean it up.
    - Without `hookTimeout`, cleanup fails at Vitest's default 10-second limit.

  </Step>
  <Step title="Write a test">

    Create `tests/search.test.js`:

    ```js tests/search.test.js
    import { test, expect } from 'vitest';
    import { TestDriver } from 'testdriverai/vitest/hooks';

    test('search shows results', async (context) => {
      // Connects to a sandbox and records the session
      const testdriver = TestDriver(context);

      // Launch Chrome at a URL
      await testdriver.provision.chrome({ url: 'https://duckduckgo.com' });

      // Locate elements by describing them
      const searchBox = await testdriver.find('search input field');
      await searchBox.click();

      // Type into the focused element and submit
      await testdriver.type('testdriver.ai');
      await testdriver.pressKeys(['enter']);

      // Ask a yes/no question about the screen
      const result = await testdriver.assert('search results are displayed');
      expect(result).toBeTruthy();
    });
    ```

    If your project does not have `"type": "module"` in `package.json`, name the file `search.test.mjs` instead.

  </Step>
  <Step title="Run the test">

    ```bash
    npx vitest run
    ```

    A sandbox starts, Chrome opens, and a live preview appears in your browser. When the run finishes, open the `TESTDRIVER_RUN_URL` printed at the end of the output to see the recording and step-by-step screenshots.

  </Step>
</Steps>

## Optional: AI client setup

If you want to write tests with an AI assistant, connect the TestDriver agent and MCP server. You can do this without re-scaffolding the project:

```bash
npx testdriverai init --client cursor,claude-code,vscode --no-sample-test
```

See [Configure Your Agent](/quickstart-cli#connect-your-ai-client) for the manual configuration of each client.

## Next steps

<CardGroup cols={2}>
  <Card title="Walkthrough" icon="map" href="/provision" arrow horizontal>
    Provision apps, locate elements, perform actions, and make assertions.
  </Card>
  <Card title="CI/CD" icon="github" href="/ci-cd" arrow horizontal>
    Run tests on every pull request with GitHub Actions or another provider.
  </Card>
</CardGroup>