testdriverai 6.2.2 → 7.0.0

package/docs/v7/api/exec.mdx

@@ -0,0 +1,346 @@
+---
+title: "exec()"
+sidebarTitle: "exec"
+description: "Execute code or shell commands in the sandbox"
+icon: "terminal"
+---
+
+## Overview
+
+Execute JavaScript code in the browser or PowerShell commands in the Windows sandbox environment.
+
+## Syntax
+
+```javascript
+await testdriver.exec(language, code, timeout, silent)
+```
+
+## Parameters
+
+<ParamField path="language" type="string" required>
+  Language to execute: `'js'` (JavaScript) or `'pwsh'` (PowerShell)
+</ParamField>
+
+<ParamField path="code" type="string" required>
+  Code or command to execute
+</ParamField>
+
+<ParamField path="timeout" type="number" required>
+  Timeout in milliseconds
+</ParamField>
+
+<ParamField path="silent" type="boolean" default="false">
+  Suppress output if `true`
+</ParamField>
+
+## Returns
+
+`Promise<string>` - Command output
+
+## JavaScript Execution
+
+Execute JavaScript in the browser context (Windows sandbox only).
+
+### DOM Manipulation
+
+```javascript
+// Click an element via JavaScript
+await testdriver.exec('js', `
+  document.querySelector('#submit-button').click();
+`, 5000);
+
+// Fill a form
+await testdriver.exec('js', `
+  document.querySelector('#username').value = 'testuser';
+  document.querySelector('#password').value = 'password123';
+  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);
+console.log('Page title:', title);
+
+// 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);
+```
+
+## PowerShell Execution
+
+Execute PowerShell commands in the Windows sandbox.
+
+### Software Installation
+
+```javascript
+// Install npm package globally
+await testdriver.exec('pwsh', 'npm install -g http-server', 30000);
+
+// Install via Chocolatey
+await testdriver.exec('pwsh', 'choco install firefox -y', 60000);
+
+// Download and run installer
+await testdriver.exec('pwsh', `
+  Invoke-WebRequest -Uri "https://example.com/setup.exe" -OutFile "C:\\setup.exe"
+  Start-Process -FilePath "C:\\setup.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
+);
+
+// List directory
+const files = await testdriver.exec('pwsh', 
+  'Get-ChildItem -Path "C:\\Users\\testdriver\\Documents"', 
+  5000
+);
+```
+
+### Process Management
+
+```javascript
+// List running processes
+const processes = await testdriver.exec('pwsh', 'Get-Process', 5000);
+
+// Start application
+await testdriver.exec('pwsh', `
+  Start-Process "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe" -ArgumentList "--start-maximized", "https://example.com"
+`, 5000);
+
+// Kill a process
+await testdriver.exec('pwsh', 'Stop-Process -Name "chrome" -Force', 5000);
+
+// Wait for process
+await testdriver.exec('pwsh', 'Start-Process notepad -Wait', 30000);
+```
+
+### Environment Variables
+
+```javascript
+// Set environment variable (session)
+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 portOpen = await testdriver.exec('pwsh', 
+  'Test-NetConnection -ComputerName localhost -Port 3000', 
+  5000
+);
+```
+
+## Silent Execution
+
+Suppress output for background operations:
+
+```javascript
+// Silent installation
+await testdriver.exec('pwsh', 'npm install -g some-package', 30000, true);
+
+// Start background process
+await testdriver.exec('pwsh', 'Start-Process notepad', 5000, true);
+
+// Run setup script silently
+await testdriver.exec('pwsh', '.\\setup.ps1', 60000, true);
+```
+
+## Best Practices
+
+<Check>
+  **Use appropriate timeouts**
+  
+  ```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);
+  ```
+</Check>
+
+<Check>
+  **Handle errors gracefully**
+  
+  ```javascript
+  try {
+    await testdriver.exec('pwsh', 'Some-Command', 5000);
+  } catch (error) {
+    console.error('Command failed:', error.message);
+    // Fallback or retry logic
+  }
+  ```
+</Check>
+
+<Check>
+  **Use silent mode for background tasks**
+  
+  ```javascript
+  // Silent install
+  await testdriver.exec('pwsh', 'npm install -g tool', 30000, true);
+  
+  // Background service
+  await testdriver.exec('pwsh', 'Start-Service MyService', 5000, true);
+  ```
+</Check>
+
+<Warning>
+  **Escape strings properly in PowerShell**
+  
+  Use proper escaping for special characters:
+  
+  ```javascript
+  // Use backticks for newlines
+  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
+  );
+  ```
+</Warning>
+
+## Complete Example
+
+```javascript
+import { beforeAll, afterAll, describe, it } from 'vitest';
+import TestDriver from 'testdriverai';
+
+describe('Code Execution', () => {
+  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 execute JavaScript in browser', async () => {
+    await testdriver.focusApplication('Google Chrome');
+    
+    // Get page info via JavaScript
+    const title = await testdriver.exec('js', 'document.title', 5000);
+    console.log('Page title:', title);
+    
+    // Manipulate DOM
+    await testdriver.exec('js', `
+      document.querySelector('#username').value = 'testuser';
+    `, 5000);
+    
+    // Verify
+    const value = await testdriver.exec('js', `
+      document.querySelector('#username').value
+    `, 5000);
+    
+    expect(value).toBe('testuser');
+  });
+
+  it('should install and use tools', async () => {
+    // Install tool
+    await testdriver.exec('pwsh', 'npm install -g http-server', 30000, true);
+    
+    // Create HTML file
+    await testdriver.exec('pwsh', `
+      Set-Content -Path "C:\\index.html" -Value "<h1>Test Page</h1>"
+    `, 5000);
+    
+    // Start server in background
+    await testdriver.exec('pwsh', `
+      Start-Process pwsh -ArgumentList "-Command", "http-server C:\\ -p 8080"
+    `, 5000, true);
+    
+    await new Promise(r => setTimeout(r, 3000));
+    
+    // Launch browser
+    await testdriver.exec('pwsh', `
+      Start-Process chrome -ArgumentList "http://localhost:8080"
+    `, 5000);
+    
+    await testdriver.focusApplication('Google Chrome');
+    
+    // Verify page loaded
+    const content = await testdriver.exec('js', 'document.body.textContent', 5000);
+    expect(content).toContain('Test Page');
+  });
+});
+```
+
+## Related Methods
+
+- [`focusApplication()`](/v7/api/focusApplication) - Focus apps before exec
+- [`find()`](/v7/api/find) - Locate elements (alternative to DOM manipulation)
+- [`type()`](/v7/api/type) - Type text (alternative to JS form filling)

package/docs/v7/api/find.mdx

@@ -0,0 +1,316 @@
+---
+title: "find()"
+sidebarTitle: "find"
+description: "Locate UI elements using natural language"
+icon: "magnifying-glass"
+---
+
+## Overview
+
+Locate UI elements on screen using AI-powered natural language descriptions. Returns an `Element` object that can be interacted with.
+
+## Syntax
+
+```javascript
+const element = await testdriver.find(description)
+```
+
+## Parameters
+
+<ParamField path="description" type="string" required>
+  Natural language description of the element to find
+</ParamField>
+
+## Returns
+
+`Promise<Element>` - Element instance that has been automatically located
+
+## Examples
+
+### Basic Element Finding
+
+```javascript
+// Find by role
+const button = await testdriver.find('submit button');
+const input = await testdriver.find('email input field');
+
+// Find by text content
+const link = await testdriver.find('Contact Us link');
+const heading = await testdriver.find('Welcome heading');
+
+// Find by visual appearance
+const icon = await testdriver.find('red warning icon');
+const image = await testdriver.find('company logo image');
+```
+
+### Finding with Context
+
+```javascript
+// Provide location context
+const field = await testdriver.find('username input in the login form');
+const button = await testdriver.find('delete button in the top right corner');
+
+// Describe nearby elements
+const input = await testdriver.find('input field below the email label');
+const checkbox = await testdriver.find('checkbox next to "Remember me"');
+
+// Describe visual position
+const menu = await testdriver.find('hamburger menu icon in the top left');
+```
+
+### Interacting with Found Elements
+
+```javascript
+// Find and click
+const submitBtn = await testdriver.find('submit button');
+await submitBtn.click();
+
+// Find and verify
+const message = await testdriver.find('success message');
+if (message.found()) {
+  console.log('Success message appeared');
+}
+
+// Find and extract info
+const price = await testdriver.find('product price');
+console.log('Price location:', price.coordinates);
+console.log('Price text:', price.text);
+```
+
+## Element Object
+
+The returned `Element` object provides:
+
+### Methods
+
+- `found()` - Check if element was located
+- `click(action)` - Click the element
+- `hover()` - Hover over the element
+- `doubleClick()` - Double-click the element
+- `rightClick()` - Right-click the element
+- `find(newDescription)` - Re-locate with optional new description
+
+### Properties
+
+- `coordinates` - Element position `{x, y, centerX, centerY}`
+- `x`, `y` - Top-left coordinates
+- `centerX`, `centerY` - Center coordinates
+- `text` - Text content (if available)
+- `screenshot` - Base64 screenshot (if available)
+- `confidence` - AI confidence score
+- `width`, `height` - Element dimensions
+- `boundingBox` - Complete bounding box
+
+See [Elements Reference](/v7/api/elements) for complete details.
+
+## Best Practices
+
+<Check>
+  **Be specific in descriptions**
+  
+  More specific descriptions improve accuracy:
+  
+  ```javascript
+  // ✅ Good
+  await testdriver.find('blue submit button below the email field');
+  
+  // ❌ Too vague
+  await testdriver.find('button');
+  ```
+</Check>
+
+<Check>
+  **Always check if found**
+  
+  Verify elements were located before interacting:
+  
+  ```javascript
+  const element = await testdriver.find('login button');
+  if (!element.found()) {
+    throw new Error('Login button not found');
+  }
+  await element.click();
+  ```
+</Check>
+
+<Check>
+  **Include visual or positional context**
+  
+  ```javascript
+  // Include color
+  await testdriver.find('red error icon');
+  
+  // Include position
+  await testdriver.find('search button in the top navigation bar');
+  
+  // Include nearby text
+  await testdriver.find('checkbox next to "I agree to terms"');
+  ```
+</Check>
+
+## Polling for Dynamic Elements
+
+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(r => setTimeout(r, 1000));
+}
+
+if (!loginButton.found()) {
+  throw new Error('Login button never appeared');
+}
+
+await loginButton.click();
+```
+
+### Helper Function
+
+```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(r => setTimeout(r, 1000));
+  }
+  
+  throw new Error(`Element "${description}" not found after ${timeout}ms`);
+}
+
+// Usage
+const button = await waitForElement(testdriver, 'submit button', 10000);
+await button.click();
+```
+
+## Use Cases
+
+<AccordionGroup>
+  <Accordion title="Form Fields">
+    ```javascript
+    const emailField = await testdriver.find('email input field');
+    await emailField.click();
+    await testdriver.type('user@example.com');
+    
+    const passwordField = await testdriver.find('password input');
+    await passwordField.click();
+    await testdriver.type('MyP@ssw0rd');
+    ```
+  </Accordion>
+  
+  <Accordion title="Buttons and Links">
+    ```javascript
+    const submitBtn = await testdriver.find('submit button');
+    await submitBtn.click();
+    
+    const cancelLink = await testdriver.find('cancel link');
+    await cancelLink.click();
+    
+    const menuIcon = await testdriver.find('hamburger menu icon');
+    await menuIcon.click();
+    ```
+  </Accordion>
+  
+  <Accordion title="Dynamic Content">
+    ```javascript
+    // Wait for loading to complete
+    let content;
+    for (let i = 0; i < 30; i++) {
+      content = await testdriver.find('results table');
+      if (content.found()) break;
+      await new Promise(r => setTimeout(r, 1000));
+    }
+    
+    // Interact with loaded content
+    const firstRow = await testdriver.find('first row in the results table');
+    await firstRow.click();
+    ```
+  </Accordion>
+  
+  <Accordion title="Complex UI Elements">
+    ```javascript
+    // Modals and dialogs
+    const modal = await testdriver.find('confirmation dialog');
+    if (modal.found()) {
+      const confirmBtn = await testdriver.find('confirm button in the dialog');
+      await confirmBtn.click();
+    }
+    
+    // Dropdown menus
+    const dropdown = await testdriver.find('country dropdown');
+    await dropdown.click();
+    
+    const option = await testdriver.find('United States option');
+    await option.click();
+    ```
+  </Accordion>
+</AccordionGroup>
+
+## Complete Example
+
+```javascript
+import { beforeAll, afterAll, describe, it, expect } from 'vitest';
+import TestDriver from 'testdriverai';
+
+describe('Element Finding', () => {
+  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 find and interact with elements', async () => {
+    await testdriver.focusApplication('Google Chrome');
+    
+    // Find login form elements
+    const usernameField = await testdriver.find('username input field');
+    expect(usernameField.found()).toBe(true);
+    
+    await usernameField.click();
+    await testdriver.type('testuser');
+    
+    // Find with context
+    const passwordField = await testdriver.find('password input below username');
+    await passwordField.click();
+    await testdriver.type('password123');
+    
+    // Find button
+    const submitBtn = await testdriver.find('green submit button');
+    expect(submitBtn.found()).toBe(true);
+    
+    console.log('Button location:', submitBtn.centerX, submitBtn.centerY);
+    
+    await submitBtn.click();
+    
+    // Wait for success message
+    let successMsg;
+    for (let i = 0; i < 10; i++) {
+      successMsg = await testdriver.find('success notification');
+      if (successMsg.found()) break;
+      await new Promise(r => setTimeout(r, 1000));
+    }
+    
+    expect(successMsg.found()).toBe(true);
+  });
+});
+```
+
+## Related Methods
+
+- [`click()`](/v7/api/click) - Click on found elements
+- [`hover()`](/v7/api/hover) - Hover over elements
+- [`assert()`](/v7/api/assert) - Verify element states
+- [Elements Reference](/v7/api/elements) - Complete Element API