testdriverai 7.2.9 → 7.2.11

package/docs/v7/{features/coverage.mdx → _drafts/powerful.mdx}

@@ -1,100 +1,11 @@
 ---
-title: "Selectorless Coverage"
+title: "Common Patterns"
 description: "Test everything from desktop apps to chatbots to video content"
 icon: "radar"
 ---
 
 TestDriver provides unmatched testing coverage across platforms, applications, and content types. From desktop applications to AI chatbots, from PDFs to videos, TestDriver can test it all.
 
-## Application Types
-
-### Desktop Applications
-
-Test native desktop applications on Windows, macOS, and Linux with the same simple API:
-
-```javascript
-import { test } from 'vitest';
-import { desktop } from 'testdriverai/presets';
-
-test('desktop app with file operations', async (context) => {
-  const { testdriver } = await desktop(context, {
-    appPath: '/Applications/MyApp.app',
-    os: 'mac'
-  });
-
-  await testdriver.find('File menu').click();
-  await testdriver.find('Open').click();
-  await testdriver.find('Documents folder').doubleClick();
-  await testdriver.find('test.txt').click();
-  await testdriver.find('Open button').click();
-  await testdriver.assert('test.txt is displayed in the editor');
-});
-```
-
-<Card title="Desktop Preset" icon="desktop" href="/v7/presets/desktop">
-  Complete guide to testing desktop applications
-</Card>
-
-### VS Code Extensions
-
-Test IDE extensions with full access to the VS Code environment:
-
-```javascript
-import { test } from 'vitest';
-import { vscode } from 'testdriverai/presets';
-
-test('vscode extension with settings', async (context) => {
-  const { testdriver } = await vscode(context, {
-    workspace: '/tmp/test-project',
-    extensions: ['your-extension-id']
-  });
-
-  // Open settings
-  await testdriver.pressKeys(['cmd', ',']);
-  await testdriver.find('search settings input').type('your.extension.setting');
-  await testdriver.find('Enable feature checkbox').click();
-  
-  // Verify extension behavior
-  await testdriver.pressKeys(['cmd', 'shift', 'p']);
-  await testdriver.type('Your Extension Command');
-  await testdriver.pressKeys(['enter']);
-  await testdriver.assert('Extension panel is visible');
-});
-```
-
-<Card title="VS Code Preset" icon="code" href="/v7/presets/vscode">
-  Complete guide to testing VS Code extensions
-</Card>
-
-### Chrome Extensions
-
-Test browser extensions in their natural environment with access to popups, content scripts, and background pages:
-
-```javascript
-import { test } from 'vitest';
-import { chromeExtension } from 'testdriverai/presets';
-
-test('chrome extension functionality', async (context) => {
-  const { testdriver } = await chromeExtension(context, {
-    extensionPath: './my-extension',
-    url: 'https://example.com'
-  });
-
-  // Test extension popup
-  await testdriver.find('extension icon').click();
-  await testdriver.find('Enable feature toggle').click();
-  await testdriver.assert('Feature enabled message appears');
-
-  // Test content script injection
-  await testdriver.assert('Extension content is visible on page');
-});
-```
-
-<Card title="Chrome Extension Preset" icon="puzzle-piece" href="/v7/presets/chrome-extension">
-  Complete guide to testing Chrome extensions
-</Card>
-
-## Advanced Use Cases
 
 ### AI Chatbots
 

package/docs/v7/{features → _drafts}/scalable.mdx

@@ -344,13 +344,35 @@ TestDriver integrates seamlessly with all major CI/CD platforms:
 
 ## JUnit Reports
 
-Generate JUnit XML reports for test result aggregation:
+Generate JUnit XML reports for test result aggregation and CI/CD integration.
+
+### Basic Setup
+
+Configure Vitest to output JUnit reports by adding a reporter to your config:
+
+```javascript vitest.config.mjs
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    testTimeout: 120000,
+    hookTimeout: 120000,
+    reporters: ['default', 'junit'],
+    outputFile: {
+      junit: 'test-report.junit.xml'
+    }
+  },
+});
+```
+
+Or run from the command line:
 
 ```bash
-# Generate JUnit report
 npx vitest run --reporter=junit --outputFile=test-results.xml
 ```
 
+This generates a standard JUnit XML report:
+
 ```xml test-results.xml
 <?xml version="1.0" encoding="UTF-8"?>
 <testsuites name="vitest tests" tests="12" failures="0" errors="0" time="125.3">
@@ -359,12 +381,112 @@ npx vitest run --reporter=junit --outputFile=test-results.xml
     <testcase name="invalid credentials show error" time="9.8" />
     <testcase name="password reset works" time="9.0" />
   </testsuite>
-  <!-- More test suites -->
 </testsuites>
 ```
 
+### GitHub Actions PR Comments
+
+Use JUnit reports to automatically post test results as comments on pull requests. This provides immediate visibility into test failures without leaving GitHub.
+
+```yaml .github/workflows/test.yml
+name: E2E Tests
+
+on:
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+  pull-requests: write
+  checks: write
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      
+      - name: Install dependencies
+        run: npm ci
+      
+      - name: Run tests
+        run: npx vitest run
+        env:
+          TD_API_KEY: ${{ secrets.TD_API_KEY }}
+
+      - name: Publish Test Results
+        uses: EnricoMi/publish-unit-test-result-action@v2
+        if: always()
+        with:
+          files: test-report.junit.xml
+          comment_mode: always
+          check_name: Test Results
+```
+
+<Note>
+  The `if: always()` ensures test results are published even when tests fail, so you always see what went wrong.
+</Note>
+
+The [publish-unit-test-result-action](https://github.com/EnricoMi/publish-unit-test-result-action) creates:
+
+- **PR comments** with a summary table of passed/failed tests
+- **Check runs** visible in the GitHub PR checks tab
+- **Annotations** highlighting failed tests in the diff view
+
+### Multi-Platform Testing with JUnit
+
+When testing across multiple platforms, use separate check names to distinguish results:
+
+```yaml .github/workflows/test.yml
+jobs:
+  test-linux:
+    runs-on: ubuntu-latest
+    steps:
+      # ... setup steps ...
+      
+      - name: Run Linux tests
+        run: npx vitest run
+        env:
+          TD_API_KEY: ${{ secrets.TD_API_KEY }}
+          TD_OS: linux
+
+      - name: Publish Test Results
+        uses: EnricoMi/publish-unit-test-result-action@v2
+        if: always()
+        with:
+          files: test-report.junit.xml
+          comment_mode: always
+          check_name: Test Results (Linux)
+
+  test-windows:
+    runs-on: ubuntu-latest
+    steps:
+      # ... setup steps ...
+      
+      - name: Run Windows tests
+        run: npx vitest run
+        env:
+          TD_API_KEY: ${{ secrets.TD_API_KEY }}
+          TD_OS: windows
+
+      - name: Publish Test Results
+        uses: EnricoMi/publish-unit-test-result-action@v2
+        if: always()
+        with:
+          files: test-report.junit.xml
+          comment_mode: always
+          check_name: Test Results (Windows)
+```
+
 <Check>
-  JUnit reports integrate with Jenkins, Azure DevOps, TeamCity, and other CI platforms for test result visualization.
+  JUnit reports integrate with Jenkins, Azure DevOps, TeamCity, GitLab, and other CI platforms for test result visualization.
 </Check>
 
 ## Familiar Test Syntax

package/docs/v7/_drafts/screenshot.mdx

@@ -0,0 +1,155 @@
+---
+title: "screenshot()"
+sidebarTitle: "screenshot"
+description: "Capture a screenshot of the current screen"
+icon: "camera"
+---
+
+## Overview
+
+Capture a screenshot of the current sandbox screen. Returns a base64 encoded PNG, or saves directly to a file and returns the filepath.
+
+## Syntax
+
+```javascript
+// Options object (recommended)
+await testdriver.screenshot(options)
+
+// Legacy positional arguments
+await testdriver.screenshot(scale, silent, mouse)
+```
+
+## Parameters
+
+<ParamField path="options" type="object">
+  Options object for screenshot capture
+</ParamField>
+
+<ParamField path="options.scale" type="number" default="1">
+  Scale factor for the screenshot (1 = original size, 0.5 = half size, etc.)
+</ParamField>
+
+<ParamField path="options.silent" type="boolean" default="false">
+  Whether to suppress logging output
+</ParamField>
+
+<ParamField path="options.mouse" type="boolean" default="false">
+  Whether to include the mouse cursor in the screenshot
+</ParamField>
+
+<ParamField path="options.path" type="string">
+  File path to save the screenshot. If provided, the screenshot is saved to this file and the filepath is returned instead of base64 data. Directories are created automatically if they don't exist.
+</ParamField>
+
+## Returns
+
+`Promise<string>` - Base64 encoded PNG screenshot, or the filepath if `options.path` was provided.
+
+## Examples
+
+### Basic Screenshot (Base64)
+
+```javascript
+// Capture a screenshot and get base64 data
+const screenshot = await testdriver.screenshot();
+
+// Write to file manually
+import fs from 'fs';
+fs.writeFileSync('screenshot.png', Buffer.from(screenshot, 'base64'));
+```
+
+### Save Directly to File
+
+```javascript
+// Save screenshot directly to a file (returns filepath)
+const filepath = await testdriver.screenshot({ path: './screenshots/test.png' });
+console.log(`Screenshot saved to: ${filepath}`);
+```
+
+### With Mouse Cursor
+
+```javascript
+// Include mouse cursor in screenshot
+const screenshot = await testdriver.screenshot({ mouse: true });
+
+// Or save to file with mouse cursor
+const filepath = await testdriver.screenshot({ 
+  path: './debug/with-cursor.png',
+  mouse: true 
+});
+```
+
+### Scaled Screenshot
+
+```javascript
+// Capture at half size (useful for reducing file size)
+const screenshot = await testdriver.screenshot({ scale: 0.5 });
+
+// Capture at double size
+const filepath = await testdriver.screenshot({ 
+  path: './hires.png',
+  scale: 2 
+});
+```
+
+### Silent Mode
+
+```javascript
+// Capture without logging output
+const screenshot = await testdriver.screenshot({ silent: true });
+```
+
+### Legacy Usage
+
+```javascript
+// Legacy positional arguments still work
+const screenshot = await testdriver.screenshot(1, false, true);
+// Equivalent to: screenshot({ scale: 1, silent: false, mouse: true })
+```
+
+## Use Cases
+
+### Debugging Test Failures
+
+```javascript
+it('should complete checkout', async (context) => {
+  const testdriver = TestDriver(context, { newSandbox: true });
+  await testdriver.provision.chrome({ url: 'https://shop.example.com' });
+
+  try {
+    await testdriver.find('Checkout button').click();
+    await testdriver.assert('Order confirmation is visible');
+  } catch (error) {
+    // Save screenshot on failure for debugging
+    await testdriver.screenshot({ path: './failures/checkout-failed.png' });
+    throw error;
+  }
+});
+```
+
+### Visual Documentation
+
+```javascript
+// Capture screenshots at each step for documentation
+await testdriver.screenshot({ path: './docs/step1-login.png' });
+await testdriver.find('Login button').click();
+await testdriver.screenshot({ path: './docs/step2-dashboard.png' });
+```
+
+### Comparing States
+
+```javascript
+// Capture before and after states
+const before = await testdriver.screenshot();
+await testdriver.find('Toggle dark mode').click();
+const after = await testdriver.screenshot();
+
+// Both are base64 - can be compared or stored
+```
+
+## Notes
+
+- Screenshots are captured from the sandbox's virtual display
+- The base64 string does not include a data URI prefix (raw base64)
+- When using `path`, directories are created automatically if they don't exist
+- File format is always PNG regardless of the file extension used

package/docs/v7/_drafts/writing-tests.mdx

@@ -0,0 +1,25 @@
+---
+title: "Writing Tests"
+description: "Learn how to write effective TestDriver tests with natural language"
+icon: "pencil"
+---
+
+Learn how to write effective TestDriver tests. This section covers everything from generating tests with AI to making assertions.
+
+<CardGroup cols={2}>
+  <Card title="Generating Tests" icon="wand-magic-sparkles" href="./generating-tests">
+    Use AI coding agents and exploration mode to generate tests
+  </Card>
+  <Card title="Locating Elements" icon="crosshairs" href="./locating-elements">
+    Find UI elements using natural language descriptions
+  </Card>
+  <Card title="Waiting for Elements" icon="clock" href="./waiting-for-elements">
+    Handle async operations and prevent flaky tests
+  </Card>
+  <Card title="Performing Actions" icon="computer-mouse" href="./performing-actions">
+    Click, type, hover, scroll and more
+  </Card>
+  <Card title="Making Assertions" icon="check-double" href="./making-assertions">
+    Verify application state with AI-powered assertions
+  </Card>
+</CardGroup>

package/docs/v7/{api/act.mdx → ai.mdx}

@@ -1,6 +1,6 @@
 ---
-title: "act()"
-sidebarTitle: "act"
+title: "ai()"
+sidebarTitle: "ai"
 description: "Execute natural language tasks using AI"
 icon: "wand-magic-sparkles"
 tag: beta
@@ -8,12 +8,12 @@ tag: beta
 
 ## Overview
 
-The `act()` method allows you to execute complex tasks using natural language descriptions. TestDriver's AI will figure out the steps needed to accomplish the task.
+The `ai()` method allows you to execute complex tasks using natural language descriptions. TestDriver's AI will figure out the steps needed to accomplish the task.
 
 ## Syntax
 
 ```javascript
-await testdriver.act(task, options)
+await testdriver.ai(task, options)
 ```
 
 ## Parameters
@@ -42,20 +42,20 @@ await testdriver.act(task, options)
 
 ```javascript
 // Simple task execution
-await testdriver.act('Click the submit button');
+await testdriver.ai('Click the submit button');
 
 // Complex multi-step task
-await testdriver.act('Fill out the contact form and submit it');
+await testdriver.ai('Fill out the contact form and submit it');
 
 // Navigation task
-await testdriver.act('Go to the settings page and enable notifications');
+await testdriver.ai('Go to the settings page and enable notifications');
 ```
 
 ### With Validation
 
 ```javascript
 // AI will verify the task completed successfully
-const result = await testdriver.act('Complete the checkout process', { 
+const result = await testdriver.ai('Complete the checkout process', { 
   validateAndLoop: true 
 });
 
@@ -66,10 +66,10 @@ console.log('Task result:', result);
 
 ```javascript
 // The AI will break down complex tasks
-await testdriver.act('Search for "laptop", add the first result to cart, and proceed to checkout');
+await testdriver.ai('Search for "laptop", add the first result to cart, and proceed to checkout');
 
 // UI exploration
-await testdriver.act('Find and click all menu items to explore the application');
+await testdriver.ai('Find and click all menu items to explore the application');
 ```
 
 ## Use Cases
@@ -79,8 +79,8 @@ await testdriver.act('Find and click all menu items to explore the application')
     Use AI to explore unfamiliar applications:
     
     ```javascript
-    await testdriver.act('Explore the main navigation menu');
-    await testdriver.act('Try to find the user profile settings');
+    await testdriver.ai('Explore the main navigation menu');
+    await testdriver.ai('Try to find the user profile settings');
     ```
   </Accordion>
   
@@ -88,8 +88,8 @@ await testdriver.act('Find and click all menu items to explore the application')
     Let AI handle multi-step processes:
     
     ```javascript
-    await testdriver.act('Complete the multi-step registration form');
-    await testdriver.act('Configure all the advanced settings to default values');
+    await testdriver.ai('Complete the multi-step registration form');
+    await testdriver.ai('Configure all the advanced settings to default values');
     ```
   </Accordion>
   
@@ -97,8 +97,8 @@ await testdriver.act('Find and click all menu items to explore the application')
     When exact element locations aren't critical:
     
     ```javascript
-    await testdriver.act('Close any popup dialogs');
-    await testdriver.act('Accept the cookie consent if it appears');
+    await testdriver.ai('Close any popup dialogs');
+    await testdriver.ai('Accept the cookie consent if it appears');
     ```
   </Accordion>
 </AccordionGroup>
@@ -110,13 +110,13 @@ await testdriver.act('Find and click all menu items to explore the application')
   
   ```javascript
   // ✅ Good
-  await testdriver.act('Add the first product to the shopping cart');
+  await testdriver.ai('Add the first product to the shopping cart');
   
   // ❌ Too vague
-  await testdriver.act('do something');
+  await testdriver.ai('do something');
   
   // ❌ Too specific (defeats the purpose)
-  await testdriver.act('click at coordinates 500, 300');
+  await testdriver.ai('click at coordinates 500, 300');
   ```
 </Check>
 
@@ -125,7 +125,7 @@ await testdriver.act('Find and click all menu items to explore the application')
   
   ```javascript
   // Use AI for setup
-  await testdriver.act('Navigate to the login page');
+  await testdriver.ai('Navigate to the login page');
   
   // Use explicit methods for critical steps
   const usernameField = await testdriver.find('username input');
@@ -142,7 +142,7 @@ await testdriver.act('Find and click all menu items to explore the application')
 
 ## When to Use AI vs Explicit Methods
 
-### Use `act()` when:
+### Use `ai()` when:
 - Exploring unfamiliar applications
 - Handling optional UI elements (popups, cookies, etc.)
 - Prototyping tests quickly
@@ -178,8 +178,8 @@ describe('E-commerce Flow with AI', () => {
     await testdriver.focusApplication('Google Chrome');
     
     // Use AI for navigation and exploration
-    await testdriver.act('Browse to the electronics section');
-    await testdriver.act('Find and add a laptop to the cart');
+    await testdriver.ai('Browse to the electronics section');
+    await testdriver.ai('Find and add a laptop to the cart');
     
     // Use explicit methods for critical steps
     const cartIcon = await testdriver.find('shopping cart icon');
@@ -189,7 +189,7 @@ describe('E-commerce Flow with AI', () => {
     console.log('Cart total:', total);
     
     // Use AI for checkout flow
-    await testdriver.act('Proceed to checkout and fill in shipping details', {
+    await testdriver.ai('Proceed to checkout and fill in shipping details', {
       validateAndLoop: true
     });
     
@@ -201,6 +201,6 @@ describe('E-commerce Flow with AI', () => {
 
 ## Related Methods
 
-- [`find()`](/v7/api/find) - Locate specific elements
-- [`assert()`](/v7/api/assert) - Make assertions
-- [`extract()`](/v7/api/extract) - Extract information
+- [`find()`](/v7/find) - Locate specific elements
+- [`assert()`](/v7/assert) - Make assertions
+- [`extract()`](/v7/extract) - Extract information

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

@@ -280,6 +280,6 @@ describe('Assertions', () => {
 
 ## Related Methods
 
-- [`extract()`](/v7/api/extract) - Extract information for detailed assertions
-- [`find()`](/v7/api/find) - Locate elements to verify
-- [`ai()`](/v7/api/ai) - Complex AI-driven tasks
+- [`extract()`](/v7/extract) - Extract information for detailed assertions
+- [`find()`](/v7/find) - Locate elements to verify
+- [`ai()`](/v7/ai) - Complex AI-driven tasks