@testdriverai/agent 7.8.0-canary.10

package/docs/v7/exec.mdx

@@ -0,0 +1,318 @@
+---
+title: "exec()"
+sidebarTitle: "exec"
+description: "Execute shell or PowerShell commands in the sandbox"
+icon: "terminal"
+---
+
+## Overview
+
+Execute shell commands (Linux) or PowerShell commands (Windows) in the sandbox environment.
+
+## Syntax
+
+```javascript
+await testdriver.exec(language, code, timeout, silent)
+```
+
+## Parameters
+
+<ParamField path="language" type="string" required>
+  Language to execute: `'sh'` (Shell/Linux) or `'pwsh'` (PowerShell/Windows)
+</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
+
+## Shell Execution (Linux)
+
+Execute shell commands in the Linux sandbox.
+
+### Basic Commands
+
+```javascript
+// List files
+const files = await testdriver.exec('sh', 'ls -la', 5000);
+
+// Check current directory
+const pwd = await testdriver.exec('sh', 'pwd', 5000);
+
+// Run a script
+await testdriver.exec('sh', './setup.sh', 60000);
+```
+
+### File Operations
+
+```javascript
+// Create a file
+await testdriver.exec('sh', 'echo "Hello World" > test.txt', 5000);
+
+// Read a file
+const content = await testdriver.exec('sh', 'cat test.txt', 5000);
+
+// Copy files
+await testdriver.exec('sh', 'cp source.txt dest.txt', 5000);
+
+// Delete files
+await testdriver.exec('sh', 'rm test.txt', 5000);
+```
+
+## PowerShell Execution (Windows)
+
+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('sh', 'ls -la', 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();
+  });
+
+  afterAll(async () => {
+    await testdriver.disconnect();
+  });
+
+  it('should execute shell commands on Linux', async () => {
+    // List directory
+    const files = await testdriver.exec('sh', 'ls -la', 5000);
+    console.log('Files:', files);
+    
+    // Create a file
+    await testdriver.exec('sh', 'echo "Hello World" > test.txt', 5000);
+    
+    // Read the file
+    const content = await testdriver.exec('sh', 'cat test.txt', 5000);
+    expect(content).toContain('Hello World');
+  });
+
+  it('should install and use tools on Windows', 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');
+  });
+});
+```
+
+## Related Methods
+
+- [`focusApplication()`](/v7/focus-application) - Focus apps before exec
+- [`find()`](/v7/find) - Locate elements visually
+- [`type()`](/v7/type) - Type text into inputs