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

# Running Tests

> Run TestDriver tests with Vitest test runner

Learn how to run TestDriver tests efficiently with Vitest's powerful test runner.

## Running Tests

TestDriver works with Vitest's powerful test runner.

<Info>
  Install Vitest globally for best results: `npm install vitest -g`
</Info>

### Run All Tests

```bash theme={null}
vitest run
```

Executes all test files in your project once and exits. Vitest automatically discovers files matching patterns like `*.test.js`, `*.test.mjs`, or `*.spec.js`.

### Run with Coverage

```bash theme={null}
vitest run --coverage
```

Generates a code coverage report showing which lines of your source code were executed during tests. Coverage helps identify untested code paths. Results are displayed in the terminal and saved to a `coverage/` directory.

<Info>
  Coverage requires the `@vitest/coverage-v8` package. Install it with `npm install -D @vitest/coverage-v8`.
</Info>

### Run Specific Tests

```bash theme={null}
vitest run login.test.js
```

Runs only the specified test file. Useful when debugging a single test or working on a specific feature.

```bash theme={null}
vitest run login.test.js checkout.test.js
```

Runs multiple specific test files. List as many files as needed, separated by spaces.

### Filter Tests by Name

```bash theme={null}
vitest run --grep "login"
```

The `--grep` flag filters tests by their name (the string passed to `it()` or `test()`). Only tests whose names match the pattern will run. Supports regex patterns for complex matching.

### Run Tests in a Folder

```bash theme={null}
vitest run tests/e2e/
```

Runs all test files within a specific directory. Great for organizing tests by type (unit, integration, e2e) and running them separately.

## Parallel Execution

TestDriver runs each test in its own cloud sandbox, enabling true parallel execution. Run your entire test suite in minutes instead of hours.

### Control Concurrency

```bash theme={null}
vitest run --maxConcurrency=5
```

The `--maxConcurrency` flag limits how many tests run simultaneously. This should match your TestDriver license slots to avoid failures from exhausted slots.

### Thread Configuration

```bash theme={null}
vitest run --pool=threads --minThreads=2 --maxThreads=8
```

Fine-tune thread allocation for optimal performance:

* `--pool=threads` — Uses worker threads for test isolation
* `--minThreads` — Minimum number of threads to keep alive (reduces startup overhead)
* `--maxThreads` — Maximum threads to spawn (limits resource usage)

### License Slots

Your TestDriver plan includes a set number of **license slots** that determine how many tests can run simultaneously. Each running test occupies one slot—when the test completes and the sandbox is destroyed, the slot is immediately available for the next test.

<Info>
  View your available slots at [console.testdriver.ai](https://console.testdriver.ai). Upgrade anytime to increase parallelization.
</Info>

### Configuring Concurrency

Set `maxConcurrency` in your Vitest config to match your license slot limit:

```javascript vitest.config.mjs theme={null}
import { defineConfig } from 'vitest/config';
import TestDriver from 'testdriverai/vitest';

export default defineConfig({
  test: {
    testTimeout: 900000,
    hookTimeout: 900000,
    maxConcurrency: 5, // Match your license slot limit
    reporters: ['default', TestDriver()],
    setupFiles: ['testdriverai/vitest/setup'],
  },
});
```

<Warning>
  Setting `maxConcurrency` higher than your license slots will cause tests to fail when slots are exhausted. Always match this value to your plan's limit.
</Warning>

### Why Parallelization Matters

| Test Suite            | Sequential (1 slot) | Parallel (5 slots) | Parallel (10 slots) |
| --------------------- | ------------------- | ------------------ | ------------------- |
| 10 tests @ 2min each  | 20 min              | 4 min              | 2 min               |
| 50 tests @ 2min each  | 100 min             | 20 min             | 10 min              |
| 100 tests @ 2min each | 200 min             | 40 min             | 20 min              |

<Tip>
  **Pro tip:** Upgrading your plan doesn't just increase speed—it enables faster CI/CD feedback loops, letting your team ship with confidence.
</Tip>

<Card title="View Plans & Pricing" icon="credit-card" href="/v7/hosted">
  Compare plans and find the right level of parallelization for your team.
</Card>

## Vitest UI

Use Vitest UI for interactive debugging:

```bash theme={null}
vitest --ui
```

The `--ui` flag launches a web-based interface for managing your test suite. Unlike `vitest run`, this starts in watch mode by default.

Open [http://localhost:51204](http://localhost:51204) to see:

* **Test file tree** — Browse and navigate your test structure
* **Test status and duration** — See pass/fail states and timing at a glance
* **Console output** — View logs and errors inline with each test
* **Re-run individual tests** — Click to re-execute specific tests without restarting
* **Filter and search** — Quickly find tests by name or status

<Tip>
  Combine with `--open` to automatically open the UI in your browser: `vitest --ui --open`
</Tip>

## Test Reports

After running tests, view detailed reports and video replays at [console.testdriver.ai](https://console.testdriver.ai).

Reports include:

* **Video replays** - Watch exactly what happened during each test
* **Screenshots** - See the state at each step
* **Timing breakdown** - Identify slow operations
* **Error details** - Debug failures with full context

```bash theme={null}
$ vitest run

 ✓ login.test.js (2) 18.4s
   ✓ user can login 12.3s
   ✓ shows error for invalid credentials 6.1s

📹 View reports at: https://console.testdriver.ai
```

<Tip>
  Bookmark your team's dashboard at [console.testdriver.ai](https://console.testdriver.ai) for quick access to test history and analytics.
</Tip>