testdriverai 6.2.2 → 7.1.0

package/docs/v7/api/rightClick.mdx

@@ -0,0 +1,123 @@
+---
+title: "rightClick"
+description: "Perform a right-click action to open context menus"
+icon: "bars"
+---
+
+## Overview
+
+The `rightClick()` method performs a right-click action on an element, typically used to open context menus. You can either call it on an [`Element`](/v7/core-concepts/elements) instance or use it directly with a selector.
+
+## Syntax
+
+```javascript
+// Right-click on an element
+await element.rightClick();
+
+// Right-click using a selector
+await ai.rightClick('selector');
+```
+
+## Parameters
+
+When called on an `Element`, no parameters are required.
+
+When called directly on the AI client:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `selector` | `string` | The selector describing the element to right-click |
+
+## Returns
+
+Returns a `Promise<void>` that resolves when the right-click action completes.
+
+## Examples
+
+### Right-Click to Open Context Menu
+
+```javascript
+const fileItem = await ai.find('README.md file');
+await fileItem.rightClick();
+
+// Select menu option
+await ai.click('Delete from context menu');
+```
+
+### Direct Right-Click with Selector
+
+```javascript
+await ai.rightClick('image in the gallery');
+await ai.click('Save image as');
+```
+
+### VS Code Context Menu
+
+```javascript
+import { test } from 'vitest';
+import { vscode } from '@testdriver/sdk';
+
+test('renames a file via context menu', async () => {
+  const { ai } = await vscode();
+  
+  // Right-click on a file
+  await ai.rightClick('test.js in the file explorer');
+  
+  // Click rename option
+  await ai.click('Rename');
+  
+  // Type new name
+  await ai.type('test.spec.js');
+  await ai.pressKeys('Enter');
+  
+  // Verify rename
+  const renamedFile = await ai.find('test.spec.js in the file explorer');
+  expect(renamedFile).toBeTruthy();
+});
+```
+
+### Browser Context Menu
+
+```javascript
+import { test } from 'vitest';
+import { chrome } from '@testdriver/sdk';
+
+test('opens link in new tab', async () => {
+  const { ai } = await chrome('https://example.com');
+  
+  // Right-click on a link
+  await ai.rightClick('Documentation link');
+  
+  // Select "Open in new tab"
+  await ai.click('Open link in new tab');
+});
+```
+
+### Custom Context Menu in Web App
+
+```javascript
+test('uses custom context menu', async () => {
+  const { ai } = await chrome('https://app.example.com');
+  
+  // Right-click on custom element
+  await ai.rightClick('project item in the list');
+  
+  // Wait for custom menu to appear
+  await ai.find('custom context menu');
+  
+  // Click menu option
+  await ai.click('Duplicate project');
+  
+  // Verify duplication
+  const duplicatedProject = await ai.find('project item (copy)');
+  expect(duplicatedProject).toBeTruthy();
+});
+```
+
+## 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

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>