/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:

    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:

    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):

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

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

    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:

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>