testdriverai 7.8.0-test.7 → 7.8.0-test.71

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-find/SKILL.md

@@ -49,8 +49,8 @@ const element = await testdriver.find(description, options)
       - `"any"` — No wrapping, uses the description as-is (default behavior)
     </ParamField>
     
-    <ParamField path="zoom" type="boolean" default={false}>
-      Enable two-phase zoom mode for better precision in crowded UIs with many similar elements.
+    <ParamField path="zoom" type="boolean" default={true}>
+      Two-phase zoom mode for better precision in crowded UIs with many similar elements. Enabled by default.
     </ParamField>
     
     <ParamField path="ai" type="object">
@@ -332,14 +332,19 @@ The `timeout` option:
 - Returns the element (check `element.found()` if not throwing on failure)
 - Set to `0` to disable polling and make a single attempt
 
-## Zoom Mode for Crowded UIs
+## Zoom Mode
 
-When dealing with many similar icons or elements clustered together (like browser toolbars), enable `zoom` mode for better precision:
+Zoom mode is **enabled by default**. It uses a two-phase approach for better precision when locating elements, especially in crowded UIs with many similar elements.
+
+To disable zoom for a specific find call, pass `zoom: false`:
 
 ```javascript
-// Enable zoom for better precision in crowded UIs
-const extensionsBtn = await testdriver.find('extensions puzzle icon in Chrome toolbar', { zoom: true });
+// Zoom is on by default — no option needed
+const extensionsBtn = await testdriver.find('extensions puzzle icon in Chrome toolbar');
 await extensionsBtn.click();
+
+// Disable zoom for a specific call if needed
+const largeButton = await testdriver.find('big hero button', { zoom: false });
 ```
 
 ### How Zoom Mode Works
@@ -352,22 +357,11 @@ await extensionsBtn.click();
 This two-phase approach gives the AI a higher-resolution view of the target area, improving accuracy when multiple similar elements are close together.
 
 <Tip>
-  Use `zoom: true` when:
-  - Clicking small icons in toolbars
-  - Selecting from a grid of similar items
-  - Targeting elements in dense UI areas
-  - The default locate is clicking the wrong similar element
-  - You get an AI verification rejection like "The crosshair is located in the empty space of the browser's tab bar/title bar area" — this means the initial locate was imprecise and zoom will help the AI pinpoint the correct element
+  You may want to disable zoom with `zoom: false` when:
+  - Targeting large, isolated elements where the extra precision isn't needed
+  - You want to speed up find calls in simple UIs
 </Tip>
 
-```javascript
-// Without zoom - may click wrong icon in toolbar
-const icon = await testdriver.find('settings icon');
-
-// With zoom - better precision for crowded areas
-const icon = await testdriver.find('settings icon', { zoom: true });
-```
-
 ## Cache Options
 
 Control caching behavior to optimize performance, especially when using dynamic variables in prompts.

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

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