@testdriverai/agent 7.8.0-test.38

package/ai/skills/testdriver-press-keys/SKILL.md

@@ -0,0 +1,348 @@
+---
+name: testdriver:press-keys
+description: Press keyboard keys and shortcuts
+---
+<!-- Generated from press-keys.mdx. DO NOT EDIT. -->
+
+## Overview
+
+Press one or more keyboard keys simultaneously, useful for keyboard shortcuts, navigation, and special keys.
+
+## Syntax
+
+```javascript
+await testdriver.pressKeys(keys)
+```
+
+## Parameters
+
+<ParamField path="keys" type="Array&lt;string&gt;" required>
+  Array of keys to press simultaneously
+</ParamField>
+
+## Returns
+
+`Promise<void>`
+
+## Common Keys
+
+### Special Keys
+- `'enter'`, `'tab'`, `'escape'`, `'backspace'`, `'delete'`
+- `'space'`, `'up'`, `'down'`, `'left'`, `'right'`
+- `'home'`, `'end'`, `'pageup'`, `'pagedown'`
+
+### Modifier Keys
+- `'ctrl'`, `'alt'`, `'shift'`
+- `'command'` (macOS), `'win'` (Windows)
+- `'ctrlleft'`, `'ctrlright'`, `'shiftleft'`, `'shiftright'`
+
+### Function Keys
+- `'f1'` through `'f24'`
+
+## Examples
+
+### Navigation
+
+```javascript
+// Tab to next field
+await testdriver.pressKeys(['tab']);
+
+// Shift+Tab to previous field
+await testdriver.pressKeys(['shift', 'tab']);
+
+// Arrow keys
+await testdriver.pressKeys(['down']);
+await testdriver.pressKeys(['up']);
+await testdriver.pressKeys(['left']);
+await testdriver.pressKeys(['right']);
+
+// Home/End
+await testdriver.pressKeys(['home']);  // Start of line
+await testdriver.pressKeys(['end']);   // End of line
+
+// Page navigation
+await testdriver.pressKeys(['pagedown']);
+await testdriver.pressKeys(['pageup']);
+```
+
+### Keyboard Shortcuts
+
+```javascript
+// Copy (Ctrl+C / Cmd+C)
+await testdriver.pressKeys(['ctrl', 'c']);
+
+// Paste (Ctrl+V / Cmd+V)
+await testdriver.pressKeys(['ctrl', 'v']);
+
+// Save (Ctrl+S)
+await testdriver.pressKeys(['ctrl', 's']);
+
+// Select All (Ctrl+A)
+await testdriver.pressKeys(['ctrl', 'a']);
+
+// Undo (Ctrl+Z)
+await testdriver.pressKeys(['ctrl', 'z']);
+
+// Redo (Ctrl+Y)
+await testdriver.pressKeys(['ctrl', 'y']);
+
+// Find (Ctrl+F)
+await testdriver.pressKeys(['ctrl', 'f']);
+
+// New tab (Ctrl+T)
+await testdriver.pressKeys(['ctrl', 't']);
+
+// Close tab (Ctrl+W)
+await testdriver.pressKeys(['ctrl', 'w']);
+
+// Refresh (F5 or Ctrl+R)
+await testdriver.pressKeys(['f5']);
+await testdriver.pressKeys(['ctrl', 'r']);
+```
+
+### System Shortcuts
+
+```javascript
+// Alt+Tab (Windows - switch apps)
+await testdriver.pressKeys(['alt', 'tab']);
+
+// Alt+F4 (Windows - close window)
+await testdriver.pressKeys(['alt', 'f4']);
+
+// Win+D (Windows - show desktop)
+await testdriver.pressKeys(['winleft', 'd']);
+
+// Win+L (Windows - lock screen)
+await testdriver.pressKeys(['winleft', 'l']);
+
+// Cmd+Tab (macOS - switch apps)
+await testdriver.pressKeys(['command', 'tab']);
+
+// Cmd+Q (macOS - quit app)
+await testdriver.pressKeys(['command', 'q']);
+```
+
+### Form Submission
+
+```javascript
+// Submit form
+await testdriver.pressKeys(['enter']);
+
+// Cancel/Close
+await testdriver.pressKeys(['escape']);
+
+// Check checkbox
+await testdriver.pressKeys(['space']);
+```
+
+### Text Editing
+
+```javascript
+// Delete selected text
+await testdriver.pressKeys(['delete']);
+
+// Backspace
+await testdriver.pressKeys(['backspace']);
+
+// Select all and delete
+await testdriver.pressKeys(['ctrl', 'a']);
+await testdriver.pressKeys(['delete']);
+
+// Cut text
+await testdriver.pressKeys(['ctrl', 'x']);
+```
+
+## Best Practices
+
+<Check>
+  **Wait after shortcuts**
+  
+  Some keyboard shortcuts trigger animations or navigation:
+  
+  ```javascript
+  await testdriver.pressKeys(['ctrl', 't']); // New tab
+  await new Promise(r => setTimeout(r, 500)); // Wait for tab
+  await testdriver.pressKeys(['ctrl', 'l']); // Focus URL bar
+  ```
+</Check>
+
+<Check>
+  **Use Tab for form navigation**
+  
+  Tab is more reliable than clicking multiple fields:
+  
+  ```javascript
+  const firstField = await testdriver.find('email input');
+  await firstField.click();
+  await testdriver.type('user@example.com');
+  
+  await testdriver.pressKeys(['tab']);
+  await testdriver.type('password123');
+  
+  await testdriver.pressKeys(['tab']);
+  await testdriver.pressKeys(['enter']); // Submit
+  ```
+</Check>
+
+<Warning>
+  **Platform-specific keys**
+  
+  Use the appropriate modifier key for the platform:
+  - Windows/Linux: `'ctrl'`
+  - macOS: `'command'`
+  
+  ```javascript
+  // For cross-platform, you might need to detect OS
+  const modKey = process.platform === 'darwin' ? 'command' : 'ctrl';
+  await testdriver.pressKeys([modKey, 'c']); // Copy
+  ```
+</Warning>
+
+## Use Cases
+
+<AccordionGroup>
+  <Accordion title="Form Navigation">
+    ```javascript
+    // Fill form using Tab
+    const firstField = await testdriver.find('name field');
+    await firstField.click();
+    await testdriver.type('John Doe');
+    
+    await testdriver.pressKeys(['tab']);
+    await testdriver.type('john@example.com');
+    
+    await testdriver.pressKeys(['tab']);
+    await testdriver.type('555-0123');
+    
+    await testdriver.pressKeys(['tab']);
+    await testdriver.pressKeys(['enter']); // Submit
+    ```
+  </Accordion>
+  
+  <Accordion title="Text Manipulation">
+    ```javascript
+    const textArea = await testdriver.find('comment textarea');
+    await textArea.click();
+    
+    // Select all existing text
+    await testdriver.pressKeys(['ctrl', 'a']);
+    
+    // Copy it
+    await testdriver.pressKeys(['ctrl', 'c']);
+    
+    // Type new text
+    await testdriver.type('New comment');
+    
+    // Undo if needed
+    await testdriver.pressKeys(['ctrl', 'z']);
+    ```
+  </Accordion>
+  
+  <Accordion title="Browser Navigation">
+    ```javascript
+    // Open new tab
+    await testdriver.pressKeys(['ctrl', 't']);
+    await new Promise(r => setTimeout(r, 500));
+    
+    // Focus address bar
+    await testdriver.pressKeys(['ctrl', 'l']);
+    await testdriver.type('https://example.com');
+    await testdriver.pressKeys(['enter']);
+    
+    // Refresh page
+    await testdriver.pressKeys(['f5']);
+    
+    // Close tab
+    await testdriver.pressKeys(['ctrl', 'w']);
+    ```
+  </Accordion>
+  
+  <Accordion title="Application Shortcuts">
+    ```javascript
+    // Save document
+    await testdriver.pressKeys(['ctrl', 's']);
+    
+    // Print
+    await testdriver.pressKeys(['ctrl', 'p']);
+    
+    // Find in page
+    await testdriver.pressKeys(['ctrl', 'f']);
+    await testdriver.type('search term');
+    await testdriver.pressKeys(['escape']); // Close find
+    ```
+  </Accordion>
+</AccordionGroup>
+
+## Complete Example
+
+```javascript
+import { beforeAll, afterAll, describe, it } from 'vitest';
+import TestDriver from 'testdriverai';
+
+describe('Keyboard Navigation', () => {
+  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 navigate form with keyboard', async () => {
+    await testdriver.focusApplication('Google Chrome');
+    
+    // Find first field
+    const emailField = await testdriver.find('email input');
+    await emailField.click();
+    await testdriver.type('user@example.com');
+    
+    // Tab through fields
+    await testdriver.pressKeys(['tab']);
+    await testdriver.type('John');
+    
+    await testdriver.pressKeys(['tab']);
+    await testdriver.type('Doe');
+    
+    await testdriver.pressKeys(['tab']);
+    await testdriver.type('password123');
+    
+    // Submit with Enter
+    await testdriver.pressKeys(['tab']);
+    await testdriver.pressKeys(['enter']);
+    
+    await testdriver.assert('form submitted successfully');
+  });
+
+  it('should use keyboard shortcuts', async () => {
+    // Open new browser tab
+    await testdriver.pressKeys(['ctrl', 't']);
+    await new Promise(r => setTimeout(r, 500));
+    
+    // Focus address bar
+    await testdriver.pressKeys(['ctrl', 'l']);
+    await testdriver.type('https://example.com');
+    await testdriver.pressKeys(['enter']);
+    
+    await new Promise(r => setTimeout(r, 2000));
+    
+    // Select all page content
+    await testdriver.pressKeys(['ctrl', 'a']);
+    
+    // Copy
+    await testdriver.pressKeys(['ctrl', 'c']);
+    
+    // Refresh page
+    await testdriver.pressKeys(['f5']);
+  });
+});
+```
+
+## Related Methods
+
+- [`type()`](/v7/type) - Type text
+- [`click()`](/v7/click) - Click elements
+- [`scroll()`](/v7/scroll) - Scroll pages

package/ai/skills/testdriver-provision/SKILL.md

@@ -0,0 +1,331 @@
+---
+name: testdriver:provision
+description: Launch browsers, desktop apps, and extensions in your sandbox
+---
+<!-- Generated from provision.mdx. DO NOT EDIT. -->
+
+## Overview
+
+The Provision API sets up applications in your sandbox before tests run. It handles downloading, installing, and launching browsers, desktop apps, VS Code, Chrome extensions, and more.
+
+Access provision methods via `testdriver.provision.*`:
+
+```javascript
+await testdriver.provision.chrome({ url: 'https://example.com' });
+```
+
+<Note>
+  When `reconnect: true` is set on the client, **all provision methods are skipped** since the application is assumed to already be running.
+</Note>
+
+## Methods
+
+### chrome()
+
+Launch Google Chrome with an optional URL.
+
+```javascript
+await testdriver.provision.chrome(options?)
+```
+
+<ParamField path="options" type="ProvisionChromeOptions">
+  <Expandable title="properties">
+    <ParamField path="url" type="string" default="http://testdriver-sandbox.vercel.app/">
+      URL to navigate to after launch.
+    </ParamField>
+    
+    <ParamField path="maximized" type="boolean" default={true}>
+      Launch Chrome in maximized window mode.
+    </ParamField>
+    
+    <ParamField path="guest" type="boolean" default={false}>
+      Launch Chrome in guest profile mode.
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+```javascript
+// Basic
+await testdriver.provision.chrome({ url: 'https://example.com' });
+
+// With guest mode
+await testdriver.provision.chrome({
+  url: 'https://example.com',
+  guest: true,
+  maximized: true,
+});
+```
+
+### chromeExtension()
+
+Install and launch a Chrome extension. You can install from a local unpacked directory or from the Chrome Web Store by extension ID.
+
+```javascript
+await testdriver.provision.chromeExtension(options)
+```
+
+<ParamField path="options" type="ProvisionChromeExtensionOptions" required>
+  One of `extensionPath` or `extensionId` is required.
+
+  <Expandable title="properties">
+    <ParamField path="extensionPath" type="string">
+      Local path to an unpacked extension directory. The extension files are uploaded to the sandbox.
+    </ParamField>
+    
+    <ParamField path="extensionId" type="string">
+      Chrome Web Store extension ID to install.
+    </ParamField>
+    
+    <ParamField path="maximized" type="boolean" default={true}>
+      Launch Chrome in maximized window mode.
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+```javascript
+// From local directory
+await testdriver.provision.chromeExtension({
+  extensionPath: './my-extension',
+});
+
+// From Chrome Web Store
+await testdriver.provision.chromeExtension({
+  extensionId: 'abcdefghijklmnop',
+});
+```
+
+### vscode()
+
+Launch Visual Studio Code with an optional workspace and extensions.
+
+```javascript
+await testdriver.provision.vscode(options?)
+```
+
+<ParamField path="options" type="ProvisionVSCodeOptions">
+  <Expandable title="properties">
+    <ParamField path="workspace" type="string">
+      Path to a workspace folder or `.code-workspace` file to open.
+    </ParamField>
+    
+    <ParamField path="extensions" type="string[]" default={[]}>
+      Array of VS Code extension IDs to install before launching.
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+```javascript
+await testdriver.provision.vscode({
+  workspace: '/home/testdriver/project',
+  extensions: ['ms-python.python', 'esbenp.prettier-vscode'],
+});
+```
+
+### installer()
+
+Download and run an application installer. Supports `.msi`, `.exe`, `.deb`, `.rpm`, `.appimage`, `.sh`, `.dmg`, and `.pkg` formats.
+
+```javascript
+await testdriver.provision.installer(options)
+```
+
+<ParamField path="options" type="ProvisionInstallerOptions" required>
+  <Expandable title="properties">
+    <ParamField path="url" type="string" required>
+      Download URL for the installer.
+    </ParamField>
+    
+    <ParamField path="filename" type="string">
+      Override the auto-detected filename from the URL.
+    </ParamField>
+    
+    <ParamField path="appName" type="string">
+      Application name to focus after installation completes.
+    </ParamField>
+    
+    <ParamField path="launch" type="boolean" default={true}>
+      Whether to focus/launch the app after installation.
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+**Behavior:**
+- Downloads the installer from the URL
+- Auto-detects the install method based on file extension
+- Runs the appropriate install command (e.g., `msiexec` for `.msi`, `dpkg` for `.deb`)
+- Optionally focuses the installed application
+
+```javascript
+// Windows MSI installer
+await testdriver.provision.installer({
+  url: 'https://example.com/app-setup.msi',
+  appName: 'MyApp',
+});
+
+// Linux DEB package
+await testdriver.provision.installer({
+  url: 'https://example.com/app.deb',
+  appName: 'MyApp',
+  launch: true,
+});
+```
+
+### electron()
+
+Launch an Electron application.
+
+```javascript
+await testdriver.provision.electron(options)
+```
+
+<ParamField path="options" type="ProvisionElectronOptions" required>
+  <Expandable title="properties">
+    <ParamField path="appPath" type="string" required>
+      Path to the Electron application directory or executable.
+    </ParamField>
+    
+    <ParamField path="args" type="string[]" default={[]}>
+      Additional command-line arguments to pass to the Electron app.
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+```javascript
+await testdriver.provision.electron({
+  appPath: '/home/testdriver/my-electron-app',
+  args: ['--no-sandbox'],
+});
+```
+
+### dashcam()
+
+Start Dashcam recording with custom options. Usually called automatically by other provision methods, but can be called directly for custom configurations.
+
+```javascript
+await testdriver.provision.dashcam(options?)
+```
+
+<ParamField path="options" type="ProvisionDashcamOptions">
+  <Expandable title="properties">
+    <ParamField path="logPath" type="string">
+      Path to the TestDriver log file. Defaults to `/tmp/testdriver.log` (Linux) or `C:\Users\testdriver\testdriver.log` (Windows).
+    </ParamField>
+    
+    <ParamField path="logName" type="string" default="TestDriver Log">
+      Display name for the log file in the Dashcam replay.
+    </ParamField>
+    
+    <ParamField path="webLogs" type="boolean" default={true}>
+      Enable web traffic log capture.
+    </ParamField>
+    
+    <ParamField path="title" type="string">
+      Recording title for the Dashcam session.
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+```javascript
+await testdriver.provision.dashcam({
+  title: 'Login Flow Test',
+  logPath: '/tmp/my-app.log',
+  logName: 'Application Log',
+  webLogs: true,
+});
+```
+
+## Reconnect Behavior
+
+When `reconnect: true` is set on the client, all provision methods are wrapped in a Proxy that intercepts calls and skips them silently. This is because when reconnecting to an existing sandbox, the applications are already running.
+
+```javascript
+const testdriver = new TestDriver({
+  reconnect: true,
+});
+
+await testdriver.ready();
+
+// These calls are silently skipped:
+await testdriver.provision.chrome({ url: 'https://example.com' });
+await testdriver.provision.dashcam();
+```
+
+## Types
+
+```typescript
+interface ProvisionChromeOptions {
+  url?: string;                    // Default: "http://testdriver-sandbox.vercel.app/"
+  maximized?: boolean;             // Default: true
+  guest?: boolean;                 // Default: false
+}
+
+interface ProvisionChromeExtensionOptions {
+  extensionPath?: string;          // Local unpacked extension path
+  extensionId?: string;            // Chrome Web Store ID
+  maximized?: boolean;             // Default: true
+}
+
+interface ProvisionVSCodeOptions {
+  workspace?: string;              // Workspace path
+  extensions?: string[];           // Extension IDs to install
+}
+
+interface ProvisionInstallerOptions {
+  url: string;                     // Download URL (required)
+  filename?: string;               // Override filename
+  appName?: string;                // App name to focus
+  launch?: boolean;                // Default: true
+}
+
+interface ProvisionElectronOptions {
+  appPath: string;                 // Path to Electron app (required)
+  args?: string[];                 // Additional args
+}
+
+interface ProvisionDashcamOptions {
+  logPath?: string;                // Log file path
+  logName?: string;                // Default: "TestDriver Log"
+  webLogs?: boolean;               // Default: true
+  title?: string;                  // Recording title
+}
+```
+
+## Complete Example
+
+```javascript
+import { describe, it, beforeAll, afterAll } from 'vitest';
+import TestDriver from 'testdriverai';
+
+describe('Chrome Extension Test', () => {
+  let testdriver;
+
+  beforeAll(async () => {
+    testdriver = new TestDriver({
+      os: 'linux',
+      resolution: '1920x1080',
+    });
+    
+    await testdriver.ready();
+    
+    // Install extension and open Chrome
+    await testdriver.provision.chromeExtension({
+      extensionPath: './my-extension',
+    });
+    
+    // Start Dashcam with custom logs
+    await testdriver.provision.dashcam({
+      title: 'Extension Test',
+      webLogs: true,
+    });
+  });
+
+  afterAll(async () => {
+    await testdriver.disconnect();
+  });
+
+  it('tests the extension popup', async () => {
+    await testdriver.find('extension icon').click();
+    await testdriver.find('popup content').click();
+  });
+});
+```