@testdriverai/agent 7.8.0-canary.10

package/docs/v7/type.mdx

@@ -0,0 +1,358 @@
+---
+title: "type()"
+sidebarTitle: "type"
+description: "Type text into focused input fields"
+icon: "keyboard"
+---
+
+## Overview
+
+Type text or numbers into the currently focused input field with optional delay between keystrokes.
+
+## Syntax
+
+```javascript
+await testdriver.type(text, options)
+```
+
+## Parameters
+
+<ParamField path="text" type="string | number" required>
+  Text to type (can be a string or number)
+</ParamField>
+
+<ParamField path="options" type="object | number">
+  Typing options (or legacy delay number)
+  
+  <Expandable title="properties">
+    <ParamField path="delay" type="number" default={250}>
+      Delay between keystrokes in milliseconds
+    </ParamField>
+    
+    <ParamField path="secret" type="boolean" default={false}>
+      If `true`, treats text as sensitive data (won't be logged or stored in debug info/dashcam)
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+## Returns
+
+`Promise<void>`
+
+## Examples
+
+### Basic Typing
+
+```javascript
+// Type text
+await testdriver.type('hello@example.com');
+
+// Type numbers
+await testdriver.type(12345);
+
+// Type with custom delay (legacy syntax)
+await testdriver.type('slow typing', 500); // 500ms between each character
+
+// Type with options object
+await testdriver.type('text', { delay: 500 });
+```
+
+### Password/Secret Handling
+
+```javascript
+// ✅ SECURE - Mark as secret to prevent logging
+const passwordField = await testdriver.find('password input');
+await passwordField.click();
+await testdriver.type('MySecureP@ssw0rd', { secret: true });
+// Password NOT logged in dashcam or debug output
+
+// ❌ INSECURE - Password will be logged
+await testdriver.type('MySecureP@ssw0rd');
+// Password appears in logs, dashcam replay, and debug info
+
+// Use secret for any sensitive data
+await testdriver.find('api key input').click();
+await testdriver.type('sk-1234567890abcdef', { secret: true });
+
+await testdriver.find('credit card input').click();
+await testdriver.type('4111111111111111', { secret: true });
+```
+
+<Warning>
+  **Always use `secret: true` for passwords and sensitive data!**
+  
+  Without this option, typed text appears in:
+  - Dashcam video replays
+  - TestDriver logs
+  - Debug screenshots
+  - Error messages
+</Warning>
+
+### Form Filling
+
+```javascript
+// Focus field and type
+const emailField = await testdriver.find('email input');
+await emailField.click();
+await testdriver.type('user@example.com');
+
+// Tab to next field and type
+await testdriver.pressKeys(['tab']);
+await testdriver.type('John Doe');
+
+// Type password securely
+await testdriver.pressKeys(['tab']);
+await testdriver.type('MySecureP@ssw0rd', { secret: true });
+```
+
+### Clearing and Replacing Text
+
+```javascript
+const searchBox = await testdriver.find('search input');
+await searchBox.click();
+
+// Clear existing text
+await testdriver.pressKeys(['ctrl', 'a']); // Select all
+await testdriver.type('new search query');
+```
+
+## Best Practices
+
+<Check>
+  **Focus the field first**
+  
+  Always click the input field or navigate to it before typing:
+  
+  ```javascript
+  const input = await testdriver.find('username input');
+  await input.click();
+  await testdriver.type('testuser');
+  ```
+</Check>
+
+<Check>
+  **Use Tab for navigation**
+  
+  Navigate between fields using Tab instead of clicking each one:
+  
+  ```javascript
+  const firstField = await testdriver.find('first name');
+  await firstField.click();
+  await testdriver.type('John');
+  
+  await testdriver.pressKeys(['tab']);
+  await testdriver.type('Doe');
+  
+  await testdriver.pressKeys(['tab']);
+  await testdriver.type('john@example.com');
+  ```
+</Check>
+
+<Check>
+  **Clear fields before typing**
+  
+  Clear existing content to avoid appending:
+  
+  ```javascript
+  const input = await testdriver.find('search field');
+  await input.click();
+  await testdriver.pressKeys(['ctrl', 'a']); // Select all
+  await testdriver.type('new search');
+  ```
+</Check>
+
+<Warning>
+  **Field must be focused**
+  
+  Typing will only work if an input field is currently focused. If no field is focused, the text may be lost or trigger unexpected keyboard shortcuts.
+</Warning>
+
+## Use Cases
+
+<AccordionGroup>
+  <Accordion title="Login Forms">
+    ```javascript
+    await testdriver.focusApplication('Google Chrome');
+    
+    const usernameField = await testdriver.find('username input');
+    await usernameField.click();
+    await testdriver.type('testuser@example.com');
+    
+    await testdriver.pressKeys(['tab']);
+    await testdriver.type('MyP@ssword123', { secret: true });
+    
+    await testdriver.pressKeys(['enter']);
+    ```
+  </Accordion>
+  
+  <Accordion title="Search Fields">
+    ```javascript
+    const searchBox = await testdriver.find('search input');
+    await searchBox.click();
+    await testdriver.type('laptop computers');
+    await testdriver.pressKeys(['enter']);
+    
+    // Wait for results
+    await new Promise(r => setTimeout(r, 2000));
+    ```
+  </Accordion>
+  
+  <Accordion title="Multi-Field Forms">
+    ```javascript
+    // First field
+    const nameField = await testdriver.find('full name input');
+    await nameField.click();
+    await testdriver.type('Jane Smith');
+    
+    // Navigate with Tab
+    await testdriver.pressKeys(['tab']);
+    await testdriver.type('jane.smith@example.com');
+    
+    await testdriver.pressKeys(['tab']);
+    await testdriver.type('+1-555-0123');
+    
+    await testdriver.pressKeys(['tab']);
+    await testdriver.type('123 Main Street');
+    ```
+  </Accordion>
+  
+  <Accordion title="Text Editors">
+    ```javascript
+    const editor = await testdriver.find('text editor area');
+    await editor.click();
+    
+    await testdriver.type('# My Document', 100);
+    await testdriver.pressKeys(['enter', 'enter']);
+    await testdriver.type('This is the first paragraph.', 50);
+    ```
+  </Accordion>
+  
+  <Accordion title="Numeric Input">
+    ```javascript
+    const quantityField = await testdriver.find('quantity input');
+    await quantityField.click();
+    
+    // Clear field
+    await testdriver.pressKeys(['ctrl', 'a']);
+    
+    // Type number
+    await testdriver.type(5);
+    ```
+  </Accordion>
+</AccordionGroup>
+
+## Typing Speed
+
+Adjust the delay parameter based on your needs:
+
+```javascript
+// Fast typing (100ms delay)
+await testdriver.type('quick entry', 100);
+
+// Normal typing (250ms - default)
+await testdriver.type('standard speed');
+
+// Slow typing (500ms delay) - useful for fields with live validation
+await testdriver.type('slow and steady', 500);
+
+// Very slow (1000ms delay) - for problematic fields
+await testdriver.type('one by one', 1000);
+```
+
+<Note>
+  Some applications with live validation or autocomplete may require slower typing speeds to avoid race conditions.
+</Note>
+
+## Special Characters
+
+```javascript
+// Email addresses
+await testdriver.type('user@example.com');
+
+// URLs
+await testdriver.type('https://example.com/path?query=value');
+
+// Passwords with special characters
+await testdriver.type('P@ssw0rd!#$%');
+
+// Paths
+await testdriver.type('C:\\Users\\Documents\\file.txt');
+
+// Multi-line text (use pressKeys for Enter)
+await testdriver.type('Line 1');
+await testdriver.pressKeys(['enter']);
+await testdriver.type('Line 2');
+```
+
+## Complete Example
+
+```javascript
+import { beforeAll, afterAll, describe, it, expect } from 'vitest';
+import TestDriver from 'testdriverai';
+
+describe('Form Filling with Type', () => {
+  let testdriver;
+
+  beforeAll(async () => {
+    client = new TestDriver(process.env.TD_API_KEY);
+    await testdriver.auth();
+    await testdriver.connect();
+  });
+
+  afterAll(async () => {
+    await testdriver.disconnect();
+  });
+
+  it('should fill out registration form', async () => {
+    await testdriver.focusApplication('Google Chrome');
+    
+    // Email field
+    const emailField = await testdriver.find('email input field');
+    await emailField.click();
+    await testdriver.type('john.doe@example.com');
+    
+    // Tab through form fields
+    await testdriver.pressKeys(['tab']);
+    await testdriver.type('John');
+    
+    await testdriver.pressKeys(['tab']);
+    await testdriver.type('Doe');
+    
+    await testdriver.pressKeys(['tab']);
+    await testdriver.type('MySecureP@ssword123');
+    
+    await testdriver.pressKeys(['tab']);
+    await testdriver.type('MySecureP@ssword123'); // Confirm password
+    
+    // Verify fields were filled
+    const result = await testdriver.assert('all form fields are filled');
+    expect(result).toBeTruthy();
+  });
+
+  it('should update search query', async () => {
+    const searchBox = await testdriver.find('search input');
+    await searchBox.click();
+    
+    // Type initial search
+    await testdriver.type('laptops');
+    await testdriver.pressKeys(['enter']);
+    
+    await new Promise(r => setTimeout(r, 2000));
+    
+    // Update search
+    await searchBox.click();
+    await testdriver.pressKeys(['ctrl', 'a']); // Select all
+    await testdriver.type('gaming laptops');
+    await testdriver.pressKeys(['enter']);
+    
+    // Verify new search
+    await testdriver.assert('search results for "gaming laptops" are shown');
+  });
+});
+```
+
+## Related Methods
+
+- [`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 vitest run
+TEST_ENV=staging vitest run
+TEST_ENV=production 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/wait.mdx

@@ -0,0 +1,52 @@
+---
+title: "wait"
+sidebarTitle: "wait"
+description: "Pause the execution of the script for a specified duration."
+icon: "clock"
+"mode": "wide"
+---
+
+## Description
+
+The `wait` method pauses test execution for a specified number of milliseconds before continuing. This is useful for adding delays between actions, waiting for animations to complete, or pausing for state changes to settle.
+
+## Syntax
+
+```javascript
+await testdriver.wait(timeout);
+```
+
+## Arguments
+
+| Argument  | Type     | Default | Description                           |
+| --------- | -------- | ------- | ------------------------------------- |
+| `timeout` | `number` | `3000`  | The duration in milliseconds to wait. |
+
+## Examples
+
+```javascript
+// Wait 2 seconds for an animation to complete
+await testdriver.find('submit button').click();
+await testdriver.wait(2000);
+
+// Wait 5 seconds
+await testdriver.wait(5000);
+
+// Wait with default timeout (3 seconds)
+await testdriver.wait();
+```
+
+## Best Practices
+
+- **Use for simple delays** — waiting for animations, transitions, or state changes after an action.
+- **Avoid for element waiting** — if you're waiting for a specific element to appear, use `find()` with a `timeout` option instead:
+  ```javascript
+  // ✅ Better for waiting for elements
+  const element = await testdriver.find('success message', { timeout: 30000 });
+
+  // ❌ Don't do this for element waiting
+  await testdriver.wait(5000);
+  const element = await testdriver.find('success message');
+  ```
+- Avoid excessively long timeouts to keep tests efficient.
+- Use sparingly — TestDriver's [redraw detection](/v7/waiting-for-elements) automatically waits for screen and network stability after each action.

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

@@ -0,0 +1,90 @@
+---
+title: "Waiting for Elements"
+description: "Handle async operations and prevent flaky tests"
+icon: "clock"
+---
+
+## Waiting for Elements
+
+By default, `find()` automatically polls for up to 10 seconds, retrying every 5 seconds until the element is found. This means most elements that appear after short async operations will be found without any extra configuration.
+
+For longer operations, increase the `timeout`:
+
+```javascript
+// Default behavior - polls for up to 10 seconds automatically
+const element = await testdriver.find('Loading complete indicator');
+await element.click();
+
+// Wait up to 30 seconds for slower operations
+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 });
+
+// Disable polling for instant checks
+const toast = await testdriver.find('notification toast', { timeout: 0 });
+```
+
+## 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
+  }
+});
+```
+
+## Simple Delays with `wait()`
+
+For simple pauses — waiting for animations, transitions, or state changes after an action — use `wait()`:
+
+```javascript
+// Wait for an animation to complete
+await testdriver.find('menu toggle').click();
+await testdriver.wait(2000);
+
+// Wait for a page transition to settle
+await testdriver.find('next page button').click();
+await testdriver.wait(1000);
+```
+
+<Note>
+  For waiting for specific **elements** to appear, prefer `find()` with a `timeout` option. Use `wait()` only for simple time-based pauses.
+</Note>

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>
+
+,