Skip to main content
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.
If you are starting from scratch, the CLI quickstart does all of this for you with one command.
1

Get an API key

Get an API Key

Start with 60 free device minutes, no credit card required.
Save the key in a .env file at your project root. The SDK loads it automatically:
.env
Add .env to .gitignore so the key is not committed.
2

Install dependencies

Install Vitest and TestDriver as dev dependencies:
TestDriver requires Node.js 20.19 or later and only runs on Vitest. Jest, Mocha, and other runners are not supported.
3

Configure Vitest

Create vitest.config.js at your project root (or add these settings to an existing one):
vitest.config.js
  • 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.
4

Write a test

Create tests/search.test.js:
tests/search.test.js
If your project does not have "type": "module" in package.json, name the file search.test.mjs instead.
5

Run the test

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:
See Configure Your Agent for the manual configuration of each client.

Next steps

Walkthrough

Provision apps, locate elements, perform actions, and make assertions.

CI/CD

Run tests on every pull request with GitHub Actions or another provider.