testdriverai 7.2.10 → 7.2.11

package/docs/docs.json

@@ -13,6 +13,91 @@
   "favicon": "/images/template/icon.png",
   "navigation": {
         "versions": [
+          {
+            "version": "v7",
+            "groups": [
+              {
+                "group": "Overview",
+                "pages": [
+                  "/v7/what-is-testdriver",
+                  "/v7/quickstart",
+                  "/v7/examples",
+                  {
+                    "group": "Plans & Pricing",
+                    "icon": "server",
+                    "pages": [
+                      "/v7/cloud",
+                      "/v7/self-hosted",
+                      "/v7/enterprise"
+                    ]
+                  }
+                ]
+              },
+              {
+                "group": "Creating Tests",
+                "pages": [
+                  "/v7/generating-tests",
+                  "/v7/device-config",
+                  "/v7/locating-elements",
+                  "/v7/waiting-for-elements",
+                  "/v7/performing-actions",
+                  "/v7/making-assertions"
+                ]
+              },
+              {
+                "group": "Running Tests",
+                "pages": [
+                  "/v7/running-tests",
+                  "/v7/caching",
+                  "/v7/ci-cd"
+                ]
+              },
+              {
+                "group": "Scaling",
+                "pages": [
+                  "/v7/variables",
+                  "/v7/secrets",
+                  "/v7/reusable-code",
+                  {
+                    "group": "Self-Hosting Setup",
+                    "icon": "server",
+                    "pages": [
+                      "/v7/aws-setup"
+                    ]
+                  }
+                ]
+              },
+              {
+                "group": "Actions",
+                "pages": [
+                  "/v7/ai",
+                  "/v7/assert",
+                  "/v7/click",
+                  "/v7/double-click",
+                  "/v7/exec",
+                  "/v7/find",
+                  "/v7/focus-application",
+                  "/v7/hover",
+                  "/v7/mouse-down",
+                  "/v7/mouse-up",
+                  "/v7/press-keys",
+                  "/v7/right-click",
+                  "/v7/type",
+                  "/v7/scroll"
+                ]
+              },
+              {
+                "group": "SDK",
+                "pages": 
+                  [
+                      "/v7/elements",
+                      "/v7/client",
+                      "/v7/dashcam"
+                    
+                ]
+              }
+            ]
+          },
           {
             "version": "v6",
             "groups": [
@@ -186,98 +271,6 @@
                 ]
               }
             ]
-          },
-          {
-            "version": "v7",
-            "groups": [
-              {
-                "group": "Overview",
-                "pages": [
-                  "/v7/what-is-testdriver",
-                  "/v7/quickstart",
-                  "/v7/examples",
-                  {
-                    "group": "Plans & Pricing",
-                    "icon": "server",
-                    "pages": [
-                      "/v7/cloud",
-                      {
-                        "group": "Self-Hosted",
-                        "icon": "server",
-                        "pages": [
-                          "/v7/self-hosted",
-                          "/v7/aws-setup"
-                        ]
-                      },
-                      "/v7/enterprise"
-                    ]
-                  }
-                ]
-              },
-              {
-                "group": "Creating Tests",
-                "pages": [
-                  "/v7/generating-tests",
-                  "/v7/locating-elements",
-                  "/v7/waiting-for-elements",
-                  "/v7/performing-actions",
-                  "/v7/making-assertions"
-                ]
-              },
-              {
-                "group": "Running Tests",
-                "pages": [
-                  "/v7/running-tests",
-                  "/v7/caching",
-                  "/v7/ci-cd"
-                ]
-              },
-              {
-                "group": "Scaling",
-                "pages": [
-                  "/v7/variables",
-                  "/v7/secrets",
-                  "/v7/reusable-code",
-                  "/v7/customizing-devices"
-                ]
-              },
-              {
-                "group": "Reference",
-                "icon": "book",
-                "pages": [
-                  {
-                    "group": "Actions",
-                    "icon": "bolt",
-                    "pages": [
-                      "/v7/ai",
-                      "/v7/assert",
-                      "/v7/click",
-                      "/v7/double-click",
-                      "/v7/exec",
-                      "/v7/find",
-                      "/v7/focus-application",
-                      "/v7/hover",
-                      "/v7/mouse-down",
-                      "/v7/mouse-up",
-                      "/v7/press-keys",
-                      "/v7/right-click",
-                      "/v7/type",
-                      "/v7/scroll"
-                    ]
-                  },
-                  {
-                    "group": "Client SDK",
-                    "icon": "code",
-                    "pages": [
-                      "/v7/client",
-                      "/v7/elements",
-                      "/v7/sandbox",
-                      "/v7/dashcam"
-                    ]
-                  }
-                ]
-              }
-            ]
           }
         ]
       },

package/docs/v7/aws-setup.mdx

@@ -1,6 +1,6 @@
 ---
 title: "AWS Setup Guide"
-sidebarTitle: "AWS Setup"
+sidebarTitle: "AWS Setup Guide"
 description: "Deploy TestDriver on your AWS infrastructure using CloudFormation"
 icon: "aws"
 ---

package/docs/v7/dashcam.mdx

@@ -417,81 +417,3 @@ On Linux/Mac, Dashcam uses shell commands:
 // Unix-specific paths
 await dashcam.addFileLog('/tmp/testdriver.log', 'TestDriver Log');
 ```
-
-## Troubleshooting
-
-### No Replay URL Returned
-
-If `stop()` returns `null`:
-
-1. Check that recording was started with `start()`
-2. Verify authentication succeeded
-3. Ensure dashcam CLI is installed in the environment
-4. Check console output for error messages
-
-### Recording Not Starting
-
-If recording doesn't start:
-
-1. Verify API key is correct
-2. Check `auth()` completed successfully
-3. Ensure dashcam CLI is installed globally
-4. Check `isRecording()` to verify state
-
-### Logs Not Appearing
-
-If logs aren't visible in replay:
-
-1. Add logs before calling `start()`
-2. Verify log file paths are correct
-3. Ensure log files exist and are accessible
-4. Check file permissions
-
-## Best Practices
-
-<AccordionGroup>
-  <Accordion title="Always authenticate before starting">
-    ```javascript
-    await dashcam.auth();
-    await dashcam.start();
-    ```
-  </Accordion>
-  
-  <Accordion title="Add logs before starting recording">
-    ```javascript
-    await dashcam.addFileLog('/tmp/app.log', 'App Log');
-    await dashcam.start();
-    ```
-  </Accordion>
-  
-  <Accordion title="Always stop recording">
-    Use try/finally to ensure recording stops:
-    
-    ```javascript
-    try {
-      await dashcam.start();
-      // Test code
-    } finally {
-      await dashcam.stop();
-    }
-    ```
-  </Accordion>
-  
-  <Accordion title="Check for replay URL">
-    ```javascript
-    const url = await dashcam.stop();
-    if (url) {
-      console.log('Replay:', url);
-    } else {
-      console.warn('No replay URL available');
-    }
-    ```
-  </Accordion>
-</AccordionGroup>
-
-## See Also
-
-- [Chrome Preset](/v7/presets/chrome) - Automatic Dashcam setup for web apps
-- [VS Code Extensions](/v7/presets/vscode) - Dashcam with VS Code testing
-- [Desktop Apps](/v7/presets/electron) - Dashcam with Electron apps
-- [Lifecycle Helpers](/v7/guides/lifecycle) - Prerun/postrun with Dashcam

package/docs/v7/elements.mdx

@@ -496,47 +496,6 @@ const elementData = JSON.stringify(element);
   Use JSON serialization when you need to log element data or when debugging why an element wasn't found. The serialized output excludes large binary data (screenshots) and circular references.
 </Tip>
 
-## Polling for Elements
-
-Use polling to wait for elements that may not be immediately visible:
-
-```javascript
-// Poll until element appears
-let loginButton;
-const maxAttempts = 30;
-
-for (let i = 0; i < maxAttempts; i++) {
-  loginButton = await testdriver.find('login button');
-  if (loginButton.found()) break;
-  await new Promise(resolve => setTimeout(resolve, 1000));
-}
-
-if (loginButton.found()) {
-  await loginButton.click();
-} else {
-  throw new Error('Login button never appeared');
-}
-```
-
-**Helper function for polling:**
-```javascript
-async function waitForElement(testdriver, description, timeout = 30000) {
-  const startTime = Date.now();
-  
-  while (Date.now() - startTime < timeout) {
-    const element = await testdriver.find(description);
-    if (element.found()) return element;
-    await new Promise(resolve => setTimeout(resolve, 1000));
-  }
-  
-  throw new Error(`Element "${description}" not found after ${timeout}ms`);
-}
-
-// Usage
-const button = await waitForElement(testdriver, 'submit button', 10000);
-await button.click();
-```
-
 ## Examples
 
 ### Basic Element Interaction
@@ -627,19 +586,7 @@ if (notification.found()) {
     await element.click();
     ```
   </Accordion>
-  
-  <Accordion title="Use polling for dynamic content">
-    Don't assume elements are immediately visible:
-    
-    ```javascript
-    let element;
-    for (let i = 0; i < 30; i++) {
-      element = await testdriver.find('loading complete message');
-      if (element.found()) break;
-      await new Promise(resolve => setTimeout(resolve, 1000));
-    }
-    ```
-  </Accordion>
+
   
   <Accordion title="Reuse element references when possible">
     If you need to interact with the same element multiple times, reuse the reference:

package/docs/v7/enterprise.mdx

@@ -114,22 +114,3 @@ Enterprise deployments support:
 >
   Discuss your requirements with our team and get a custom proposal for your Enterprise deployment.
 </Card>
-
-## Related
-
-<CardGroup cols={2}>
-  <Card
-    title="Cloud"
-    icon="cloud"
-    href="/v7/cloud"
-  >
-    Zero-setup testing with device-seconds billing
-  </Card>
-  <Card
-    title="Self-Hosted"
-    icon="server"
-    href="/v7/self-hosted"
-  >
-    Flat-rate licensing with your AWS infrastructure
-  </Card>
-</CardGroup>

package/docs/v7/generating-tests.mdx

@@ -6,9 +6,13 @@ icon: "wand-magic-sparkles"
 
 ## Instructions for Coding Agents
 
-We recommend starting with [our quickstart](./quickstart) then supplying your coding agent with our [agents.md](https://github.com/testdriverai/testdriverai/agents.md) file.
+We recommend starting with [our quickstart](./quickstart) then supplying your coding agent with our agents.md file.
 
-Then, you can prompt your coding agent to generate tests:
+<Card title="Agents.md" icon="link" arrow="true" horizontal href="https://github.com/testdriverai/testdriverai/blob/main/agents.md?plain=1">
+  Copy the current version of agents.md to provide your coding agent with up-to-date instructions on how to generate TestDriver tests.
+</Card>
+
+Then, you can prompt your coding agent to generate tests. Here is an example prompt:
 
 ```md
 Make me a TestDriver test that does the following steps:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testdriverai",
-  "version": "7.2.10",
+  "version": "7.2.11",
   "description": "Next generation autonomous AI agent for end-to-end testing of web & desktop",
   "main": "sdk.js",
   "exports": {

package/docs/v7/sandbox.mdx

@@ -1,404 +0,0 @@
----
-title: "Sandbox Management"
-sidebarTitle: "Sandbox"
-description: "Execute scripts and manage the sandbox environment"
-icon: "server"
----
-
-## Overview
-
-The sandbox is a virtual machine where your tests run. You can execute shell commands, JavaScript, and manage applications within the sandbox environment.
-
-## Code Execution
-
-### exec()
-
-Execute code or shell commands in the sandbox.
-
-```javascript
-await testdriver.exec(language, code, timeout, silent)
-```
-
-**Parameters:**
-- `language` (string) - Language to execute: `'js'` (JavaScript) or `'pwsh'` (PowerShell)
-- `code` (string) - Code or command to execute
-- `timeout` (number) - Timeout in milliseconds
-- `silent` (boolean, optional) - Suppress output if `true`
-
-**Returns:** `Promise<string>` - Command output
-
-### JavaScript Execution
-
-Execute JavaScript code in the browser context (Windows sandbox only).
-
-```javascript
-// Execute JavaScript in the browser
-const result = await testdriver.exec('js', 'document.title', 5000);
-console.log('Page title:', result);
-
-// Manipulate the DOM
-await testdriver.exec('js', `
-  document.querySelector('#username').value = 'testuser';
-`, 5000);
-
-// Return data from the page
-const elementText = await testdriver.exec('js', `
-  document.querySelector('.message').textContent
-`, 5000);
-```
-
-### PowerShell Execution
-
-Execute PowerShell commands in the Windows sandbox.
-
-```javascript
-// Run a simple command
-const output = await testdriver.exec('pwsh', 'Get-Process chrome', 5000);
-console.log('Chrome processes:', output);
-
-// Install software
-await testdriver.exec('pwsh', 'npm install -g dashcam@beta', 10000);
-
-// Start an application
-await testdriver.exec('pwsh', `
-  Start-Process "C:/Program Files/Google/Chrome/Application/chrome.exe" -ArgumentList "--start-maximized", "https://example.com"
-`, 10000);
-
-// File operations
-await testdriver.exec('pwsh', 'New-Item -Path "C:\\test.txt" -ItemType File', 5000);
-```
-
-### Silent Execution
-
-Use the `silent` parameter to suppress output for background operations:
-
-```javascript
-// Silent installation
-await testdriver.exec('pwsh', 'npm install -g some-package', 10000, true);
-
-// Start background process
-await testdriver.exec('pwsh', 'Start-Process notepad', 5000, true);
-```
-
-## Application Management
-
-### focusApplication()
-
-Bring an application window to the foreground.
-
-```javascript
-await testdriver.focusApplication(name)
-```
-
-**Parameters:**
-- `name` (string) - Application name (e.g., `'Google Chrome'`, `'Microsoft Edge'`, `'Notepad'`)
-
-**Returns:** `Promise<string>` - Result message
-
-**Example:**
-```javascript
-// Focus Chrome browser
-await testdriver.focusApplication('Google Chrome');
-
-// Focus Edge
-await testdriver.focusApplication('Microsoft Edge');
-
-// Focus Notepad
-await testdriver.focusApplication('Notepad');
-```
-
-<Tip>
-  Call `focusApplication()` before interacting with UI elements to ensure the correct window is active.
-</Tip>
-
-## Common Sandbox Operations
-
-### Installing Software
-
-```javascript
-// Install npm package globally
-await testdriver.exec('pwsh', 'npm install -g package-name', 30000);
-
-// Install via Chocolatey (if available)
-await testdriver.exec('pwsh', 'choco install firefox -y', 60000);
-
-// Download and install
-await testdriver.exec('pwsh', `
-  Invoke-WebRequest -Uri "https://example.com/installer.exe" -OutFile "C:\\installer.exe"
-  Start-Process -FilePath "C:\\installer.exe" -ArgumentList "/S" -Wait
-`, 120000);
-```
-
-### File Operations
-
-```javascript
-// Create a file
-await testdriver.exec('pwsh', `
-  Set-Content -Path "C:\\test.txt" -Value "Hello World"
-`, 5000);
-
-// Read a file
-const content = await testdriver.exec('pwsh', 'Get-Content -Path "C:\\test.txt"', 5000);
-
-// Copy files
-await testdriver.exec('pwsh', 'Copy-Item -Path "C:\\source.txt" -Destination "C:\\dest.txt"', 5000);
-
-// Delete files
-await testdriver.exec('pwsh', 'Remove-Item -Path "C:\\test.txt"', 5000);
-```
-
-### Environment Variables
-
-```javascript
-// Set environment variable
-await testdriver.exec('pwsh', '$env:MY_VAR = "value"', 5000);
-
-// Get environment variable
-const value = await testdriver.exec('pwsh', '$env:MY_VAR', 5000);
-
-// Set persistent environment variable
-await testdriver.exec('pwsh', '[Environment]::SetEnvironmentVariable("MY_VAR", "value", "User")', 5000);
-```
-
-### Network Operations
-
-```javascript
-// Test connectivity
-const pingResult = await testdriver.exec('pwsh', 'Test-NetConnection google.com', 10000);
-
-// Download file
-await testdriver.exec('pwsh', `
-  Invoke-WebRequest -Uri "https://example.com/file.zip" -OutFile "C:\\Downloads\\file.zip"
-`, 30000);
-
-// Check if port is open
-const portCheck = await testdriver.exec('pwsh', 'Test-NetConnection -ComputerName localhost -Port 3000', 5000);
-```
-
-### Process Management
-
-```javascript
-// List running processes
-const processes = await testdriver.exec('pwsh', 'Get-Process', 5000);
-
-// Kill a process
-await testdriver.exec('pwsh', 'Stop-Process -Name "chrome" -Force', 5000);
-
-// Start a process and wait for it
-await testdriver.exec('pwsh', 'Start-Process notepad -Wait', 30000);
-
-// Start process with arguments
-await testdriver.exec('pwsh', `
-  Start-Process "chrome.exe" -ArgumentList "--incognito", "https://example.com"
-`, 5000);
-```
-
-## Browser Automation with JavaScript
-
-### DOM Manipulation
-
-```javascript
-// Click an element
-await testdriver.exec('js', `
-  document.querySelector('#submit-button').click();
-`, 5000);
-
-// Fill a form
-await testdriver.exec('js', `
-  document.querySelector('#username').value = 'user@example.com';
-  document.querySelector('#password').value = 'secret';
-  document.querySelector('#login-form').submit();
-`, 5000);
-
-// Scroll to element
-await testdriver.exec('js', `
-  document.querySelector('#footer').scrollIntoView();
-`, 5000);
-```
-
-### Reading Page Data
-
-```javascript
-// Get page title
-const title = await testdriver.exec('js', 'document.title', 5000);
-
-// Get all links
-const links = await testdriver.exec('js', `
-  Array.from(document.querySelectorAll('a')).map(a => a.href).join('\\n')
-`, 5000);
-
-// Check if element exists
-const exists = await testdriver.exec('js', `
-  document.querySelector('.error-message') !== null
-`, 5000);
-
-// Get element text
-const text = await testdriver.exec('js', `
-  document.querySelector('.notification').textContent
-`, 5000);
-```
-
-### Waiting for Conditions
-
-```javascript
-// Wait for element to appear (using polling)
-await testdriver.exec('js', `
-  await new Promise((resolve) => {
-    const interval = setInterval(() => {
-      if (document.querySelector('.loaded')) {
-        clearInterval(interval);
-        resolve();
-      }
-    }, 100);
-  });
-`, 30000);
-
-// Wait for page load
-await testdriver.exec('js', `
-  if (document.readyState !== 'complete') {
-    await new Promise(resolve => window.addEventListener('load', resolve));
-  }
-`, 10000);
-```
-
-## Complete Example
-
-```javascript
-import { beforeAll, afterAll, describe, it } from 'vitest';
-import TestDriver from 'testdriverai';
-
-describe('Sandbox Operations', () => {
-  let testdriver;
-
-  beforeAll(async () => {
-    client = new TestDriver(process.env.TD_API_KEY, {
-      os: 'windows',
-      resolution: '1366x768'
-    });
-    
-    await testdriver.auth();
-    await testdriver.connect({ newSandbox: true });
-  });
-
-  afterAll(async () => {
-    await testdriver.disconnect();
-  });
-
-  it('should install and use a tool', async () => {
-    // Install a tool
-    await testdriver.exec('pwsh', 'npm install -g http-server', 30000, true);
-    
-    // Create a simple HTML file
-    await testdriver.exec('pwsh', `
-      Set-Content -Path "C:\\index.html" -Value "<h1>Hello World</h1>"
-    `, 5000);
-    
-    // Start HTTP server (background process)
-    await testdriver.exec('pwsh', `
-      Start-Process pwsh -ArgumentList "-Command", "http-server C:\\ -p 8080"
-    `, 5000, true);
-    
-    // Wait for server to start
-    await new Promise(resolve => setTimeout(resolve, 3000));
-    
-    // Launch browser to view the page
-    await testdriver.exec('pwsh', `
-      Start-Process chrome -ArgumentList "http://localhost:8080"
-    `, 5000);
-    
-    // Focus the browser
-    await testdriver.focusApplication('Google Chrome');
-    
-    // Verify the page loaded
-    const pageText = await testdriver.exec('js', 'document.body.textContent', 5000);
-    expect(pageText).toContain('Hello World');
-  });
-
-  it('should manage files and processes', async () => {
-    // Create test file
-    await testdriver.exec('pwsh', `
-      "Test content" | Out-File -FilePath "C:\\test.txt"
-    `, 5000);
-    
-    // Open file in notepad
-    await testdriver.exec('pwsh', 'Start-Process notepad C:\\test.txt', 5000);
-    
-    // Focus notepad
-    await testdriver.focusApplication('Notepad');
-    
-    // Wait a moment
-    await new Promise(resolve => setTimeout(resolve, 1000));
-    
-    // Close notepad
-    await testdriver.exec('pwsh', 'Stop-Process -Name notepad -Force', 5000);
-  });
-});
-```
-
-## Best Practices
-
-<AccordionGroup>
-  <Accordion title="Use appropriate timeouts">
-    Set realistic timeouts based on the operation:
-    
-    ```javascript
-    // Quick operations: 5000ms
-    await testdriver.exec('js', 'document.title', 5000);
-    
-    // Installations: 30000-60000ms
-    await testdriver.exec('pwsh', 'npm install -g package', 30000);
-    
-    // Downloads or complex operations: 60000-120000ms
-    await testdriver.exec('pwsh', 'Install-Module Something', 120000);
-    ```
-  </Accordion>
-  
-  <Accordion title="Handle errors gracefully">
-    Wrap exec calls in try-catch for better error handling:
-    
-    ```javascript
-    try {
-      await testdriver.exec('pwsh', 'Some-Command', 5000);
-    } catch (error) {
-      console.error('Command failed:', error.message);
-      // Fall back or retry
-    }
-    ```
-  </Accordion>
-  
-  <Accordion title="Use silent mode for background operations">
-    Suppress output for installation and background tasks:
-    
-    ```javascript
-    // Silent install
-    await testdriver.exec('pwsh', 'npm install -g tool', 30000, true);
-    
-    // Background process
-    await testdriver.exec('pwsh', 'Start-Process app', 5000, true);
-    ```
-  </Accordion>
-  
-  <Accordion title="Focus applications before interaction">
-    Always focus the target application before UI interactions:
-    
-    ```javascript
-    await testdriver.focusApplication('Google Chrome');
-    const button = await testdriver.find('submit button');
-    await button.click();
-    ```
-  </Accordion>
-  
-  <Accordion title="Escape strings properly in PowerShell">
-    Use proper escaping for special characters:
-    
-    ```javascript
-    // Use backticks for newlines in PowerShell strings
-    await testdriver.exec('pwsh', `
-      Write-Host "Line 1\`nLine 2"
-    `, 5000);
-    
-    // Use single quotes to avoid variable expansion
-    await testdriver.exec('pwsh', "Write-Host 'Text with $special chars'", 5000);
-    ```
-  </Accordion>
-</AccordionGroup>