> ## Documentation Index
> Fetch the complete documentation index at: https://docs.testdriver.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Manual

> Add TestDriver to an existing project by hand.

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 theme={null}
    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 theme={null}
    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 theme={null}
    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 theme={null}
    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 theme={null}
    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 theme={null}
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>