testdriverai 7.2.3 → 7.2.10

package/docs/v7/{api/mouseUp.mdx → mouse-up.mdx}

@@ -6,7 +6,7 @@ icon: "arrow-pointer"
 
 ## Overview
 
-The `mouseUp()` method releases the mouse button, completing a drag operation or custom mouse gesture that was started with [`mouseDown()`](/v7/api/mouseDown). You can call it without parameters to release at the current mouse position.
+The `mouseUp()` method releases the mouse button, completing a drag operation or custom mouse gesture that was started with [`mouseDown()`](/v7/mouse-down). You can call it without parameters to release at the current mouse position.
 
 ## Syntax
 
@@ -150,15 +150,15 @@ test('selects text with mouse drag', async () => {
 
 ## Important Notes
 
-- `mouseUp()` must be preceded by [`mouseDown()`](/v7/api/mouseDown) to have an effect
+- `mouseUp()` must be preceded by [`mouseDown()`](/v7/mouse-down) to have an effect
 - Releases the button at the current cursor position
 - Completes any drag or selection operation that was in progress
-- For simple clicks, use [`click()`](/v7/api/click) instead of mouseDown/mouseUp pair
+- For simple clicks, use [`click()`](/v7/click) instead of mouseDown/mouseUp pair
 
 ## Related Methods
 
-- [`mouseDown()`](/v7/api/mouseDown) - Press mouse button without releasing
-- [`hover()`](/v7/api/hover) - Move mouse to element
-- [`click()`](/v7/api/click) - Complete click (mouseDown + mouseUp)
-- [`doubleClick()`](/v7/api/doubleClick) - Double-click on element
-- [`rightClick()`](/v7/api/rightClick) - Right-click for context menu
+- [`mouseDown()`](/v7/mouse-down) - Press mouse button without releasing
+- [`hover()`](/v7/hover) - Move mouse to element
+- [`click()`](/v7/click) - Complete click (mouseDown + mouseUp)
+- [`doubleClick()`](/v7/double-click) - Double-click on element
+- [`rightClick()`](/v7/right-click) - Right-click for context menu

package/docs/v7/performing-actions.mdx

@@ -0,0 +1,51 @@
+---
+title: "Performing Actions"
+description: "Click, type, hover, scroll and more with TestDriver"
+icon: "computer-mouse"
+---
+
+## Performing Actions
+
+TestDriver provides a variety of actions you can perform, like [clicking](/v7/click), [typing](/v7/type), [hovering](/v7/hover), and [scrolling](/v7/scroll). For a full list, see the [API Reference](/v7/click).
+
+```javascript
+// Clicking
+await testdriver.find('submit button').click();
+await testdriver.find('file item').doubleClick();
+await testdriver.find('text area').rightClick();
+
+// Typing
+await testdriver.find('email input').type('user@example.com');
+await testdriver.find('password input').type('secret', { secret: true });
+
+// Keyboard shortcuts
+await testdriver.pressKeys(['enter']);
+await testdriver.pressKeys(['ctrl', 'c']);
+
+// Hovering
+await testdriver.find('dropdown menu').hover();
+
+// Scrolling
+await testdriver.scroll('down', 500);
+await testdriver.scrollUntilText('Footer content');
+
+// Extracting information from screen
+const price = await testdriver.extract('the total price');
+const orderNumber = await testdriver.extract('the order confirmation number');
+```
+
+## Chaining Actions
+
+TestDriver supports method chaining for cleaner code:
+
+```javascript
+// Chain find() with actions
+const button = await testdriver.find('submit button').click();
+```
+
+Or save element reference for later use:
+
+```javascript
+const button = await testdriver.find('submit button');
+await button.click();
+```

package/docs/v7/{api/pressKeys.mdx → press-keys.mdx}

@@ -344,6 +344,6 @@ describe('Keyboard Navigation', () => {
 
 ## Related Methods
 
-- [`type()`](/v7/api/type) - Type text
-- [`click()`](/v7/api/click) - Click elements
-- [`scroll()`](/v7/api/scroll) - Scroll pages
+- [`type()`](/v7/type) - Type text
+- [`click()`](/v7/click) - Click elements
+- [`scroll()`](/v7/scroll) - Scroll pages

package/docs/v7/quickstart.mdx

@@ -0,0 +1,162 @@
+---
+title: "Quick Start"
+sidebarTitle: "Quickstart"
+description: "Run your first computer-use test in minutes."
+icon: "rocket"
+---
+
+TestDriver makes it easy to write automated computer-use tests for web browsers, desktop apps, and more. Follow the directions below to run your first TestDriver test.
+
+<Tip><a href="https://discord.com/invite/cWDFW8DzPm" target="_blank" rel="noreferrer">Join our Discord</a> if you have any questions or need help getting started!</Tip>
+
+<Tabs>
+  <Tab title="Automatic Setup">
+
+    Get started quickly with the TestDriver CLI.
+
+    <Steps>
+      <Step title="Create a TestDriver Account">
+
+        You will need a TestDriver account to get an API key.
+
+        <Card
+          title="Sign Up for TestDriver"
+          icon="user-plus"
+          href="https://app.testdriver.ai/team"
+          arrow
+          horizontal
+        >
+          No credit-card required!
+        </Card>
+
+      </Step>
+      <Step title="Install TestDriver">
+
+        Use `npx` to quickly set up an example project:
+
+        ```bash
+        npx testdriverai@beta init
+        ```
+
+        This will walk you through creating a new project folder, installing dependencies, and setting up your API key.
+
+      </Step>
+      
+      <Step title="Run Your Test">
+
+        TestDriver uses Vitest as the test runner. To run your test, use:
+        
+        ```bash
+        vitest run
+        ```
+
+        This will spawn a sandbox, launch Chrome, and run the example test!
+
+      </Step>
+    </Steps>
+  </Tab>
+  <Tab title="Manual Setup">
+
+    Install TestDriver and manually create the files yourself.
+
+    <Steps>
+      <Step title="Create a TestDriver Account">
+
+        You will need a TestDriver account to get an API key.
+
+        <Card
+          title="Sign Up for TestDriver"
+          icon="user-plus"
+          href="https://app.testdriver.ai/team"
+          arrow
+          horizontal
+        >
+          No credit-card required!
+        </Card>
+
+      </Step>
+      <Step title="Install Dependencies">
+
+        Install Vitest and TestDriver as dev dependencies:
+
+        ```bash
+        npm install --save-dev vitest testdriverai@beta
+        ```
+
+      </Step>
+      <Step title="Create a vitest.config.js File">
+
+        In your project root, create a `vitest.config.js` file with the following content:
+
+        ```js vitest.config.js
+        import TestDriver from 'testdriverai/vitest';
+        import { defineConfig } from 'vitest/config';
+
+        export default defineConfig({
+          test: {
+            testTimeout: 900000,
+            hookTimeout: 900000,
+            disableConsoleIntercept: true,
+            maxConcurrency: 1, // this should match your plan's concurrency limit 
+            reporters: [
+              'default',
+              TestDriver()
+            ],
+            setupFiles: ['testdriverai/vitest/setup'],
+          },
+        });
+        ```
+
+      </Step>
+      <Step title="Create an Example Test File">
+
+        Add your API key to the example test file below and save it as `test.mjs` in your project root.
+
+        ```js test.mjs highlight={9}
+        import { describe, expect, it } from "vitest";
+        // Import TestDriver from the vitest hooks
+        import { TestDriver } from "testdriverai/vitest/hooks";
+
+        describe("Google Search Example", () => {
+          it("should search for TestDriver", async (context) => {
+            // Create TestDriver instance - automatically connects to sandbox
+            const testdriver = TestDriver(context, {
+              apiKey: 'YOUR_API_KEY_HERE' // supply your API key here 
+            });
+
+            // Provision Chrome browser with a URL
+            // This also starts dashcam recording automatically
+            await testdriver.provision.chrome({ url: "https://duckduckgo.com" });
+
+            // Find and interact with elements using natural language
+            const searchBox = await testdriver.find("DuckDuckGo search input field");
+            await searchBox.click();
+
+            // Type into the focused element
+            await testdriver.type("testdriver.ai");
+
+            // Press Enter to search
+            await testdriver.pressKeys(["enter"]);
+
+            // Assert something is visible on the page
+            const result = await testdriver.assert("search results are displayed");
+            expect(result).toBeTruthy();
+          });
+        });
+        ```
+
+      </Step>
+      <Step title="Run Your Test">
+
+        TestDriver uses Vitest as the test runner. To run your test, use:
+        
+        ```bash
+        vitest run
+        ```
+
+        This will spawn a sandbox, launch Chrome, and run the example test!
+
+      </Step>
+    </Steps>
+  </Tab>
+</Tabs>

package/docs/v7/reusable-code.mdx

@@ -0,0 +1,240 @@
+---
+title: "Reusable Code Snippets"
+description: "Build maintainable test suites with reusable code patterns"
+icon: "recycle"
+---
+
+As your test suite grows, you'll want to extract common patterns into reusable code. This keeps tests DRY, readable, and easy to maintain.
+
+## Helper Functions
+
+The simplest approach is extracting common actions into helper functions. Create a `helpers/` directory for shared utilities:
+
+```javascript test/helpers/auth.js
+export async function login(testdriver, { email, password }) {
+  const emailInput = await testdriver.find('email input');
+  await emailInput.click();
+  await testdriver.type(email);
+  
+  const passwordInput = await testdriver.find('password input');
+  await passwordInput.click();
+  await testdriver.type(password);
+  
+  const loginButton = await testdriver.find('login button');
+  await loginButton.click();
+  
+  const result = await testdriver.assert('user is logged in');
+  return result;
+}
+
+export async function logout(testdriver) {
+  const userMenu = await testdriver.find('user menu');
+  await userMenu.click();
+  
+  const logoutButton = await testdriver.find('logout button');
+  await logoutButton.click();
+}
+```
+
+Now import and use these helpers in any test:
+
+```javascript test/checkout.test.mjs
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "testdriverai/lib/vitest/hooks.mjs";
+import { login } from './helpers/auth.js';
+
+describe("Checkout", () => {
+  it("should complete checkout as logged in user", async (context) => {
+    const testdriver = TestDriver(context, { newSandbox: true });
+    
+    await testdriver.provision.chrome({
+      url: 'https://shop.example.com',
+    });
+
+    // Use the helper
+    await login(testdriver, { 
+      email: 'user@example.com', 
+      password: 'password123' 
+    });
+
+    // Continue with checkout steps...
+    const cartButton = await testdriver.find('cart button');
+    await cartButton.click();
+  });
+});
+```
+
+## Page Objects
+
+For larger test suites, the Page Object pattern encapsulates all interactions with a specific page or component:
+
+```javascript test/pages/LoginPage.js
+export class LoginPage {
+  constructor(testdriver) {
+    this.td = testdriver;
+  }
+
+  async enterEmail(email) {
+    const input = await this.td.find('email input');
+    await input.click();
+    await this.td.type(email);
+  }
+
+  async enterPassword(password) {
+    const input = await this.td.find('password input');
+    await input.click();
+    await this.td.type(password);
+  }
+
+  async submit() {
+    const button = await this.td.find('submit button');
+    await button.click();
+  }
+
+  async login(email, password) {
+    await this.enterEmail(email);
+    await this.enterPassword(password);
+    await this.submit();
+  }
+
+  async assertError(message) {
+    return await this.td.assert(`error message shows "${message}"`);
+  }
+
+  async assertLoggedIn() {
+    return await this.td.assert('user dashboard is visible');
+  }
+}
+```
+
+Use the page object in your tests:
+
+```javascript test/auth.test.mjs
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "testdriverai/lib/vitest/hooks.mjs";
+import { LoginPage } from './pages/LoginPage.js';
+
+describe("Authentication", () => {
+  it("should show error for invalid credentials", async (context) => {
+    const testdriver = TestDriver(context, { newSandbox: true });
+    
+    await testdriver.provision.chrome({
+      url: 'https://app.example.com/login',
+    });
+
+    const loginPage = new LoginPage(testdriver);
+    
+    await loginPage.login('invalid@test.com', 'wrongpassword');
+    
+    const hasError = await loginPage.assertError('Invalid credentials');
+    expect(hasError).toBeTruthy();
+  });
+
+  it("should redirect to dashboard on success", async (context) => {
+    const testdriver = TestDriver(context, { newSandbox: true });
+    
+    await testdriver.provision.chrome({
+      url: 'https://app.example.com/login',
+    });
+
+    const loginPage = new LoginPage(testdriver);
+    
+    await loginPage.login('valid@test.com', 'correctpassword');
+    
+    const isLoggedIn = await loginPage.assertLoggedIn();
+    expect(isLoggedIn).toBeTruthy();
+  });
+});
+```
+
+## Shared Test Fixtures
+
+Create reusable fixtures for common test setup scenarios:
+
+```javascript test/fixtures/index.js
+export const testUsers = {
+  admin: { email: 'admin@example.com', password: 'admin123' },
+  regular: { email: 'user@example.com', password: 'user123' },
+  guest: { email: 'guest@example.com', password: 'guest123' },
+};
+
+export const testUrls = {
+  staging: 'https://staging.example.com',
+  production: 'https://example.com',
+};
+
+export async function setupAuthenticatedSession(testdriver, user = testUsers.regular) {
+  const emailInput = await testdriver.find('email input');
+  await emailInput.click();
+  await testdriver.type(user.email);
+  
+  const passwordInput = await testdriver.find('password input');
+  await passwordInput.click();
+  await testdriver.type(user.password);
+  
+  const loginButton = await testdriver.find('login button');
+  await loginButton.click();
+  
+  await testdriver.assert('user is logged in');
+}
+```
+
+```javascript test/admin.test.mjs
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "testdriverai/lib/vitest/hooks.mjs";
+import { testUsers, testUrls, setupAuthenticatedSession } from './fixtures/index.js';
+
+describe("Admin Panel", () => {
+  it("should access admin settings", async (context) => {
+    const testdriver = TestDriver(context, { newSandbox: true });
+    
+    await testdriver.provision.chrome({
+      url: `${testUrls.staging}/login`,
+    });
+
+    await setupAuthenticatedSession(testdriver, testUsers.admin);
+
+    const settingsLink = await testdriver.find('admin settings link');
+    await settingsLink.click();
+    
+    const result = await testdriver.assert('admin settings panel is visible');
+    expect(result).toBeTruthy();
+  });
+});
+```
+
+## Suggested Project Structure
+
+<FileTree>
+  <Folder name="test" defaultOpen>
+    <Folder name="fixtures" defaultOpen>
+      <File name="index.js" />
+    </Folder>
+    <Folder name="helpers" defaultOpen>
+      <File name="auth.js" />
+      <File name="navigation.js" />
+      <File name="forms.js" />
+    </Folder>
+    <Folder name="pages" defaultOpen>
+      <File name="LoginPage.js" />
+      <File name="DashboardPage.js" />
+      <File name="CheckoutPage.js" />
+    </Folder>
+    <Folder name="specs" defaultOpen>
+      <File name="auth.test.mjs" />
+      <File name="checkout.test.mjs" />
+      <File name="search.test.mjs" />
+    </Folder>
+  </Folder>
+</FileTree>
+
+| Folder | Purpose |
+|--------|---------|
+| `fixtures/` | Test data and setup utilities |
+| `helpers/` | Reusable helper functions |
+| `pages/` | Page object classes |
+| `specs/` | Test files |
+
+<Tip>
+Start simple with helper functions. Only introduce page objects when you find yourself duplicating the same element interactions across multiple tests.
+</Tip>

package/docs/v7/{api/rightClick.mdx → right-click.mdx}

@@ -116,8 +116,8 @@ test('uses custom context menu', async () => {
 
 ## Related Methods
 
-- [`click()`](/v7/api/click) - Single click on an element
-- [`doubleClick()`](/v7/api/doubleClick) - Double-click on an element
-- [`mouseDown()`](/v7/api/mouseDown) - Press mouse button without releasing
-- [`mouseUp()`](/v7/api/mouseUp) - Release mouse button
-- [`hover()`](/v7/api/hover) - Move mouse over element without clicking
+- [`click()`](/v7/click) - Single click on an element
+- [`doubleClick()`](/v7/double-click) - Double-click on an element
+- [`mouseDown()`](/v7/mouse-down) - Press mouse button without releasing
+- [`mouseUp()`](/v7/mouse-up) - Release mouse button
+- [`hover()`](/v7/hover) - Move mouse over element without clicking

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>