testdriverai 6.2.1 → 7.0.0

package/docs/v7/api/sandbox.mdx

@@ -0,0 +1,404 @@
+---
+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>

package/docs/v7/api/scroll.mdx

@@ -0,0 +1,300 @@
+---
+title: "scroll()"
+sidebarTitle: "scroll"
+description: "Scroll pages and elements"
+icon: "arrows-up-down"
+---
+
+## Overview
+
+Scroll the page or active element in any direction using mouse wheel or keyboard.
+
+## Syntax
+
+```javascript
+await testdriver.scroll(direction, amount, method)
+```
+
+## Parameters
+
+<ParamField path="direction" type="string" default="down">
+  Direction to scroll: `'up'`, `'down'`, `'left'`, `'right'`
+</ParamField>
+
+<ParamField path="amount" type="number" default="300">
+  Amount to scroll in pixels
+</ParamField>
+
+<ParamField path="method" type="string" default="mouse">
+  Scroll method: `'mouse'` or `'keyboard'`
+</ParamField>
+
+## Returns
+
+`Promise<void>`
+
+## Examples
+
+### Basic Scrolling
+
+```javascript
+// Scroll down (default)
+await testdriver.scroll();
+
+// Scroll down 500 pixels
+await testdriver.scroll('down', 500);
+
+// Scroll up
+await testdriver.scroll('up');
+
+// Scroll up 200 pixels
+await testdriver.scroll('up', 200);
+```
+
+### Horizontal Scrolling
+
+```javascript
+// Scroll right
+await testdriver.scroll('right', 300);
+
+// Scroll left
+await testdriver.scroll('left', 300);
+```
+
+### Scroll Methods
+
+```javascript
+// Mouse wheel scroll (smooth, pixel-precise)
+await testdriver.scroll('down', 300, 'mouse');
+
+// Keyboard scroll (uses Page Down/Up, more compatible)
+await testdriver.scroll('down', 300, 'keyboard');
+```
+
+## Scroll Until Found
+
+### scrollUntilText()
+
+Scroll until specific text appears on screen.
+
+```javascript
+await testdriver.scrollUntilText(text, direction, maxDistance, textMatchMethod, method, invert)
+```
+
+**Parameters:**
+- `text` (string) - Text to find
+- `direction` (string) - Scroll direction (default: `'down'`)
+- `maxDistance` (number) - Max pixels to scroll (default: 10000)
+- `textMatchMethod` (string) - `'turbo'` or `'ai'` (default: `'turbo'`)
+- `method` (string) - `'keyboard'` or `'mouse'` (default: `'keyboard'`)
+- `invert` (boolean) - Scroll until text disappears (default: false)
+
+**Examples:**
+```javascript
+// Scroll down until "Contact Us" appears
+await testdriver.scrollUntilText('Contact Us');
+
+// Scroll up to find text
+await testdriver.scrollUntilText('Header', 'up');
+
+// Scroll until text disappears
+await testdriver.scrollUntilText('Loading...', 'down', 5000, 'turbo', 'keyboard', true);
+
+// Use AI matching for fuzzy text
+await testdriver.scrollUntilText('footer content', 'down', 10000, 'ai');
+```
+
+### scrollUntilImage()
+
+Scroll until a visual element appears.
+
+```javascript
+await testdriver.scrollUntilImage(description, direction, maxDistance, method, path, invert)
+```
+
+**Parameters:**
+- `description` (string) - Description of the image/element
+- `direction` (string) - Scroll direction (default: `'down'`)
+- `maxDistance` (number) - Max pixels to scroll (default: 10000)
+- `method` (string) - `'keyboard'` or `'mouse'` (default: `'keyboard'`)
+- `path` (string | null) - Path to image template (optional)
+- `invert` (boolean) - Scroll until image disappears (default: false)
+
+**Examples:**
+```javascript
+// Scroll until visual element appears
+await testdriver.scrollUntilImage('red subscribe button');
+
+// Scroll using image template
+await testdriver.scrollUntilImage('', 'down', 10000, 'keyboard', './footer-logo.png');
+
+// Scroll until image disappears
+await testdriver.scrollUntilImage('loading spinner', 'down', 5000, 'keyboard', null, true);
+```
+
+## Best Practices
+
+<Check>
+  **Choose the right scroll method**
+  
+  ```javascript
+  // For web pages, mouse scroll is usually smoother
+  await testdriver.scroll('down', 300, 'mouse');
+  
+  // For desktop apps or when mouse doesn't work
+  await testdriver.scroll('down', 300, 'keyboard');
+  ```
+</Check>
+
+<Check>
+  **Use scrollUntil for dynamic content**
+  
+  ```javascript
+  // Instead of guessing scroll amount
+  await testdriver.scrollUntilText('Load More button');
+  
+  const loadMoreBtn = await testdriver.find('Load More button');
+  await loadMoreBtn.click();
+  ```
+</Check>
+
+<Check>
+  **Set reasonable max distance**
+  
+  ```javascript
+  // Avoid infinite scrolling
+  await testdriver.scrollUntilText('Footer', 'down', 5000); // Max 5000px
+  ```
+</Check>
+
+<Warning>
+  **Keyboard scroll uses Page Down/Up**
+  
+  Keyboard scrolling typically moves by one "page" at a time, which may be more than the specified pixel amount. It's more compatible but less precise than mouse scrolling.
+</Warning>
+
+## Use Cases
+
+<AccordionGroup>
+  <Accordion title="Navigate to Footer">
+    ```javascript
+    // Scroll to bottom of page
+    await testdriver.scrollUntilText('Contact Us');
+    
+    const contactLink = await testdriver.find('Contact Us link');
+    await contactLink.click();
+    ```
+  </Accordion>
+  
+  <Accordion title="Load More Results">
+    ```javascript
+    // Scroll to load more button
+    await testdriver.scrollUntilText('Load More');
+    
+    const loadBtn = await testdriver.find('Load More button');
+    await loadBtn.click();
+    
+    await new Promise(r => setTimeout(r, 2000));
+    ```
+  </Accordion>
+  
+  <Accordion title="Find Element in Long List">
+    ```javascript
+    // Scroll through list to find item
+    await testdriver.scrollUntilText('Product #42');
+    
+    const product = await testdriver.find('Product #42');
+    await product.click();
+    ```
+  </Accordion>
+  
+  <Accordion title="Infinite Scroll">
+    ```javascript
+    // Scroll multiple times for infinite scroll
+    for (let i = 0; i < 5; i++) {
+      await testdriver.scroll('down', 500);
+      await new Promise(r => setTimeout(r, 1000)); // Wait for load
+    }
+    ```
+  </Accordion>
+  
+  <Accordion title="Horizontal Gallery">
+    ```javascript
+    // Navigate horizontal carousel
+    await testdriver.scroll('right', 300);
+    await new Promise(r => setTimeout(r, 500));
+    
+    const nextImage = await testdriver.find('next image in carousel');
+    await nextImage.click();
+    ```
+  </Accordion>
+</AccordionGroup>
+
+## Complete Example
+
+```javascript
+import { beforeAll, afterAll, describe, it } from 'vitest';
+import TestDriver from 'testdriverai';
+
+describe('Scrolling', () => {
+  let testdriver;
+
+  beforeAll(async () => {
+    client = new TestDriver(process.env.TD_API_KEY);
+    await testdriver.auth();
+    await testdriver.connect({ newSandbox: true });
+  });
+
+  afterAll(async () => {
+    await testdriver.disconnect();
+  });
+
+  it('should scroll to find elements', async () => {
+    await testdriver.focusApplication('Google Chrome');
+    
+    // Scroll to footer
+    await testdriver.scrollUntilText('Contact Information');
+    
+    // Click footer link
+    const privacyLink = await testdriver.find('Privacy Policy link');
+    await privacyLink.click();
+    
+    await testdriver.assert('privacy policy page is displayed');
+  });
+
+  it('should handle infinite scroll', async () => {
+    await testdriver.focusApplication('Google Chrome');
+    
+    // Scroll multiple times to load content
+    for (let i = 0; i < 3; i++) {
+      await testdriver.scroll('down', 500);
+      await new Promise(r => setTimeout(r, 1500)); // Wait for load
+    }
+    
+    // Verify content loaded
+    await testdriver.assert('more than 10 items are visible');
+  });
+
+  it('should scroll until loading completes', async () => {
+    // Scroll until loading spinner disappears
+    await testdriver.scrollUntilImage(
+      'loading spinner', 
+      'down', 
+      5000, 
+      'keyboard', 
+      null, 
+      true // invert - wait for it to disappear
+    );
+    
+    // Now interact with loaded content
+    const firstResult = await testdriver.find('first search result');
+    await firstResult.click();
+  });
+});
+```
+
+## Related Methods
+
+- [`find()`](/v7/api/find) - Locate elements after scrolling
+- [`pressKeys()`](/v7/api/pressKeys) - Use Page Down/Up keys
+- [`wait()`](/v7/api/wait) - Wait after scrolling