---
title: "Installation"
description: "Install TestDriver and set up your first test in 2 minutes"
icon: "download"
---
Get started with TestDriver in just a few steps. This guide will have you running your first AI-powered test in under 2 minutes.
**Fastest Way to Get Started:** Use `testdriverai init` to scaffold a complete project automatically:
```bash
npm install -g testdriverai
testdriverai init
```
This creates everything you need: package.json, test files, Vitest config, GitHub Actions workflow, and prompts for your API key. Then just run `vitest run`!
For manual setup, continue with the steps below.
## Prerequisites
Node.js 18 or higher
```bash
node --version
# v18.0.0 or higher
```
npm, yarn, or pnpm
```bash
npm --version
# or
yarn --version
# or
pnpm --version
```
## Step 1: Install TestDriver
Install TestDriver and Vitest test runner:
```bash npm
npm install --save-dev testdriverai vitest
```
```bash yarn
yarn add --dev testdriverai vitest
```
```bash pnpm
pnpm add -D testdriverai vitest
```
TestDriver works with any test framework (Vitest, Jest, Mocha), but we recommend Vitest for the best experience.
## Step 2: Get Your API Key
Visit [console.testdriver.ai](https://console.testdriver.ai) and create a free account.
Navigate to Settings ā API Keys and generate a new key.
The key will look like: `tdai-1234567890abcdef1234567890abcdef`
Create a `.env` file in your project root:
```bash .env
TD_API_KEY=tdai-your-api-key-here
```
Add `.env` to your `.gitignore` to avoid committing secrets!
## Step 3: Create Your First Test
Create a test file `test.test.js`:
```javascript test.test.js
import { test } from 'vitest';
import { chrome } from 'testdriverai/presets';
test('my first test', async (context) => {
const { testdriver } = await chrome(context, {
url: 'https://example.com'
// apiKey automatically read from process.env.TD_API_KEY
});
await testdriver.find('More information link').click();
await testdriver.assert('IANA page is visible');
});
```
That's it! TestDriver automatically handles authentication, browser launch, navigation, video recording, and cleanup.
## Step 4: Run Your Test
Run your test with Vitest:
```bash
vitest run
```
You should see output like:
```
ā test.test.js (1)
ā my first test (12.3s)
Test Files 1 passed (1)
Tests 1 passed (1)
Duration 12.45s
š¹ Replay: https://console.testdriver.ai/dashcam/abc123
```
Click the Dashcam replay URL to watch a video of your test execution!
## Optional: Configure Vitest
For a better experience, create a `vitest.config.mjs`:
```javascript vitest.config.mjs
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
testTimeout: 120000, // 2 minutes per test (TestDriver tests can take longer)
hookTimeout: 120000, // 2 minutes for setup/teardown
},
});
```
## Installation Options
### TypeScript Setup
TestDriver includes TypeScript definitions out of the box:
```typescript test.test.ts
import { test } from 'vitest';
import { chrome } from 'testdriverai/presets';
test('typed test', async (context) => {
const { testdriver } = await chrome(context, {
url: 'https://example.com'
});
const element = await testdriver.find('button');
// element has full type information
console.log(element.coordinates.x);
});
```
No additional setup needed!
### Global Installation (Optional)
Install TestDriver CLI globally for project scaffolding and sandbox management:
```bash
npm install -g testdriverai
```
This gives you access to commands like:
```bash
# Initialize a new project (recommended!)
testdriverai init
# Spawn a sandbox
testdriverai sandbox spawn
# List active sandboxes
testdriverai sandbox list
# Stop a sandbox
testdriverai sandbox stop i-abc123
```
The `testdriverai init` command is the fastest way to start a new project. It creates:
- package.json with test scripts
- Vitest configuration with TestDriver plugin
- Example test file using the chrome preset
- GitHub Actions workflow for CI/CD
- .gitignore to protect secrets
- Installs all dependencies
- Prompts for your API key and saves to .env
[Learn more about sandbox management](/v7/guides/sandbox-management)
### Monorepo Setup
For monorepos, install TestDriver in the root and reference it from test packages:
```json package.json (root)
{
"workspaces": ["packages/*"],
"devDependencies": {
"testdriverai": "^7.0.0",
"vitest": "^1.0.0"
}
}
```
```json packages/app/package.json
{
"scripts": {
"test": "vitest run"
}
}
```
## Alternative Test Frameworks
While we recommend Vitest, TestDriver works with any test framework:
```javascript
import { test } from 'vitest';
import { chrome } from 'testdriverai/presets';
test('my test', async (context) => {
const { testdriver } = await chrome(context, { url });
// Test code
});
```
```javascript
import { chrome } from 'testdriverai/presets';
test('my test', async () => {
const { testdriver } = await chrome({ url });
// Test code
});
```
```javascript
import { chrome } from 'testdriverai/presets';
describe('My Suite', () => {
it('should work', async function() {
const { testdriver } = await chrome(this, { url });
// Test code
});
});
```
```javascript
import { TestDriver } from 'testdriverai';
async function runTest() {
const testdriver = new TestDriver({
apiKey: process.env.TD_API_KEY
});
await testdriver.connect();
// Test code
await testdriver.disconnect();
}
runTest();
```
## Verify Installation
Run this quick verification to ensure everything is set up correctly:
```javascript verify.test.js
import { test } from 'vitest';
import { chrome } from 'testdriverai/presets';
test('verify installation', async (context) => {
console.log('ā TestDriver SDK imported');
const { testdriver, dashcam } = await chrome(context, {
url: 'https://example.com'
});
console.log('ā Connected to TestDriver sandbox');
console.log('ā Chrome browser launched');
const element = await testdriver.find('More information link');
console.log('ā AI vision working');
console.log('ā Element found:', element.text);
await element.click();
console.log('ā Click action successful');
await testdriver.assert('IANA page is visible');
console.log('ā AI assertion passed');
console.log('ā Dashcam recording:', dashcam.url);
console.log('\nā
Installation verified successfully!');
});
```
Run it:
```bash
vitest run verify.test.js
```
## Troubleshooting
**Error:** `TestDriver API key not found`
**Solutions:**
1. Check `.env` file exists in project root
2. Verify key format: `TD_API_KEY=tdai-...`
3. Restart your terminal/IDE to reload environment
4. Or pass API key directly:
```javascript
const { testdriver } = await chrome(context, {
url: 'https://example.com',
apiKey: 'tdai-your-key-here'
});
```
**Error:** `Cannot find module 'testdriverai'`
**Solutions:**
1. Ensure you're in the correct directory
2. Run `npm install` again
3. Check `package.json` includes testdriverai
4. Delete `node_modules` and reinstall:
```bash
rm -rf node_modules package-lock.json
npm install
```
**Error:** `Test timed out after 5000ms`
**Solution:** Increase timeout in vitest config:
```javascript vitest.config.mjs
export default defineConfig({
test: {
testTimeout: 120000, // 2 minutes
},
});
```
TestDriver tests can take longer than unit tests due to AI analysis and browser automation.
**Error:** `Cannot find type definitions`
**Solution:** TestDriver includes types by default, but ensure your `tsconfig.json` is correct:
```json tsconfig.json
{
"compilerOptions": {
"module": "ESNext",
"moduleResolution": "node",
"esModuleInterop": true
}
}
```
**Error:** `Failed to connect to TestDriver API`
**Solution:**
1. Check your internet connection
2. Verify firewall allows outbound HTTPS
3. If behind corporate proxy, configure:
```bash .env
HTTP_PROXY=http://proxy.company.com:8080
HTTPS_PROXY=http://proxy.company.com:8080
```
For on-premise deployment, see [self-hosting guide](/v7/guides/self-hosting).