testdriverai 7.0.0 → 7.1.0

package/docs/v7/platforms/windows.mdx

@@ -0,0 +1,430 @@
+---
+title: "Windows"
+description: "Run TestDriver tests on Windows sandboxes (Enterprise)"
+icon: "windows"
+---
+
+<Info>
+Windows sandboxes are available on **Enterprise plans only**. [Contact sales](https://testdriver.ai/contact) to enable Windows testing.
+</Info>
+
+## Overview
+
+Windows sandboxes enable testing of Windows-specific applications, desktop software, and Windows-only workflows.
+
+Windows sandboxes provide:
+- Windows Server 2019/2022
+- Full desktop environment
+- PowerShell and Command Prompt
+- Support for all TestDriver commands
+- Custom AMI support for pre-installed software
+- RDP access for debugging
+
+## Usage
+
+Specify Windows as the operating system:
+
+```javascript
+import { TestDriver } from '@testdriverai/testdriver';
+
+const testdriver = await TestDriver.create({
+  apiKey: process.env.TD_API_KEY,
+  os: 'windows'  // Requires Enterprise plan
+});
+```
+
+### With Lifecycle Helpers
+
+```javascript
+import { chrome } from './setup/lifecycleHelpers.mjs';
+import { test } from 'vitest';
+
+test('windows app test', async (context) => {
+  const { testdriver } = await chrome(context, { 
+    url: 'https://example.com',
+    os: 'windows'
+  });
+  
+  await testdriver.find('login button').then(el => el.click());
+});
+```
+
+## System Details
+
+### Operating System
+- **OS**: Windows Server 2019 or 2022
+- **Architecture**: x86_64 (64-bit)
+- **Desktop**: Windows Desktop Experience
+
+### Pre-installed Software
+- **Browsers**: Chrome, Edge, Firefox
+- **Runtimes**: .NET Framework, .NET Core
+- **Languages**: Node.js, Python (optional)
+- **Tools**: PowerShell 5.1+, Git, Visual Studio Build Tools (optional)
+
+### Default Resolution
+- **1920x1080** (configurable via `resolution` parameter)
+
+## Configuration
+
+### Custom Resolution
+
+Set screen resolution:
+
+```javascript
+const testdriver = await TestDriver.create({
+  apiKey: process.env.TD_API_KEY,
+  os: 'windows',
+  resolution: '1280x720'
+});
+```
+
+### Environment Variables
+
+```javascript
+const testdriver = await TestDriver.create({
+  apiKey: process.env.TD_API_KEY,
+  os: 'windows',
+  env: {
+    NODE_ENV: 'test',
+    DEBUG: 'true'
+  }
+});
+```
+
+## Custom AMI
+
+Enterprise plans support **custom Windows AMIs** with pre-installed software, reducing test setup time.
+
+### Benefits
+- Pre-install proprietary software
+- Configure system settings
+- Install custom certificates
+- Set up development tools
+
+### Setup
+
+1. Contact TestDriver support to create custom AMI
+2. Provide installation scripts and requirements
+3. Reference AMI in tests:
+
+```javascript
+const testdriver = await TestDriver.create({
+  apiKey: process.env.TD_API_KEY,
+  os: 'windows',
+  ami: 'ami-custom-windows-123'  // Your custom AMI ID
+});
+```
+
+See [Self-Hosting Guide](/v7/guides/self-hosting) for details on managing custom AMIs.
+
+## Common Use Cases
+
+### Windows Desktop Applications
+
+Test native Windows applications:
+
+```javascript
+import { test } from 'vitest';
+
+test('windows desktop app', async (context) => {
+  const { testdriver } = await chrome(context, { os: 'windows' });
+  
+  // Launch application
+  await testdriver.exec('pwsh', 
+    'Start-Process "C:\\Program Files\\MyApp\\MyApp.exe"',
+    5000
+  );
+  
+  // Wait for app to load
+  await new Promise(r => setTimeout(r, 3000));
+  
+  // Interact with app
+  await testdriver.find('main menu').then(el => el.click());
+  await testdriver.find('file open').then(el => el.click());
+});
+```
+
+### .NET Applications
+
+Test .NET Framework or .NET Core apps:
+
+```javascript
+test('dotnet app', async (context) => {
+  const { testdriver } = await chrome(context, { os: 'windows' });
+  
+  // Run .NET application
+  await testdriver.exec('pwsh',
+    'dotnet run --project C:\\app\\MyApp.csproj',
+    10000
+  );
+  
+  await testdriver.find('window title').then(el => el.click());
+});
+```
+
+### Registry Operations
+
+Modify Windows Registry:
+
+```javascript
+test('registry test', async (context) => {
+  const { testdriver } = await chrome(context, { os: 'windows' });
+  
+  // Set registry value
+  await testdriver.exec('pwsh',
+    'Set-ItemProperty -Path "HKCU:\\Software\\MyApp" -Name "Setting" -Value "Test"',
+    5000
+  );
+  
+  // Read registry value
+  const result = await testdriver.exec('pwsh',
+    'Get-ItemProperty -Path "HKCU:\\Software\\MyApp" -Name "Setting"',
+    5000
+  );
+  console.log('Registry value:', result);
+});
+```
+
+### File Operations
+
+Work with Windows file system:
+
+```javascript
+test('file operations', async (context) => {
+  const { testdriver } = await chrome(context, { os: 'windows' });
+  
+  // Create directory
+  await testdriver.exec('pwsh', 'New-Item -Path "C:\\Test" -ItemType Directory', 5000);
+  
+  // Download file
+  await testdriver.exec('pwsh',
+    'Invoke-WebRequest -Uri "https://example.com/file.zip" -OutFile "C:\\Test\\file.zip"',
+    30000
+  );
+  
+  // Extract archive
+  await testdriver.exec('pwsh',
+    'Expand-Archive -Path "C:\\Test\\file.zip" -DestinationPath "C:\\Test"',
+    10000
+  );
+});
+```
+
+## Command Execution
+
+### PowerShell
+
+Execute PowerShell commands:
+
+```javascript
+// PowerShell Core (pwsh)
+await testdriver.exec('pwsh', 'Get-Process', 5000);
+
+// PowerShell 5.1 (powershell)
+await testdriver.exec('powershell', 'Get-Service', 5000);
+```
+
+### Command Prompt
+
+Execute CMD commands:
+
+```javascript
+await testdriver.exec('cmd', 'dir C:\\', 5000);
+```
+
+### Batch Scripts
+
+Run batch files:
+
+```javascript
+// Create batch file
+await testdriver.exec('cmd', 
+  'echo @echo off > C:\\test.bat && echo echo Hello >> C:\\test.bat',
+  5000
+);
+
+// Execute batch file
+await testdriver.exec('cmd', 'C:\\test.bat', 5000);
+```
+
+## Package Management
+
+### Chocolatey
+
+Install packages with Chocolatey (if pre-installed on AMI):
+
+```javascript
+// Install package
+await testdriver.exec('pwsh',
+  'choco install -y git',
+  60000
+);
+
+// Use installed software
+await testdriver.exec('pwsh', 'git --version', 5000);
+```
+
+### NPM
+
+Install Node.js packages:
+
+```javascript
+await testdriver.exec('pwsh', 'npm install -g typescript', 30000);
+```
+
+### NuGet
+
+Install .NET packages:
+
+```javascript
+await testdriver.exec('pwsh',
+  'Install-Package Newtonsoft.Json -Force',
+  30000
+);
+```
+
+## Debugging
+
+### RDP Access
+
+Connect via Remote Desktop Protocol:
+
+```javascript
+const instance = testdriver.getInstance();
+console.log('RDP:', `${instance.ip}:${instance.rdpPort || 3389}`);
+
+// Use RDP client to connect and watch tests
+```
+
+### Screenshots
+
+Capture screenshots:
+
+```javascript
+// Windows screenshot via PowerShell
+await testdriver.exec('pwsh',
+  'Add-Type -AssemblyName System.Windows.Forms; [System.Windows.Forms.SendKeys]::SendWait("{PRTSC}"); Start-Sleep -Seconds 1',
+  5000
+);
+```
+
+### Event Logs
+
+Access Windows Event Logs:
+
+```javascript
+const logs = await testdriver.exec('pwsh',
+  'Get-EventLog -LogName Application -Newest 10',
+  5000
+);
+console.log('Event logs:', logs);
+```
+
+## Performance
+
+### Startup Time
+- **First test**: 60-120s (Windows boots slower than Linux)
+- **Subsequent tests**: 0s (sandbox reuse)
+- **Custom AMI**: Faster (pre-installed software)
+
+### Optimization Tips
+- Use custom AMI with pre-installed software
+- Reuse sandboxes across tests
+- Enable caching
+- Minimize software installation during tests
+
+See [Performance Guide](/v7/guides/performance) for details.
+
+## Limitations
+
+### Slower Startup
+Windows sandboxes take longer to boot than Linux (60-120s vs 20-60s).
+
+### Higher Cost
+Windows sandboxes consume more test minutes due to licensing.
+
+### Limited Free Tier
+Windows sandboxes not available on free tier.
+
+## Troubleshooting
+
+### Application Won't Launch
+
+```javascript
+// Try launching with full path
+await testdriver.exec('pwsh',
+  'Start-Process -FilePath "C:\\Program Files\\App\\app.exe"',
+  5000
+);
+
+// Or use cmd
+await testdriver.exec('cmd',
+  'start "" "C:\\Program Files\\App\\app.exe"',
+  5000
+);
+```
+
+### Permission Denied
+
+```javascript
+// Run as administrator (if AMI configured)
+await testdriver.exec('pwsh',
+  'Start-Process -FilePath "app.exe" -Verb RunAs',
+  5000
+);
+```
+
+### Timeout Issues
+
+Increase timeout for slower Windows operations:
+
+```javascript
+await testdriver.exec('pwsh', 'command', 120000);  // 2 minutes
+```
+
+## Enterprise Features
+
+### Custom AMI Management
+- Pre-install proprietary software
+- Configure system settings
+- Install certificates and licenses
+- Set up development environments
+
+### Dedicated Sandboxes
+- Reserved Windows instances
+- Faster startup (always-on)
+- Guaranteed availability
+
+### Support
+- Priority support for Windows issues
+- Custom AMI creation assistance
+- Windows-specific troubleshooting
+
+## Contact Sales
+
+Ready to enable Windows testing?
+
+<Card title="Contact Sales" icon="envelope" href="https://testdriver.ai/contact">
+  Get Enterprise access to Windows sandboxes
+</Card>
+
+## See Also
+
+<CardGroup cols={2}>
+  <Card title="Linux" icon="linux" href="/v7/platforms/linux">
+    Linux sandboxes (default)
+  </Card>
+  
+  <Card title="macOS" icon="apple" href="/v7/platforms/macos">
+    macOS sandboxes (Beta)
+  </Card>
+  
+  <Card title="Self-Hosting" icon="server" href="/v7/guides/self-hosting">
+    Custom AMI management
+  </Card>
+  
+  <Card title="Configuration" icon="gear" href="/v7/getting-started/configuration">
+    Sandbox configuration
+  </Card>
+</CardGroup>

package/docs/v7/presets/chrome-extension.mdx

@@ -0,0 +1,223 @@
+---
+title: "Chrome Extension Testing"
+sidebarTitle: "Chrome Extensions"
+description: "Test Chrome extensions with Chrome for Testing"
+icon: "puzzle-piece"
+---
+
+## Overview
+
+Test Chrome extensions by loading them into Chrome for Testing. This preset uses the `launchChromeExtension()` helper to launch Chrome with a specific extension loaded by its Chrome Web Store ID.
+
+## Quick Start
+
+```javascript
+import { test } from 'vitest';
+import TestDriver from 'testdriverai';
+import { 
+  runPrerunChromeExtension, 
+  runPostrun 
+} from 'testdriverai/testdriver/acceptance-sdk/setup/lifecycleHelpers.mjs';
+
+test('test chrome extension', async () => {
+  const client = await TestDriver.create({
+    apiKey: process.env.TD_API_KEY,
+    os: "linux",
+    verbosity: 1,
+  });
+
+  // Launch Chrome with extension loaded
+  // Extension ID from Chrome Web Store
+  await runPrerunChromeExtension(client, "cjpalhdlnbpafiamejdnhcphjbkeiagm");
+
+  // Your test code here
+  await client.focusApplication("Google Chrome");
+  
+  // ... test extension functionality
+
+  await runPostrun(client);
+  await client.cleanup();
+});
+```
+
+## Finding Extension IDs
+
+Extension IDs can be found in the Chrome Web Store URL:
+
+```
+https://chrome.google.com/webstore/detail/ublock-origin/cjpalhdlnbpafiamejdnhcphjbkeiagm
+                                                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+                                                      This is the extension ID
+```
+
+## Popular Extensions
+
+| Extension | ID |
+|-----------|---|
+| uBlock Origin | `cjpalhdlnbpafiamejdnhcphjbkeiagm` |
+| React Developer Tools | `fmkadmapgofadopljbjfkapdkoienihi` |
+| Redux DevTools | `lmhkpmbekcpmknklioeibfkpmmfibljd` |
+| Bitwarden | `nngceckbapebfimnlniiiahkandclblb` |
+
+## Loading Multiple Extensions
+
+Load multiple extensions by separating IDs with commas:
+
+```javascript
+await launchChromeExtension(
+  client, 
+  "cjpalhdlnbpafiamejdnhcphjbkeiagm,nngceckbapebfimnlniiiahkandclblb"
+);
+```
+
+## Complete Example
+
+```javascript
+import { describe, it, beforeAll, afterAll } from 'vitest';
+import TestDriver from 'testdriverai';
+import { 
+  runPrerunChromeExtension, 
+  runPostrun 
+} from 'testdriverai/testdriver/acceptance-sdk/setup/lifecycleHelpers.mjs';
+
+describe('Chrome Extension Testing', () => {
+  let client;
+  let dashcamUrl;
+
+  beforeAll(async () => {
+    client = await TestDriver.create({
+      apiKey: process.env.TD_API_KEY,
+      os: "linux",
+      verbosity: 1,
+    });
+
+    // Load uBlock Origin extension
+    await runPrerunChromeExtension(client, "cjpalhdlnbpafiamejdnhcphjbkeiagm");
+  });
+
+  afterAll(async () => {
+    if (client) {
+      dashcamUrl = await runPostrun(client);
+      await client.cleanup();
+    }
+  });
+
+  it('should verify extension is loaded', async () => {
+    await client.focusApplication("Google Chrome");
+
+    // Navigate to a page
+    const element = await client.find("TestDriver.ai Sandbox");
+    expect(element.found()).toBe(true);
+
+    // Test extension-specific functionality
+    // For example, checking if ads are blocked with uBlock
+  });
+
+  it('should access extension popup', async () => {
+    await client.focusApplication("Google Chrome");
+    
+    // Open extension management
+    await client.exec(
+      "sh",
+      `xdotool key --clearmodifiers ctrl+shift+e`,
+      5000,
+      true
+    );
+
+    // Wait for extensions page
+    await new Promise((resolve) => setTimeout(resolve, 2000));
+  });
+});
+```
+
+## Environment Setup
+
+Chrome for Testing is pre-installed in the E2B sandbox environment at:
+
+```
+/opt/chrome-for-testing/chrome
+/usr/local/bin/chrome-for-testing (symlink)
+```
+
+## Direct API Usage
+
+Use the lower-level API for more control:
+
+```javascript
+import { launchChromeExtension } from 'testdriverai/testdriver/acceptance-sdk/setup/lifecycleHelpers.mjs';
+
+// Launch with specific extension and URL
+await launchChromeExtension(
+  client,
+  "cjpalhdlnbpafiamejdnhcphjbkeiagm",
+  "https://example.com"
+);
+```
+
+## Testing Extension Features
+
+### Test Extension Popup
+
+```javascript
+it('opens extension popup', async () => {
+  // Click extension icon (varies by extension)
+  await client.click('extension icon in toolbar');
+  
+  // Interact with popup
+  const popup = await client.find('extension popup window');
+  expect(popup.found()).toBe(true);
+});
+```
+
+### Test Extension Settings
+
+```javascript
+it('configures extension settings', async () => {
+  // Right-click extension icon
+  await client.rightClick('extension icon');
+  
+  // Click options
+  await client.click('Options');
+  
+  // Configure settings
+  await client.click('Enable feature X');
+  await client.click('Save');
+});
+```
+
+### Test Content Scripts
+
+```javascript
+it('verifies content script injection', async () => {
+  // Navigate to a page
+  await client.exec('sh', 'xdotool key ctrl+l', 5000, true);
+  await client.type('https://example.com');
+  await client.pressKeys('Enter');
+  
+  // Check for extension-injected elements
+  const injected = await client.find('element added by extension');
+  expect(injected.found()).toBe(true);
+});
+```
+
+## Troubleshooting
+
+### Extension Not Loading
+
+1. Verify the extension ID is correct
+2. Check Chrome for Testing is installed in the sandbox
+3. Ensure extension is compatible with Chrome for Testing version
+
+### Extension Permissions
+
+Some extensions may require additional permissions or setup. You may need to:
+
+1. Navigate to `chrome://extensions/`
+2. Enable developer mode
+3. Grant required permissions
+
+## See Also
+
+- [Web Apps (Chrome)](/v7/presets/chrome) - Regular Chrome browser testing
+- [Desktop Apps (Electron)](/v7/presets/electron) - Electron app testing
+- [Lifecycle Helpers](/v7/guides/lifecycle) - Prerun/postrun functions