@testdriverai/agent 7.11.229-canary → 7.11.231-test

package/docs/quickstart-manual.mdx

@@ -1,28 +1,49 @@
 ---
-title: "Manual"
+title: "Set up a project"
 sidebarTitle: "Setting up your workspace"
-description: "Add TestDriver to an existing project by hand."
+description: "Add TestDriver to your own project and run your first Vitest test."
 icon: "wrench"
 ---
 
-Add TestDriver to an existing project without the `init` scaffold. This is useful when you already have a Vitest setup or want full control over each file.
+Add TestDriver to a new or existing project, then run your first test.
+
+- **Fastest:** run `npx testdriverai init` and let it create every file for you.
+- **By hand:** follow the steps below to see exactly what each file does.
 
 <Tip>
-If you only want to drive TestDriver from chat, [MCP Setup](/mcp-setup) is a single URL with nothing to install.
+  Only want to drive TestDriver from chat? [MCP setup](/mcp-setup) needs one URL and nothing installed.
 </Tip>
 
+## Set up with init
+
+Run `init` in your project folder:
+
+```bash
+npx testdriverai init
+```
+
+It signs you in and saves your API key to `.env`. It then adds:
+
+- A `package.json`, if you don't have one
+- `vitest.config.js` with the TestDriver reporter
+- An example test in `tests/`
+- A GitHub Actions workflow
+- The TestDriver agent and MCP server for your AI client
+
+`init` keeps your existing `package.json`, Vitest config, tests, and workflow. It only adds to `.gitignore` and to MCP config files.
+
+Then run the example:
+
+```bash
+npx vitest run
+```
+
+## Set up by hand
+
 <Steps>
-  <Step title="Get an API key">
-
-    <Card
-      title="Get an API Key"
-      icon="user-plus"
-      href="https://console.testdriver.ai/settings"
-      arrow
-      horizontal
-    >
-      Start with 60 free device minutes, no credit card required.
-    </Card>
+  <Step title="Add your API key">
+
+    Create an API key at [console.testdriver.ai/team/api-keys](https://console.testdriver.ai/team/api-keys). The free plan includes 30 testing minutes and needs no credit card.
 
     Save the key in a `.env` file at your project root. The SDK loads it automatically:
 
@@ -30,7 +51,7 @@ If you only want to drive TestDriver from chat, [MCP Setup](/mcp-setup) is a sin
     TD_API_KEY=your_api_key
     ```
 
-    Add `.env` to `.gitignore` so the key is not committed.
+    Add `.env` to `.gitignore` so the key isn't committed.
 
   </Step>
   <Step title="Install dependencies">
@@ -41,14 +62,12 @@ If you only want to drive TestDriver from chat, [MCP Setup](/mcp-setup) is a sin
     npm install --save-dev vitest testdriverai
     ```
 
-    <Note>
-    TestDriver requires Node.js 20.19 or later and only runs on [Vitest](https://vitest.dev). Jest, Mocha, and other runners are not supported.
-    </Note>
+    TestDriver needs Node.js 20.19 or later. It only runs on [Vitest](https://vitest.dev), not Jest, Mocha, or other runners.
 
   </Step>
   <Step title="Configure Vitest">
 
-    Create `vitest.config.js` at your project root (or add these settings to an existing one):
+    Create `vitest.config.js` at your project root, or add these settings to your existing config:
 
     ```js vitest.config.js
     import { defineConfig } from 'vitest/config';
@@ -65,9 +84,9 @@ If you only want to drive TestDriver from chat, [MCP Setup](/mcp-setup) is a sin
     });
     ```
 
-    - `TestDriver()` reporter uploads results, recordings, and screenshots to the console.
-    - `setupFiles` registers the hooks that connect each test to a sandbox and clean it up.
-    - Without `hookTimeout`, cleanup fails at Vitest's default 10-second limit.
+    - **`TestDriver()`** is the reporter. It records each run in the TestDriver console, with its recording.
+    - **`setupFiles`** links your tests to the reporter, so each test's recording attaches to the run.
+    - **The timeouts** must be long. Vitest's defaults (5 seconds for tests, 10 for hooks) are too short for a real machine.
 
   </Step>
   <Step title="Write a test">
@@ -99,37 +118,45 @@ If you only want to drive TestDriver from chat, [MCP Setup](/mcp-setup) is a sin
     });
     ```
 
-    If your project does not have `"type": "module"` in `package.json`, name the file `search.test.mjs` instead.
+    If your `package.json` doesn't set `"type": "module"`, name the file `search.test.mjs` instead.
 
   </Step>
   <Step title="Run the test">
 
     ```bash
-    vitest run
+    npx vitest run
     ```
 
-    A sandbox starts, Chrome opens, and a live preview appears in your browser. When the run finishes, open the `TESTDRIVER_RUN_URL` printed at the end of the output to see the recording and step-by-step screenshots.
+    A sandbox starts, Chrome opens, and a live preview appears in your browser.
+
+    When the run finishes, open the `TESTDRIVER_RUN_URL` link at the end of the output. It shows the recording and each step.
 
   </Step>
 </Steps>
 
-## Optional: AI client setup
+## Connect an AI assistant
 
-If you want to write tests with an AI assistant, connect the TestDriver agent and MCP server. You can do this without re-scaffolding the project:
+To write tests with an AI assistant, add the TestDriver agent and MCP server to your project. `--no-sample-test` skips the example test files:
 
 ```bash
 npx testdriverai init --client cursor,claude-code,vscode --no-sample-test
 ```
 
-See [MCP Setup](/mcp-setup) for the configuration of each client.
+Your existing config and tests stay as they are. For Claude Code or VS Code, you can use the [plugin](/quickstart-claude) or [extension](/quickstart-vscode) instead.
 
 ## Next steps
 
 <CardGroup cols={2}>
-  <Card title="Walkthrough" icon="map" href="/provision" arrow horizontal>
-    Provision apps, locate elements, perform actions, and make assertions.
+  <Card title="Launch apps" icon="rocket" href="/provision">
+    Start Chrome, extensions, VS Code, or desktop apps.
+  </Card>
+  <Card title="Perform actions" icon="arrow-pointer" href="/performing-actions">
+    Click, type, scroll, and wait for a changing UI.
+  </Card>
+  <Card title="Make assertions" icon="circle-check" href="/making-assertions">
+    Check what's on screen in plain language.
   </Card>
-  <Card title="CI/CD" icon="github" href="/ci-cd" arrow horizontal>
-    Run tests on every pull request with GitHub Actions or another provider.
+  <Card title="Run in CI/CD" icon="code-branch" href="/ci-cd">
+    Run your tests on every pull request.
   </Card>
 </CardGroup>

package/docs/quickstart-vscode.mdx

@@ -0,0 +1,97 @@
+---
+title: "Add TestDriver to VS Code and Cursor"
+sidebarTitle: "VS Code & Cursor"
+description: "Set up TestDriver in your editor and watch tests run in a live preview panel."
+icon: "code"
+---
+
+Install the TestDriver extension, and your editor's AI assistant can write and run end-to-end tests. You watch the sandbox in a panel beside your code.
+
+The extension:
+
+- Signs you in.
+- Sets up your project and MCP server.
+- Opens the live preview automatically whenever a test runs.
+
+## Before you begin
+
+- **VS Code 1.85 or later with GitHub Copilot**, or **Cursor**.
+- **Node.js 20.19 or later**, which runs the MCP server and your tests.
+- **A workspace folder open** in the editor, since the extension sets up TestDriver in it.
+
+<Steps>
+  <Step title="Install the extension">
+
+    Install [TestDriver.ai from the VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=testdriver.testdriver), or search for **TestDriver.ai** in the Extensions view.
+
+    In Cursor, the extension may not appear in search. If so, download it with **Download Extension** on the Marketplace page. Then run **Extensions: Install from VSIX** from the Command Palette and choose the file.
+
+  </Step>
+  <Step title="Sign in">
+
+    Run **TestDriver: Sign In** from the Command Palette. It opens your browser, signs you in to TestDriver, and saves your API key in the editor.
+
+  </Step>
+  <Step title="Set up your project">
+
+    Run **TestDriver: Initialize Project**. It writes your API key to `.env` and runs `npx testdriverai init`, which installs the SDK and adds:
+
+    - An example test
+    - The TestDriver agent and skills
+    - A Vitest config
+    - A GitHub Actions workflow
+
+  </Step>
+  <Step title="Connect the MCP server">
+
+    Run **TestDriver: Install MCP Server** and choose where to save it: `.vscode/mcp.json` for VS Code or `.cursor/mcp.json` for Cursor.
+
+    If it asks whether to overwrite an existing TestDriver entry, choose **Yes**. This version of the config turns on the live preview panel.
+
+  </Step>
+  <Step title="Write your first test">
+
+    In VS Code, run **TestDriver: Chat with Agent**. It opens Copilot chat with the TestDriver agent and a sample prompt.
+
+    In Cursor, open the chat and ask:
+
+    ```text
+    Use TestDriver to write a test that logs in to https://testdriver-sandbox.vercel.app/login and adds an item to the cart.
+    ```
+
+    The live preview panel opens as the agent starts the sandbox. The agent writes the test under `tests/` as it goes.
+
+  </Step>
+</Steps>
+
+## Extension commands
+
+| Command | What it does |
+| --- | --- |
+| **TestDriver: Sign In** | Signs in through your browser and saves your API key |
+| **TestDriver: Set API Key** | Saves an API key you paste in instead |
+| **TestDriver: Initialize Project** | Runs `npx testdriverai init` in the workspace |
+| **TestDriver: Install MCP Server** | Adds the TestDriver MCP server to `.vscode/mcp.json` or `.cursor/mcp.json` |
+| **TestDriver: Chat with Agent** | Opens the TestDriver agent in Copilot chat (VS Code) |
+| **TestDriver: Turn into Repeatable Test** | Asks Copilot to turn your session into a test with a GitHub Actions workflow |
+| **TestDriver: Open Live Preview** / **Close Live Preview** | Opens or closes the sandbox preview panel |
+| **TestDriver: Open Getting Started** | Opens the extension's setup walkthrough |
+
+The preview panel opens automatically when a test starts. To turn that off, set `testdriverai.autoOpenPreview` to `false` in your settings.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Generate tests with AI" icon="compass" href="/generating-tests">
+    Prompt the agent and steer it while it works.
+  </Card>
+  <Card title="Run tests" icon="play" href="/copilot/running-tests">
+    Run tests from the editor or the terminal.
+  </Card>
+  <Card title="Make assertions" icon="circle-check" href="/making-assertions">
+    Check what's on screen in plain language.
+  </Card>
+  <Card title="Run in CI/CD" icon="code-branch" href="/ci-cd">
+    Run your tests on every pull request.
+  </Card>
+</CardGroup>

package/docs/quickstart.mdx

@@ -1,22 +1,38 @@
 ---
-title: "Quick Start"
+title: "Quickstart"
 sidebarTitle: "Quickstart"
-description: "Run your first computer-use test in minutes."
+description: "Start with TestDriver from GitHub, Claude Code, VS Code, Cursor, any MCP client, or your own project."
 icon: "rocket"
 ---
 
-TestDriver writes and runs computer-use tests for web apps, desktop apps, and browser extensions. Tests describe what a user sees and does in plain English, and run on real machines in the cloud. Pick the path that fits how you work:
+TestDriver writes and runs end-to-end tests for web apps, desktop apps, and browser extensions.
+
+Each test describes what a user sees and does in plain language. It runs on a real machine in the cloud.
+
+Choose where you want to start:
 
 <CardGroup cols={1}>
   <Card title="Add to GitHub" icon="github" href="/quickstart-github" arrow horizontal>
-    No install. Mention `@testdriverai` in a PR or issue and it writes, runs, and commits tests for you.
+    An AI code reviewer that tests every pull request in a real sandbox.
+  </Card>
+  <Card title="Claude Code" icon="terminal" href="/quickstart-claude" arrow horizontal>
+    Install the plugin to write and run tests from Claude Code.
   </Card>
-  <Card title="MCP Setup" icon="plug" href="/mcp-setup" arrow horizontal>
-    Add one URL to Claude, Cursor, VS Code, ChatGPT, or any MCP client. No install, no API key.
+  <Card title="VS Code & Cursor" icon="code" href="/quickstart-vscode" arrow horizontal>
+    Install the extension to write tests and watch them run live.
   </Card>
-  <Card title="Manual" icon="wrench" href="/quickstart-manual" arrow horizontal>
-    Add TestDriver to an existing Vitest project file by file.
+  <Card title="Connect your AI client" icon="plug" href="/mcp-setup" arrow horizontal>
+    Add one URL to any MCP client, such as Claude or ChatGPT.
+  </Card>
+  <Card title="Set up a project" icon="wrench" href="/quickstart-manual" arrow horizontal>
+    Write and run Vitest tests in your own repository.
   </Card>
 </CardGroup>
 
-<Tip><a href="https://discord.com/invite/cWDFW8DzPm" target="_blank" rel="noreferrer">Join our Discord</a> if you have questions or get stuck.</Tip>
+Not sure? Start with GitHub. Your next pull request gets a review without any setup.
+
+Set up a project when you want to write and run tests yourself.
+
+<Tip>
+  Questions along the way? Ask in the [TestDriver Discord](https://discord.com/invite/cWDFW8DzPm).
+</Tip>

package/docs/redraw.mdx

@@ -1,216 +1,152 @@
 ---
-title: "Redraw"
+title: "Wait for the screen to settle"
 sidebarTitle: "Redraw"
-description: "Wait for the screen to stabilize after interactions"
+description: "Make actions wait until the screen stops changing before the next step runs."
 icon: "rotate"
 mode: "wide"
 ---
 
-## 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()`