Run tests

Run tests from the terminal or VS Code, in parallel, and watch them live.

TestDriver tests are ordinary Vitest files. You run them with Vitest, on your machine and in CI.

Each test:

• Starts its own cloud sandbox.
• Runs its steps.
• Prints a link to a full report with a recording of the run.

Before you begin

• A project with TestDriver installed, with your API key in .env as TD_API_KEY. See Set up a project.
• At least one test, which you can generate with AI or write by hand.

Run tests from the terminal

Run every test in the project:

npx vitest run

Vitest finds files whose names end in .test or .spec plus a JavaScript or TypeScript extension, such as tests/login.test.mjs.

To run part of your suite, pass files, folders, or a name filter:

# One file
npx vitest run tests/login.test.mjs

# Every test in a folder
npx vitest run tests/checkout/

# Only tests whose name matches
npx vitest run -t "login"

Use npx vitest (without run) for watch mode. It reruns tests when you save a file.

Run tests from VS Code

Install the Vitest extension to run tests from the Testing view. Click the run button next to a file or test. The result appears inline next to the code.

To watch the sandbox in a panel beside your code, install the TestDriver extension and use the ide preview mode below.

Watch a test run

TestDriver shows each run live. Choose where with the preview option or the TD_PREVIEW environment variable:

Mode	Where the run appears
"browser" (default)	A live view in your web browser
"ide"	A panel in VS Code or Cursor (requires the TestDriver extension)
"none"	Nowhere, for CI and other headless runs

const testdriver = TestDriver(context, { preview: 'ide' });

Open the test report

When a test finishes, TestDriver prints a link to its report:

TESTDRIVER_RUN_URL=https://console.testdriver.ai/runs/abc123

The report includes the run’s recording, screenshots, and logs. Every past run is in the TestDriver console.

Run tests in parallel

Vitest runs test files in parallel, and each running test gets its own sandbox. Your plan sets how many sandboxes can run at once.

At the limit, a new test waits for a free slot instead of failing. By default, the SDK retries every 10 seconds for up to 60 seconds.

Set TD_CONCURRENCY_MAX_WAIT (in seconds) to wait longer, or to 0 to fail immediately.

To cap how many test files run at once on your machine, limit Vitest’s workers:

npx vitest run --maxWorkers=5

For CI setups and parallel job matrices, see Run tests in CI/CD.

Reuse a sandbox while you iterate

Each test normally starts a fresh sandbox, which takes time to boot, especially on Windows.

While you work on a long flow, keep the sandbox running between runs and reconnect to it. Then you only rerun the steps you’re changing.

1. Run the steps that already work with a longer keepAlive. It keeps the sandbox running for that many milliseconds after the test ends (60 seconds by default, up to 30 minutes):

   tests/setup-cart.test.mjs

   const testdriver = TestDriver(context, {
     keepAlive: 10 * 60 * 1000, // 10 minutes
   });
   
   await testdriver.provision.chrome({ url: 'https://testdriver-sandbox.vercel.app/login' });
   // ...steps that log in and fill the cart
   

2. In the file you’re working on, set reconnect: true. TestDriver reattaches to the last sandbox it used, recorded in .testdriver/last-sandbox. It skips provision calls because the app is already open:

   tests/checkout.test.mjs

   const testdriver = TestDriver(context, {
     reconnect: true,
     keepAlive: 10 * 60 * 1000,
   });
   
   // No provision call: Chrome is still open from the previous run
   const checkoutButton = await testdriver.find('Checkout button');
   await checkoutButton.click();
   

Run the second file within the first file’s keepAlive window. Reconnecting fails if the sandbox has already shut down.

A kept-alive sandbox uses your plan’s testing minutes until it shuts down. Use a keepAlive no longer than you need.

To connect to a specific sandbox instead, or for more sandbox options, see Customize devices.

Fix a failing test

When the app changes and a test no longer matches it, ask the TestDriver agent to update the test. It reruns the flow in a sandbox and sees the current screen:

The login test is failing because the form layout changed. Update tests/login.test.mjs to match the new design.

For small changes, such as an updated find() description or assertion, edit the test file directly.

To dig into what went wrong in a run, see Debug with screenshots.

Troubleshooting

Tests fail with a Vitest timeout

Tests that drive a real machine take longer than Vitest’s 5-second default. Set testTimeout and hookTimeout in vitest.config.mjs.

npx testdriverai init sets both to 5 minutes:

vitest.config.mjs

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

export default defineConfig({
  test: {
    testTimeout: 300000,
    hookTimeout: 300000,
    reporters: ['default', TestDriver()],
    setupFiles: ['testdriverai/vitest/setup'],
  },
});

TestDriver can't find my API key

The SDK reads TD_API_KEY from the environment. It loads .env in your project root automatically.

Check that .env contains TD_API_KEY=..., or set the variable for one run:

TD_API_KEY=your_api_key npx vitest run

Tests wait a long time before starting

You’re probably at your plan’s sandbox limit, and tests are waiting for a free slot.

Run fewer files at once with --maxWorkers, or check your plan in the TestDriver console.

Next steps

Make assertions

Write checks that catch the regressions you care about.

Debug with screenshots

See what the sandbox showed at each step of a run.

Run in CI/CD

Run your tests on every push and pull request.

Launch apps

Start Chrome, extensions, VS Code, or desktop apps in the sandbox.