testdriverai 7.2.9 → 7.2.11

package/docs/v7/running-tests.mdx

@@ -0,0 +1,181 @@
+---
+title: "Running Tests"
+description: "Run TestDriver tests with Vitest test runner"
+icon: "play"
+---
+
+Learn how to run TestDriver tests efficiently with Vitest's powerful test runner.
+
+## Running Tests
+
+TestDriver works with Vitest's powerful test runner.
+
+### Run All Tests
+
+```bash
+npx 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
+npx 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
+npx vitest run login.test.js
+```
+
+Runs only the specified test file. Useful when debugging a single test or working on a specific feature.
+
+```bash
+npx 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
+npx 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
+npx 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
+npx 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
+npx 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
+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/cloud"
+>
+  Compare plans and find the right level of parallelization for your team.
+</Card>
+
+## Vitest UI
+
+Use Vitest UI for interactive debugging:
+
+```bash
+npx 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 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: `npx 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
+$ npx 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>

package/docs/v7/{api/scroll.mdx → scroll.mdx}

@@ -295,6 +295,6 @@ describe('Scrolling', () => {
 
 ## Related Methods
 
-- [`find()`](/v7/api/find) - Locate elements after scrolling
-- [`pressKeys()`](/v7/api/pressKeys) - Use Page Down/Up keys
-- [`wait()`](/v7/api/wait) - Wait after scrolling
+- [`find()`](/v7/find) - Locate elements after scrolling
+- [`pressKeys()`](/v7/press-keys) - Use Page Down/Up keys
+- [`wait()`](/v7/wait) - Wait after scrolling

package/docs/v7/secrets.mdx

@@ -0,0 +1,115 @@
+---
+title: "Using Secrets"
+description: "Securely manage passwords and sensitive data in your tests"
+icon: "key"
+---
+
+Protect sensitive information like passwords, API keys, and tokens in your TestDriver tests.
+
+## Typing Secrets Securely
+
+When typing sensitive information like passwords, use the `secret: true` option to prevent the value from being logged or stored:
+
+```javascript
+import { test } from 'vitest';
+import { chrome } from 'testdriverai/presets';
+
+test('login with secure password', async (context) => {
+  const { testdriver } = await chrome(context, { 
+    url: 'https://myapp.com/login' 
+  });
+
+  await testdriver.find('email input').click();
+  await testdriver.type(process.env.TD_USERNAME);
+  
+  await testdriver.find('password input').click();
+  // Password is masked in logs and recordings
+  await testdriver.type(process.env.TD_PASSWORD, { secret: true });
+  
+  await testdriver.find('login button').click();
+  await testdriver.assert('dashboard is visible');
+});
+```
+
+<Note>
+When `secret: true` is set, the typed text appears as `****` in all logs, recordings, and dashcam output.
+</Note>
+
+## Storing Secrets in GitHub
+
+Store sensitive credentials as GitHub repository secrets so they're never exposed in your code:
+
+<Steps>
+  <Step title="Navigate to Repository Settings">
+    Go to your GitHub repository → **Settings** → **Secrets and variables** → **Actions**
+  </Step>
+  <Step title="Add Repository Secrets">
+    Click **New repository secret** and add your secrets:
+    - `TD_API_KEY` - Your TestDriver API key
+    - `TD_USERNAME` - Test account username
+    - `TD_PASSWORD` - Test account password
+  </Step>
+  <Step title="Use in GitHub Actions">
+    Reference secrets in your workflow file:
+    ```yaml .github/workflows/test.yml
+    - name: Run TestDriver tests
+      env:
+        TD_API_KEY: ${{ secrets.TD_API_KEY }}
+        TD_USERNAME: ${{ secrets.TD_USERNAME }}
+        TD_PASSWORD: ${{ secrets.TD_PASSWORD }}
+      run: npx vitest run
+    ```
+  </Step>
+</Steps>
+
+## Local Development
+
+For local development, store secrets in a `.env` file:
+
+```bash .env
+TD_API_KEY=your_api_key_here
+TD_USERNAME=testuser@example.com
+TD_PASSWORD=your_secure_password
+```
+
+<Warning>
+Never commit `.env` files to version control. Add `.env` to your `.gitignore` file.
+</Warning>
+
+## Complete Example
+
+Here's a full login test with proper secrets handling:
+
+```javascript tests/login.test.js
+import { test, expect } from 'vitest';
+import { chrome } from 'testdriverai/presets';
+
+test('secure login flow', async (context) => {
+  const { testdriver } = await chrome(context, { 
+    url: process.env.TD_WEBSITE || 'https://staging.myapp.com'
+  });
+
+  // Enter username (not sensitive)
+  await testdriver.find('email input').click();
+  await testdriver.type(process.env.TD_USERNAME);
+  
+  // Enter password securely
+  await testdriver.find('password input').click();
+  await testdriver.type(process.env.TD_PASSWORD, { secret: true });
+  
+  // Submit login
+  await testdriver.find('login button').click();
+  
+  // Verify successful login
+  const loggedIn = await testdriver.assert('user is logged in');
+  expect(loggedIn).toBeTruthy();
+});
+```
+
+<Card title="Secrets Best Practices" icon="shield-check">
+  - **Always use `secret: true`** when typing passwords, tokens, or sensitive data
+  - **Use environment variables** to keep secrets out of code
+  - **Store secrets in your CI provider** (GitHub Actions, GitLab CI, etc.)
+  - **Never commit secrets** to version control
+  - **Rotate secrets regularly** to maintain security
+</Card>

package/docs/v7/self-hosted.mdx

@@ -0,0 +1,66 @@
+---
+title: "Self-Hosted"
+sidebarTitle: "Self-Hosted"
+description: "Unlimited test execution, complete privacy, and the ability to customize everything — all for a predictable flat license fee."
+icon: "server"
+---
+
+Self-hosted pricing is based on **parallel test capacity**: the number of tests you can run simultaneously on **your infrastructure**. 
+
+With self-hosting, you get:.
+
+- **Flat license fee** per parallel test slot
+- **Unlimited test execution** — run as many tests as you want
+- **No device-second metering** — predictable monthly costs
+- **Use your own AI keys** — control data usage with your own OpenAI, Anthropic, or other AI provider keys
+- **Custom hardware & software** — choose instance types, resolution, install specific software, and configure networking as needed
+- **Debug & Customize** — RDP into test machines, install custom software, modify the AMI, and debug issues directly. No black boxes.
+
+## Get Started
+
+Ready to self-host? Follow our comprehensive AWS setup guide:
+
+<Card
+  title="AWS Setup Guide"
+  icon="aws"
+  href="/v7/aws-setup"
+>
+  Step-by-step instructions for deploying TestDriver on your AWS infrastructure using CloudFormation.
+</Card>
+
+
+## Who Should Self-Host?
+
+Self-hosting is ideal for teams that:
+
+- **Run high test volumes** — Flat pricing becomes more economical at scale
+- **Want infrastructure control** — Custom hardware, specific software dependencies, or network configurations
+- **Prefer predictable costs** — Budget with confidence using flat monthly fees
+
+
+## How It Works
+
+With self-hosting, you run test sandboxes on your own AWS infrastructure. TestDriver still provides:
+
+- **Dashboard** — View test results, analytics, and reports at [console.testdriver.ai](https://console.testdriver.ai)
+- **API** — Orchestration and AI-powered test execution
+- **License Management** — Your parallel test capacity
+
+You provide:
+
+- **AWS Infrastructure** — EC2 instances running in your account
+- **AI API Keys** — Use your own OpenAI, Anthropic, or other AI provider keys
+- **Custom Configuration** — Hardware specs, networking, installed software
+
+## Comparison vs Cloud
+
+| Feature | Cloud | Self-Hosted |
+|---------|-------|-------------|
+| **Setup Time** | Minutes | Hours |
+| **Pricing Model** | Device-seconds | Flat license fee |
+| **Infrastructure Management** | TestDriver | You |
+| **Device Location** | TestDriver cloud | Your AWS account |
+| **AI API Keys** | TestDriver's | Your own |
+| **Custom Software** | Limited | Full control |
+| **Hardware Selection** | Standard | Your choice |
+| **Debugging Access** | Replays only | Full RDP access |

package/docs/v7/{api/type.mdx → type.mdx}

@@ -353,6 +353,6 @@ describe('Form Filling with Type', () => {
 
 ## Related Methods
 
-- [`pressKeys()`](/v7/api/pressKeys) - Press keyboard keys and shortcuts
-- [`find()`](/v7/api/find) - Locate input fields
-- [`click()`](/v7/api/click) - Focus input fields
+- [`pressKeys()`](/v7/press-keys) - Press keyboard keys and shortcuts
+- [`find()`](/v7/find) - Locate input fields
+- [`click()`](/v7/click) - Focus input fields

package/docs/v7/variables.mdx

@@ -0,0 +1,111 @@
+---
+title: "Using Variables"
+description: "Use dynamic data and secure secrets in your tests"
+icon: "square-root-variable"
+---
+
+Scale your testing with dynamic data and secure secrets management. Choose the right approach based on your testing needs.
+
+## Environment Variables
+
+Environment variables are ideal for **configuration that changes between environments** (dev, staging, production) or for **secrets that shouldn't be committed to code**. Use this approach when you need to run the same tests against different servers or with different credentials.
+
+```javascript
+import { test } from 'vitest';
+import { chrome } from 'testdriverai/presets';
+
+test('multi-environment testing', async (context) => {
+  const env = process.env.TEST_ENV || 'staging';
+  const urls = {
+    dev: 'https://dev.myapp.com',
+    staging: 'https://staging.myapp.com',
+    production: 'https://myapp.com'
+  };
+
+  const { testdriver } = await chrome(context, { 
+    url: urls[env] 
+  });
+
+  await testdriver.assert('app is running');
+});
+```
+
+```bash
+# Run against different environments
+TEST_ENV=dev npx vitest run
+TEST_ENV=staging npx vitest run
+TEST_ENV=production npx vitest run
+```
+
+## Test Fixtures
+
+Test fixtures work best when you have **structured, reusable test data** that needs to be shared across multiple tests. Use fixtures when testing different user roles, product catalogs, or any scenario where you want to parameterize tests with a known set of data.
+
+```javascript test/fixtures/users.js
+export const testUsers = [
+  { email: 'admin@test.com', role: 'admin' },
+  { email: 'user@test.com', role: 'user' },
+  { email: 'guest@test.com', role: 'guest' }
+];
+
+export const products = [
+  { name: 'Laptop', price: 999 },
+  { name: 'Mouse', price: 29 },
+  { name: 'Keyboard', price: 89 }
+];
+```
+
+```javascript test/permissions.test.js
+import { test } from 'vitest';
+import { chrome } from 'testdriverai/presets';
+import { testUsers } from './fixtures/users.js';
+
+test.each(testUsers)('$role can access dashboard', async ({ email, role }, context) => {
+  const { testdriver } = await chrome(context, { url });
+  
+  await testdriver.find('email input').type(email);
+  await testdriver.find('password input').type('password123');
+  await testdriver.find('login button').click();
+  
+  if (role === 'admin') {
+    await testdriver.assert('admin panel is visible');
+  } else {
+    await testdriver.assert('user dashboard is visible');
+  }
+});
+```
+
+## Dynamic Data Generation
+
+Dynamic data generation is perfect for **creating unique test data on each run**, avoiding conflicts with existing records, and **testing edge cases with realistic data**. Use libraries like Faker when you need fresh emails, names, or other data that won't collide with previous test runs.
+
+```javascript
+import { test } from 'vitest';
+import { chrome } from 'testdriverai/presets';
+import { faker } from '@faker-js/faker';
+
+test('user registration with dynamic data', async (context) => {
+  const { testdriver } = await chrome(context, { url });
+
+  // Generate unique test data for each run
+  const userData = {
+    firstName: faker.person.firstName(),
+    lastName: faker.person.lastName(),
+    email: faker.internet.email(),
+    password: faker.internet.password({ length: 12 })
+  };
+
+  await testdriver.find('first name input').type(userData.firstName);
+  await testdriver.find('last name input').type(userData.lastName);
+  await testdriver.find('email input').type(userData.email);
+  await testdriver.find('password input').type(userData.password);
+  await testdriver.find('register button').click();
+
+  await testdriver.assert('registration successful');
+  console.log('Registered user:', userData.email);
+});
+```
+
+```bash
+npm install --save-dev @faker-js/faker
+```

package/docs/v7/waiting-for-elements.mdx

@@ -0,0 +1,66 @@
+---
+title: "Waiting for Elements"
+description: "Handle async operations and prevent flaky tests"
+icon: "clock"
+---
+
+## Waiting for Elements
+
+Use the `timeout` option with `find()` to wait for elements that appear after async operations:
+
+```javascript
+// Wait up to 30 seconds for element to appear (polls every 5 seconds)
+const element = await testdriver.find('Loading complete indicator', { timeout: 30000 });
+await element.click();
+
+// Useful after actions that trigger loading states
+await testdriver.find('submit button').click();
+await testdriver.find('success message', { timeout: 15000 });
+
+// Short timeout for quick checks
+const toast = await testdriver.find('notification toast', { timeout: 5000 });
+```
+
+## Flake Prevention
+
+TestDriver automatically waits for the screen and network to stabilize after each action using **redraw detection**. This prevents flaky tests caused by animations, loading states, or dynamic content updates.
+
+<Note>
+  Redraw detection adds a small delay after each action but significantly reduces test flakiness.
+</Note>
+
+For example, when clicking a submit button that navigates to a new page:
+
+```javascript
+// Click submit - TestDriver automatically waits for the new page to load
+await testdriver.find('submit button').click();
+
+// By the time this runs, the page has fully loaded and stabilized
+await testdriver.assert('dashboard is displayed');
+await testdriver.find('welcome message');
+```
+
+Without redraw detection, you'd need manual waits or retries to handle the page transition. TestDriver handles this automatically by detecting when the screen stops changing and network requests complete.
+
+You can disable redraw detection or customize its behavior:
+
+```javascript
+// Disable redraw detection for faster tests (less reliable)
+const testdriver = TestDriver(context, { 
+  redraw: false 
+});
+```
+
+Here is an example of customizing redraw detection:
+
+```javascript
+// Fine-tune redraw detection
+const testdriver = TestDriver(context, { 
+  redraw: {
+    enabled: true,
+    diffThreshold: 0.1,      // Pixel difference threshold (0-1)
+    screenRedraw: true,      // Monitor screen changes
+    networkMonitor: true,    // Wait for network idle
+  }
+});
+```

package/docs/v7/what-is-testdriver.mdx

@@ -0,0 +1,54 @@
+---
+title: "What is TestDriver?"
+description: "Reliably test your most difficult user flows"
+icon: "circle-info"
+---
+
+## The problem with modern testing tools
+
+Modern testing tools like Playwright are designed to test a single web application, running in a single browser tab using selectors.
+
+However, selectors are often either unreliable or unavailable in complex scenarios, leading to brittle and flaky tests:
+
+| Challenge | Problem | Examples |
+|-----------|---------|----------|
+| **Fast moving teams** | Frequently change UI structure, breaking CSS/XPath selectors | Agile teams, startups, vibe-coders |
+| **Dynamic content** | Cannot be targeted with selectors | AI chatbots, PDFs, images, videos |
+| **Software you don't own** | May lack proper accessibility attributes | Other websites, extensions, third-party applications |
+| **Multi-application workflows** | Cannot be tested with web-only tools | Desktop apps, browser extensions, IDEs |
+| **Visual states** | Impossible to verify with code-based selectors | Charts, graphs, videos, images, spelling errors, UI layout |
+
+## The TestDriver Solution
+
+TestDriver is a complete testing platform built specifically for handling these scenarios. It consists of a Javascript SDK, hosted infrastructure, and debugging tools that make it easy to write, run, and maintain tests for your most difficult user flows.
+
+### Javascript SDK
+
+Here is an example of a TestDriver test that installs a production Chrome extension from the Chrome Web Store and verifies that it appears in the extensions menu:
+
+```javascript Installing Loom from the Chrome Web Store
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "testdriverai/vitest/hooks";
+
+describe("Chrome Extension Test", () => {
+  const testdriver = TestDriver(context);
+
+  // Launch Chrome with Loom loaded by its Chrome Web Store ID
+  await testdriver.provision.chromeExtension({
+    extensionId: 'liecbddmkiiihnedobmlmillhodjkdmb'
+  });
+
+  // Click on the extensions button (puzzle piece icon) in Chrome toolbar
+  const extensionsButton = await testdriver.find("The puzzle-shaped icon in the Chrome toolbar.");
+  await extensionsButton.click();
+
+  // Look for Loom in the extensions menu
+  const loomExtension = await testdriver.find("Loom extension in the extensions dropdown");
+  expect(loomExtension.found()).toBeTruthy();
+});
+```
+
+
+<Tip>[vitest](https://vitest.dev/) is the preferred test runner for TestDriver.</Tip>
+
+,