testdriver:quickstart-manual

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.

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

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>

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.

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.

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

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:

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

See Configure Your Agent for the manual configuration of each client.

Next steps