testdriverai 7.8.0-test.4 → 7.8.0-test.40

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

@@ -0,0 +1,356 @@
+---
+name: testdriver:events
+description: Listen to SDK lifecycle events with wildcard support
+---
+<!-- Generated from events.mdx. DO NOT EDIT. -->
+
+## Overview
+
+TestDriver uses [EventEmitter2](https://github.com/EventEmitter2/EventEmitter2) for its event system. Events use a colon-delimited namespace pattern and support wildcard listeners.
+
+Access the emitter through `testdriver.emitter`:
+
+```javascript
+testdriver.emitter.on('command:start', (data) => {
+  console.log(`Running: ${data.command}`);
+});
+```
+
+### Configuration
+
+The internal emitter is created with:
+
+```javascript
+new EventEmitter2({
+  wildcard: true,
+  delimiter: ':',
+  maxListeners: 20,
+  verboseMemoryLeak: false,
+  ignoreErrors: false,
+});
+```
+
+### Wildcard Listeners
+
+Use `*` to match a single level or `**` to match multiple levels:
+
+```javascript
+// Match all log events
+testdriver.emitter.on('log:*', (message) => {
+  console.log(message);
+});
+
+// Match all events in any namespace
+testdriver.emitter.on('**', (...args) => {
+  console.log('Event:', this.event, args);
+});
+```
+
+## Event Reference
+
+### Command Events
+
+Emitted during the execution of SDK commands (`click`, `type`, `find`, etc.).
+
+| Event | Payload |
+|---|---|
+| `command:start` | `{ command, depth, data, timestamp, sourcePosition }` |
+| `command:success` | `{ command, depth, data, duration, response, timestamp, sourcePosition }` |
+| `command:error` | `{ command, depth, data, error, duration, timestamp, sourcePosition }` |
+| `command:status` | `{ command, status: "executing", data, depth, timestamp }` |
+| `command:progress` | `{ command, status: "completed", timing, data, depth, timestamp }` |
+
+```javascript
+testdriver.emitter.on('command:start', ({ command, data }) => {
+  console.log(`Starting ${command}`, data);
+});
+
+testdriver.emitter.on('command:error', ({ command, error, duration }) => {
+  console.error(`${command} failed after ${duration}ms: ${error}`);
+});
+```
+
+### Step Events
+
+Emitted for each AI reasoning step within a command.
+
+| Event | Payload |
+|---|---|
+| `step:start` | `{ stepIndex, prompt, commandCount, timestamp, sourcePosition }` |
+| `step:success` | `{ stepIndex, prompt, commandCount, duration, timestamp, sourcePosition }` |
+| `step:error` | `{ stepIndex, prompt, error, duration?, timestamp, sourcePosition? }` |
+
+```javascript
+testdriver.emitter.on('step:start', ({ stepIndex, prompt }) => {
+  console.log(`Step ${stepIndex}: ${prompt}`);
+});
+```
+
+### Test Events
+
+Emitted when a test file execution starts.
+
+| Event | Payload |
+|---|---|
+| `test:start` | `{ filePath, timestamp }` |
+| `test:success` | *Emitted on test completion* |
+| `test:error` | *Emitted on test failure* |
+
+### Log Events
+
+Emitted for all log output from the SDK.
+
+| Event | Payload |
+|---|---|
+| `log:log` | `(message: string)` — general log message |
+| `log:warn` | `(message: string)` — warning message |
+| `log:debug` | `(message: string)` — debug output (only when `VERBOSE`/`DEBUG`/`TD_DEBUG` env set) |
+| `log:info` | `(message: string)` — informational message |
+| `log:error` | `(message: string)` — error message |
+| `log:narration` | `(message: string, overwrite?: boolean)` — in-place status line |
+| `log:markdown` | `(markdown: string)` — full static markdown content |
+| `log:markdown:start` | `(streamId: string)` — begin streaming markdown |
+| `log:markdown:chunk` | `(streamId: string, chunk: string)` — incremental chunk |
+| `log:markdown:end` | `(streamId: string)` — end streaming markdown |
+
+```javascript
+// Capture all logs
+testdriver.emitter.on('log:*', function (message) {
+  console.log(`[${this.event}]`, message);
+});
+```
+
+### Screen Capture Events
+
+Emitted during screenshot capture.
+
+| Event | Payload |
+|---|---|
+| `screen-capture:start` | `{ scale, silent, display }` |
+| `screen-capture:end` | `{ scale, silent, display }` |
+| `screen-capture:error` | `{ error, scale, silent, display }` |
+
+### Sandbox Events
+
+Emitted for sandbox WebSocket lifecycle and communication.
+
+| Event | Payload |
+|---|---|
+| `sandbox:connected` | *No payload* — WebSocket connection established |
+| `sandbox:authenticated` | `{ traceId }` — authentication successful |
+| `sandbox:error` | `(err: Error \| string)` — connection or sandbox error |
+| `sandbox:sent` | `(message: object)` — WebSocket message sent |
+| `sandbox:received` | *No payload* — successful message reply received |
+| `sandbox:progress` | `{ step, message }` — sandbox setup progress |
+
+```javascript
+testdriver.emitter.on('sandbox:connected', () => {
+  console.log('Connected to sandbox');
+});
+
+testdriver.emitter.on('sandbox:progress', ({ step, message }) => {
+  console.log(`Sandbox: [${step}] ${message}`);
+});
+```
+
+### Redraw Events
+
+Emitted during screen stability detection. See [Redraw](/v7/redraw) for more details.
+
+| Event | Payload |
+|---|---|
+| `redraw:status` | `{ redraw: { enabled, settled, hasChangedFromInitial, consecutiveFramesStable, diffFromInitial, diffFromLast, text }, network: { enabled, settled, rxBytes, txBytes, text }, timeout: { isTimeout, elapsed, max, text } }` |
+| `redraw:complete` | `{ screenSettled, hasChangedFromInitial, consecutiveFramesStable, networkSettled, isTimeout, timeElapsed }` |
+
+```javascript
+testdriver.emitter.on('redraw:complete', (result) => {
+  if (result.isTimeout) {
+    console.warn('Redraw timed out after', result.timeElapsed, 'ms');
+  }
+});
+```
+
+### File Events
+
+Emitted during file load/save operations in the agent.
+
+| Event | Payload |
+|---|---|
+| `file:start` | `{ operation: "load" \| "save" \| "run", filePath, timestamp }` |
+| `file:stop` | `{ operation, filePath, duration, success, sourceMap?, reason?, timestamp }` |
+| `file:load` | `{ filePath, size, timestamp }` |
+| `file:save` | `{ filePath, size, timestamp }` |
+| `file:diff` | `{ filePath, diff: { patches, sourceMaps, summary: { additions, deletions, modifications } }, timestamp }` |
+| `file:error` | `{ operation, filePath, error, duration?, timestamp }` |
+
+### Error Events
+
+Emitted for errors at various severity levels.
+
+| Event | Payload |
+|---|---|
+| `error:fatal` | `(error: string \| Error)` — terminates the process |
+| `error:general` | `(message: string)` — non-fatal error |
+| `error:sandbox` | `(err: Error \| string)` — sandbox/WebSocket error |
+
+```javascript
+testdriver.emitter.on('error:*', function (err) {
+  console.error(`[${this.event}]`, err);
+});
+```
+
+### SDK Events
+
+Emitted for API request lifecycle.
+
+| Event | Payload |
+|---|---|
+| `sdk:request` | `{ path }` — outgoing API request |
+| `sdk:response` | `{ path }` — API response received |
+| `sdk:retry` | `{ path, attempt, error, delayMs }` — request retry |
+
+### Other Events
+
+| Event | Payload |
+|---|---|
+| `exit` | `(exitCode: number)` — `0` for success, `1` for failure |
+| `status` | `(message: string)` — general status updates |
+| `mouse-click` | `{ x, y, button, click, double }` — mouse click performed |
+| `terminal:stdout` | Terminal stdout output |
+| `terminal:stderr` | Terminal stderr output |
+
+## Practical Examples
+
+### Custom Test Reporter
+
+```javascript
+const results = [];
+
+testdriver.emitter.on('command:success', ({ command, duration }) => {
+  results.push({ command, duration, status: 'pass' });
+});
+
+testdriver.emitter.on('command:error', ({ command, duration, error }) => {
+  results.push({ command, duration, status: 'fail', error });
+});
+
+// After test completes
+afterAll(() => {
+  console.table(results);
+});
+```
+
+### Progress Monitoring
+
+```javascript
+testdriver.emitter.on('step:start', ({ stepIndex, prompt }) => {
+  process.stdout.write(`\r  Step ${stepIndex}: ${prompt}`);
+});
+
+testdriver.emitter.on('command:progress', ({ command, timing }) => {
+  process.stdout.write(`\r  ${command} completed in ${timing}ms`);
+});
+```
+
+### Debug Logging
+
+```javascript
+// Log every event (verbose)
+testdriver.emitter.on('**', function (...args) {
+  console.debug(`[EVENT] ${this.event}`, ...args);
+});
+```
+
+## Types
+
+```typescript
+interface CommandStartEvent {
+  command: string;
+  depth: number;
+  data: Record<string, any>;
+  timestamp: number;
+  sourcePosition: SourcePosition;
+}
+
+interface CommandSuccessEvent {
+  command: string;
+  depth: number;
+  data: Record<string, any>;
+  duration: number;
+  response: any;
+  timestamp: number;
+  sourcePosition: SourcePosition;
+}
+
+interface CommandErrorEvent {
+  command: string;
+  depth: number;
+  data: Record<string, any>;
+  error: string;
+  duration: number;
+  timestamp: number;
+  sourcePosition: SourcePosition;
+}
+
+interface StepStartEvent {
+  stepIndex: number;
+  prompt: string;
+  commandCount: number;
+  timestamp: number;
+  sourcePosition: SourcePosition;
+}
+
+interface StepSuccessEvent {
+  stepIndex: number;
+  prompt: string;
+  commandCount: number;
+  duration: number;
+  timestamp: number;
+  sourcePosition: SourcePosition;
+}
+
+interface RedrawStatusEvent {
+  redraw: {
+    enabled: boolean;
+    settled: boolean;
+    hasChangedFromInitial: boolean;
+    consecutiveFramesStable: number;
+    diffFromInitial: number;
+    diffFromLast: number;
+    text: string;
+  };
+  network: {
+    enabled: boolean;
+    settled: boolean;
+    rxBytes: number;
+    txBytes: number;
+    text: string;
+  };
+  timeout: {
+    isTimeout: boolean;
+    elapsed: number;
+    max: number;
+    text: string;
+  };
+}
+
+interface RedrawCompleteEvent {
+  screenSettled: boolean;
+  hasChangedFromInitial: boolean;
+  consecutiveFramesStable: number;
+  networkSettled: boolean;
+  isTimeout: boolean;
+  timeElapsed: number;
+}
+
+interface SandboxProgressEvent {
+  step: string;
+  message: string;
+}
+
+interface SourcePosition {
+  file: string;
+  line: number;
+  column: number;
+}
+```

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

@@ -0,0 +1,7 @@
+---
+name: testdriver:mcp
+description: mcp
+---
+<!-- Generated from mcp.mdx. DO NOT EDIT. -->
+
+

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();
+  });
+});
+```