@testdriverai/agent 7.11.240-test → 7.11.241-canary

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

@@ -1,214 +1,150 @@
 ---
 name: testdriver:redraw
-description: Wait for the screen to stabilize after interactions
+description: Make actions wait until the screen stops changing before the next step runs.
 ---
 <!-- Generated from redraw.mdx. DO NOT EDIT. -->
 
-## Overview
+Redraw detection makes each action wait until the screen has changed and then stopped changing.
 
-The redraw system waits for the screen to become stable after an interaction. Then it continues. It finds when animations, page loads, and network requests are complete. This stops actions on a screen that changes.
+- Use it for apps with animations, page transitions, or content that loads after a click.
+- It's off by default. Without it, the next command runs as soon as the action is sent.
+- It can also wait for network traffic in the sandbox to die down.
 
-<Note>
-  **Redraw is disabled by default from v7.3.** Enable it if your tests interact with applications that have many animations or load states.
-</Note>
+## Turn it on
 
-## How It Works
+Pass `redraw: true` when you create the client:
 
-Redraw uses a **two-phase detection** method:
+```javascript tests/search.test.mjs
+import { describe, expect, it } from 'vitest';
+import { TestDriver } from 'testdriverai/vitest/hooks';
 
-1. **Change Detection**. TestDriver compares the present frame to the first screenshot from after the action. If the pixel diff is more than 0.1%, the screen changed.
-2. **Stability Detection** — TestDriver compares frames that come after each other with z-score analysis. When the diff between frames is less than 0.1%, or the z-score is negative (the present diff is less than the average), the screen is complete.
+describe('Search', () => {
+  it('shows results after searching', async (context) => {
+    const testdriver = TestDriver(context, { redraw: true });
+    await testdriver.provision.chrome({ url: 'https://testdriver-sandbox.vercel.app/login' });
 
-The screen is **complete** when both phases finish: the screen changed from the first state AND the frames that come after each other are now stable.
+    // With redraw on, click() returns once the error message has finished drawing
+    await testdriver.find('Sign in button below the password field').click();
 
-```mermaid
-flowchart TD
-    A[Action performed] --> B{Phase 1: Change Detection\ndiffFromInitial > 0.1%?}
-    B -- "Yes (screen changed)" --> C{Phase 2: Stability\nz-score < 0 or\ndiffPercent < 0.1%?}
-    C -- "Yes (frames stable)" --> D[Screen settled ✓]
-    B -- "No (waiting...)" --> B
-    C -- "No (waiting...)" --> C
+    const result = await testdriver.assert('an error says the fields are required');
+    expect(result).toBe(true);
+  });
+});
 ```
 
-### Polling
-
-The system polls at **500ms intervals**, comparing screenshot frames. This reduces WebSocket traffic while still providing responsive detection.
-
-### Pixel Comparison
-
-Uses [pixelmatch](https://github.com/mapbox/pixelmatch) for per-pixel comparison with a threshold of `0.1` for pixel sensitivity. A frame diff above **0.1% of total pixels** indicates the screen has changed.
-
-### Z-Score Analysis
+Every click, hover, type, key press, scroll, and `focusApplication()` call now waits for the screen to settle.
 
-Screen stability uses statistical analysis of the last **10 measurements**:
+## What it waits for
 
-1. Calculate the mean and standard deviation of consecutive frame diffs
-2. Compute the z-score: `(currentDiff - mean) / stddev`
-3. Screen is stable when `diffPercent < 0.1%` or `z-score < 0` (current diff is below the average)
+TestDriver takes a small screenshot right before the action, then one every 500 ms after it. The screen counts as settled when both of these are true:
 
-This approach adapts to the specific animation patterns of your application rather than using a fixed threshold.
+1. **The screen changed.** A frame differs from the "before" screenshot by more than 0.1% of its pixels.
+2. **The screen stopped changing.** The latest frame differs from the previous one by less than 0.1%, or by less than the average of the last 10 frames.
 
-## Per-Command Timeouts
+If the screen doesn't settle in time, the command carries on anyway. It doesn't throw.
 
-Each command type has a specific redraw timeout:
+| Command | Waits at most |
+| --- | --- |
+| `click()`, `doubleClick()`, `rightClick()`, `mouseDown()`, `mouseUp()` | 5 s |
+| `hover()` | 2.5 s |
+| `type()` | 5 s |
+| `pressKeys()` | 5 s |
+| `scroll()` | 5 s |
+| `focusApplication()` | 1 s |
 
-| Command | Timeout | Reason |
-|---------|---------|--------|
-| `click` | 5000ms | Page navigations, modal openings |
-| `hover` (within click) | 5000ms | Same as click |
-| `hover` (standalone) | 2500ms | Tooltip animations |
-| `scroll` | 5000ms | Lazy-loaded content |
-| `type` | 5000ms | Autocomplete, validation |
-| `pressKeys` | 5000ms | Keyboard shortcuts may trigger changes |
-| `focusApplication` | 1000ms | Window focus animations |
+<Warning>
+  An action that doesn't change the screen never meets the first condition. It waits the full timeout, such as 5 seconds for a click. Turn redraw off for those commands (see below) or leave it off and use [`wait()`](/wait) where you need it.
+</Warning>
 
-If the timeout is reached before the screen settles, the command continues anyway. The timeout event is available via the `redraw:complete` event.
+## Wait for network traffic too
 
-## Configuration
-
-### Constructor Options
+Set `thresholds.network` to also wait until the sandbox's network traffic drops below its recent average:
 
 ```javascript
-const testdriver = new TestDriver({
-  // Shorthand: enable/disable
-  redraw: true,    // enable with defaults
-  redraw: false,   // disable (default since v7.3)
-
-  // Full configuration
-  redraw: {
-    enabled: true,
-    screenRedraw: true,       // enable screen pixel diff detection
-    networkMonitor: false,    // enable network settling detection
-  },
+const testdriver = TestDriver(context, {
+  redraw: { thresholds: { network: true } },
 });
 ```
 
-<ParamField path="redraw" type="RedrawConfig | boolean" default={false}>
-  Redraw configuration. Pass `true`/`false` for shorthand, or an object for fine-grained control.
+TestDriver then waits for both the screen and the network to settle, within the same timeouts.
+
+To wait for the network only, turn off the screen check with `thresholds: { screen: false, network: true }`.
+
+## Options
+
+<ParamField path="redraw" type="boolean | object" default="false">
+  `true` turns on screen detection. Pass an object to choose what to wait for.
 
   <Expandable title="properties">
-    <ParamField path="enabled" type="boolean" default={false}>
-      Enable or disable the redraw system. Default changed to `false` in v7.3.
+    <ParamField path="enabled" type="boolean" default="true">
+      Whether redraw detection is on when you pass an object.
     </ParamField>
-    
-    <ParamField path="screenRedraw" type="boolean" default={true}>
-      Enable pixel-diff-based screen change detection. If both `screenRedraw` and `networkMonitor` are `false`, redraw auto-disables.
-    </ParamField>
-    
-    <ParamField path="networkMonitor" type="boolean" default={false}>
-      Enable network traffic monitoring for settling detection. Monitors WebSocket traffic on the sandbox to detect when network activity subsides.
+    <ParamField path="thresholds" type="object">
+      <Expandable title="properties">
+        <ParamField path="screen" type="number | false">
+          Set to `false` to skip the screen check. Any other value leaves it on. The 0.1% change threshold is fixed.
+        </ParamField>
+        <ParamField path="network" type="boolean" default="false">
+          Also wait for network traffic in the sandbox to settle.
+        </ParamField>
+      </Expandable>
     </ParamField>
   </Expandable>
 </ParamField>
 
-### Per-Command Override
+<Note>
+  Older tests may use `redrawThreshold`, or `diffThreshold`, `screenRedraw`, and `networkMonitor` inside `redraw`. They still work, but are deprecated. Use `redraw` with `thresholds` instead.
+</Note>
+
+## Override it for one command
 
-Override redraw settings for individual commands:
+The client's action methods accept a `redraw` object as an option. It applies to that call only:
 
 ```javascript
-// Enable redraw for a specific click
-await testdriver.find('load more').click({
-  redraw: { enabled: true },
-});
+// Wait for this key press even though redraw is off for the client
+await testdriver.pressKeys(['enter'], { redraw: { enabled: true } });
 
-// Disable redraw for a fast interaction
-await testdriver.find('checkbox').click({
-  redraw: false,
-});
+// Skip the wait for a click you know changes nothing on screen
+await testdriver.click({ x: 640, y: 360, redraw: { enabled: false } });
 ```
 
-## Network Settling
-
-When `networkMonitor` is enabled, the system also monitors sandbox network traffic:
+This works on `testdriver.click()`, `hover()`, `type()`, `pressKeys()`, `scroll()`, and `focusApplication()`.
 
-- Polls for `totalBytesReceived` and `totalBytesSent` from the sandbox
-- Keeps the last **60 measurements**
-- Calculates z-scores for both RX and TX byte rates
-- Network is **settled** when both RX and TX z-scores are negative (traffic is below average)
-- Has a **10-second timeout** for network polling
-- Non-critical: network errors are logged but never throw
+- Pass an object. A per-command `redraw: true` or `redraw: false` is ignored.
+- Element methods such as `element.click()` don't take options. They always use the client's setting.
 
-The final settling condition requires **both** screen AND network to be settled (when both are enabled).
+## Watch it work
 
-## Events
+Redraw emits two events on the client's [event emitter](/events#redraw-events):
 
-The redraw system emits events through the SDK emitter. See [Events](/events) for the full event reference.
-
-| Event | Description |
-|---|---|
-| `redraw:status` | Emitted on each poll with current screen diff, network stats, and timeout info |
-| `redraw:complete` | Emitted when redraw resolves (settled or timed out) |
+- `redraw:status` on every check, with the current screen and network state.
+- `redraw:complete` when the wait ends, with `isTimeout` and `timeElapsed`.
 
 ```javascript
-testdriver.emitter.on('redraw:status', (status) => {
-  console.log(`Screen: ${status.redraw.text}`);
-  console.log(`Network: ${status.network.text}`);
-  console.log(`Timeout: ${status.timeout.text}`);
-});
-
-testdriver.emitter.on('redraw:complete', (result) => {
-  if (result.isTimeout) {
-    console.warn(`Redraw timed out after ${result.timeElapsed}ms`);
-  } else {
-    console.log(`Screen settled in ${result.timeElapsed}ms`);
+testdriver.getEmitter().on('redraw:complete', ({ isTimeout, timeElapsed }) => {
+  if (isTimeout) {
+    console.warn(`Screen didn't settle within ${timeElapsed} ms`);
   }
 });
 ```
 
-## When to Use Redraw
-
-**Enable redraw when:**
-- Testing single-page applications (SPAs) with route transitions
-- Interacting with pages that lazy-load content on scroll
-- Clicking buttons that trigger animations or modals
-- Testing apps with significant network-driven UI updates
-
-**Keep redraw disabled when:**
-- Tests are already stable without it
-- You want faster test execution
-- Your application has minimal animations
-- You're using explicit waits or assertions instead
-
-## Types
-
-```typescript
-interface RedrawConfig {
-  enabled?: boolean;              // Default: false (since v7.3)
-  screenRedraw?: boolean;         // Default: true
-  networkMonitor?: boolean;       // Default: false
-}
-
-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;
-}
-```
+## When to use it
+
+Turn redraw on when:
+
+- Clicks open pages, modals, or menus that animate in.
+- Scrolling loads more content.
+- Typing triggers autocomplete or validation messages.
+
+Leave it off when:
+
+- Your tests already pass reliably without it. Each action takes longer with it on.
+- Many actions don't visibly change the screen.
+- You already wait with `find()` and a `timeout`, which keeps looking until the element appears.
+
+## Related
+
+- [Options](/options#redraw-detection): every client option
+- [Events](/events): the full list of events
+- [wait()](/wait): pause for a fixed time
+- [Locate elements](/locating-elements): wait for an element to appear with `find()`