testdriverai 7.2.9 → 7.2.11

package/docs/v7/locating-elements.mdx

@@ -0,0 +1,71 @@
+---
+title: "Locating Elements"
+description: "Find UI elements using natural language descriptions"
+icon: "crosshairs"
+---
+
+## Locating Single Elements
+
+Use natural language to describe elements. Descriptions should be specific enough to locate the element, but not too-specific that they break with minor UI changes. For example:
+
+```javascript
+await testdriver.find('email input field');
+await testdriver.find('first product card in the grid');
+await testdriver.find('dropdown menu labeled "Country"');
+```
+
+<Info>TestDriver will cache found elements for improved performance on subsequent calls. Learn more about [element caching here](/v7/caching).</Info>
+
+## Debugging Found Elements
+
+After finding an element, you can inspect its properties for debugging:
+
+```javascript
+const button = await testdriver.find('submit button');
+console.log(button);
+```
+
+This outputs all element properties:
+
+```javascript
+{
+  description: 'submit button',
+  found: true,
+  x: 150,
+  y: 300,
+  coordinates: { x: 150, y: 300, centerX: 200, centerY: 320 },
+  threshold: 0.8,
+  confidence: 0.95,
+  similarity: 0.92,
+  selector: 'button[type="submit"]',
+  cache: {
+    hit: true,
+    strategy: 'pixel-diff',
+    createdAt: '2025-01-15T10:30:00Z',
+    diffPercent: 0.02,
+    imageUrl: 'https://...'
+  }
+}
+```
+
+## Working with Multiple Elements
+
+Find and interact with multiple elements:
+
+```javascript
+// Find all matching elements
+const products = await testdriver.findAll('product card');
+console.log(`Found ${products.length} products`);
+
+// Interact with each
+for (const product of products) {
+  const title = await product.find('title text');
+  console.log('Product:', title.text);
+
+  await product.find('add to cart button').click();
+}
+
+// Or find specific element
+const firstProduct = products[0];
+await firstProduct.click();
+```

package/docs/v7/making-assertions.mdx

@@ -0,0 +1,32 @@
+---
+title: "Making Assertions"
+description: "Verify application state with AI-powered assertions"
+icon: "check-double"
+---
+
+## Making Assertions
+
+Use AI-powered assertions to verify application state:
+
+```javascript
+// Verify visibility
+await testdriver.assert('login page is displayed');
+await testdriver.assert('submit button is visible');
+await testdriver.assert('loading spinner is not visible');
+
+// Verify content
+await testdriver.assert('page title is "Welcome"');
+await testdriver.assert('success message says "Account created"');
+await testdriver.assert('error message contains "Invalid email"');
+
+// Verify state
+await testdriver.assert('checkbox is checked');
+await testdriver.assert('dropdown shows "United States"');
+await testdriver.assert('button is disabled');
+
+// Verify visual appearance
+await testdriver.assert('submit button is blue');
+await testdriver.assert('form has red border');
+```
+
+<Info>Assertions are not cached and always re-evaluated to ensure accuracy.</Info>

package/docs/v7/{api/mouseDown.mdx → mouse-down.mdx}

@@ -147,15 +147,15 @@ test('resizes panel', async () => {
 
 ## Important Notes
 
-- Always pair `mouseDown()` with [`mouseUp()`](/v7/api/mouseUp) to complete the gesture
+- Always pair `mouseDown()` with [`mouseUp()`](/v7/mouse-up) to complete the gesture
 - The mouse button remains pressed until `mouseUp()` is called
-- Use [`hover()`](/v7/api/hover) to move the mouse while the button is pressed
+- Use [`hover()`](/v7/hover) to move the mouse while the button is pressed
 - For simple drag operations, consider using `ai()` with a natural language description like `"drag file to folder"`
 
 ## Related Methods
 
-- [`mouseUp()`](/v7/api/mouseUp) - Release the mouse button
-- [`hover()`](/v7/api/hover) - Move mouse to element
-- [`click()`](/v7/api/click) - Full click (mouseDown + mouseUp)
-- [`doubleClick()`](/v7/api/doubleClick) - Double-click on element
-- [`rightClick()`](/v7/api/rightClick) - Right-click for context menu
+- [`mouseUp()`](/v7/mouse-up) - Release the mouse button
+- [`hover()`](/v7/hover) - Move mouse to element
+- [`click()`](/v7/click) - Full click (mouseDown + mouseUp)
+- [`doubleClick()`](/v7/double-click) - Double-click on element
+- [`rightClick()`](/v7/right-click) - Right-click for context menu

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