@testdriverai/agent 7.11.229-test → 7.11.231-test

package/docs/docs.json

@@ -16,34 +16,36 @@
       {
         "group": "Overview",
         "pages": [
-          "/agent",
-          "/what-is-testdriver",
           {
-            "group": "Quickstart",
+            "group": "Get started",
             "icon": "rocket",
             "pages": [
               "/quickstart",
               "/quickstart-github",
+              "/quickstart-claude",
+              "/quickstart-vscode",
               "/mcp-setup"
             ]
           },
+          "/agent",
+          "/what-is-testdriver",
           {
             "group": "Examples",
             "icon": "code",
             "pages": [
               "/examples/assert",
-              "/examples/element-not-found",
-              "/examples/findall-coffee-icons",
-              "/examples/hover-image",
-              "/examples/hover-text-with-description",
-              "/examples/hover-text",
-              "/examples/installer",
-              "/examples/launch-vscode-linux",
-              "/examples/parse",
+              "/examples/type",
+              "/examples/click-button",
+              "/examples/click-icon",
+              "/examples/add-to-cart",
               "/examples/press-keys",
-              "/examples/scroll-keyboard",
               "/examples/scroll",
-              "/examples/type"
+              "/examples/navigate-and-scroll",
+              "/examples/findall-coffee-icons",
+              "/examples/element-not-found",
+              "/examples/parse",
+              "/examples/installer",
+              "/examples/launch-vscode-linux"
             ]
           }
         ]
@@ -52,15 +54,15 @@
         "group": "Using TestDriver",
         "pages": [
           "/generating-tests",
+          "/performing-actions",
           "/copilot/running-tests",
           "/debugging-with-screenshots",
           "/caching",
-          "/performing-actions",
           "/copilot/auto-healing"
         ]
       },
       {
-        "group": "Building & Maintaining Tests",
+        "group": "Building & maintaining tests",
         "pages": [
           "/quickstart-manual",
           {
@@ -114,7 +116,6 @@
             "group": "Integrations",
             "icon": "plug",
             "pages": [
-              "/github",
               "/ci-cd"
             ]
           },
@@ -124,7 +125,7 @@
             "pages": [
               "/hosted",
               {
-                "group": "Self-Hosting",
+                "group": "Self-hosting",
                 "icon": "server",
                 "pages": [
                   "/self-hosted",
@@ -137,7 +138,7 @@
         ]
       },
       {
-        "group": "Advanced Topics",
+        "group": "Advanced topics",
         "pages": [
           "/variables",
           "/secrets",
@@ -548,6 +549,62 @@
     {
       "source": "/v7/:slug*",
       "destination": "/:slug*"
+    },
+    {
+      "source": "/examples/hover-image",
+      "destination": "/examples/click-icon"
+    },
+    {
+      "source": "/examples/hover-text",
+      "destination": "/examples/click-button"
+    },
+    {
+      "source": "/examples/hover-text-with-description",
+      "destination": "/examples/add-to-cart"
+    },
+    {
+      "source": "/examples/scroll-keyboard",
+      "destination": "/examples/navigate-and-scroll"
+    },
+    {
+      "source": "/examples/ai",
+      "destination": "/generating-tests"
+    },
+    {
+      "source": "/examples/captcha-api",
+      "destination": "/captcha"
+    },
+    {
+      "source": "/examples/chrome-extension",
+      "destination": "/provision"
+    },
+    {
+      "source": "/examples/drag-and-drop",
+      "destination": "/mouse-down"
+    },
+    {
+      "source": "/examples/formatted-logging",
+      "destination": "/dashcam"
+    },
+    {
+      "source": "/examples/match-image",
+      "destination": "/find"
+    },
+    {
+      "source": "/examples/scroll-until-text",
+      "destination": "/scroll"
+    },
+    {
+      "source": "/claude-mcp-plugin",
+      "destination": "/quickstart-claude"
+    },
+    {
+      "source": "/github",
+      "destination": "/quickstart-github"
+    },
+    {
+      "source": "/elements",
+      "destination": "/find"
     }
   ],
   "integrations": {

package/docs/double-click.mdx

@@ -1,102 +1,82 @@
 ---
-title: "doubleClick"
-description: "Perform a double-click action on an element or at specific coordinates"
+title: "doubleClick()"
+sidebarTitle: "doubleClick"
+description: "Double-click an element you found, for example to open a file or select a word."
 icon: "hand-pointer"
 ---
 
-## Overview
-
-The `doubleClick()` method does a double-click action on an element. You can call it on an [`Element`](/core-concepts/elements) instance. Or you can use it with a selector.
-
-## Syntax
+Double-click an element you've located with [`find()`](/find):
 
 ```javascript
-// Double-click on an element
-await element.doubleClick();
-
-// Double-click using a selector
-await ai.doubleClick('selector');
+await testdriver.find('report.pdf in the file list').doubleClick();
 ```
 
-## Parameters
+## element.doubleClick()
 
-When called on an `Element`, no parameters are required.
+Double-clicks the element at the point where `find()` located it. It's the same as `element.click('double-click')`.
 
-When called directly on the AI client:
+```typescript
+element.doubleClick(): Promise<void>
+```
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `selector` | `string` | The selector describing the element to double-click |
+It takes no parameters.
 
-## Returns
+### Errors
 
-It returns a `Promise<void>`. The promise resolves when the double-click action completes.
+Throws an `ElementNotFoundError` if `find()` didn't locate the element. See [click()](/click#errors) for how to check `found()` first.
 
-## Examples
+## Double-click at coordinates
 
-### Double-Click on Found Element
+The client has no `doubleClick()` method. To double-click a point on the screen, pass `action: 'double-click'` to [`testdriver.click()`](/click#testdriver-click-options):
 
 ```javascript
-const fileItem = await ai.find('README.md file');
-await fileItem.doubleClick();
+await testdriver.click({ x: 640, y: 360, action: 'double-click' });
 ```
 
-### Direct Double-Click with Selector
+Prefer `element.doubleClick()`, which keeps working when the layout or screen size changes.
 
-```javascript
-await ai.doubleClick('README.md in the file list');
-```
+## Examples
 
-### Opening Files in VS Code
+### Open a file in VS Code
 
 ```javascript
-import { test } from 'vitest';
-import { vscode } from '@testdriver/sdk';
-
-test('opens a file by double-clicking', async () => {
-  const { ai } = await vscode();
-  
-  // Double-click to open a file in the explorer
-  await ai.doubleClick('package.json in the file explorer');
-  
-  // Verify the file opened
-  const editor = await ai.find('text editor showing package.json');
-  expect(editor).toBeTruthy();
-});
+await testdriver.find('package.json in the Explorer sidebar').doubleClick();
+await testdriver.assert('package.json is open in the editor');
 ```
 
-### Opening Folders in File Manager
+### Select a word
 
 ```javascript
-import { test } from 'vitest';
-import { chrome } from '@testdriver/sdk';
-
-test('navigates folders in Google Drive', async () => {
-  const { ai } = await chrome('https://drive.google.com');
-  
-  // Double-click to open a folder
-  await ai.doubleClick('Documents folder');
-  
-  // Wait for folder to open
-  await ai.find('breadcrumb showing Documents');
-});
+await testdriver.find('the word "Checkout" in the page heading').doubleClick();
+await testdriver.pressKeys(['ctrl', 'c']);
 ```
 
-### Selecting Text with Double-Click
+## Complete example
 
-```javascript
-// Double-click to select a word
-await ai.doubleClick('word "TestDriver" in the paragraph');
+```javascript tests/open-file.test.mjs
+import { describe, expect, it } from 'vitest';
+import { TestDriver } from 'testdriverai/vitest/hooks';
 
-// Verify selection
-const selectedText = await ai.exec('window.getSelection().toString()');
-expect(selectedText).toBe('TestDriver');
+describe('VS Code', () => {
+  it('opens a file from the Explorer', async (context) => {
+    const testdriver = TestDriver(context);
+    await testdriver.exec({
+      language: 'sh',
+      code: 'mkdir -p /tmp/my-project && echo "{}" > /tmp/my-project/package.json',
+    });
+    await testdriver.provision.vscode({ workspace: '/tmp/my-project' });
+
+    await testdriver.find('package.json in the Explorer sidebar').doubleClick();
+
+    const result = await testdriver.assert('package.json is open in the editor');
+    expect(result).toBe(true);
+  });
+});
 ```
 
-## Related Methods
+## Related
 
-- [`click()`](/click) - Single click on an element
-- [`rightClick()`](/right-click) - Right-click to open context menu
-- [`mouseDown()`](/mouse-down) - Press mouse button without releasing
-- [`mouseUp()`](/mouse-up) - Release mouse button
-- [`hover()`](/hover) - Move mouse over element without clicking
+- [click()](/click): single clicks, and clicks at coordinates
+- [rightClick()](/right-click): open a context menu
+- [find()](/find): locate the element to double-click
+- [Perform actions](/performing-actions): every kind of action in one guide

package/docs/errors.mdx

@@ -1,248 +1,174 @@
 ---
 title: "Errors"
 sidebarTitle: "Errors"
-description: "Custom error classes and error handling"
+description: "The errors TestDriver throws, what they contain, and how to catch them."
 icon: "triangle-exclamation"
 mode: "wide"
 ---
 
-## Overview
-
-TestDriver gives custom error classes with full debug information. The SDK exports them. You can use them for `instanceof` checks in your tests.
+TestDriver exports two error classes you can check with `instanceof`:
 
 ```javascript
-import TestDriver, { ElementNotFoundError, AIError } from 'testdriverai';
+import { ElementNotFoundError, AIError } from 'testdriverai';
 ```
 
+- [`ElementNotFoundError`](#elementnotfounderror): you acted on an element that `find()` didn't locate.
+- [`AIError`](#aierror): an `ai()` task failed.
+
+Other failures, such as a failed assertion, throw a plain `Error` with a recognizable message. See [Other errors](#other-errors).
+
 ## ElementNotFoundError
 
-TestDriver throws this when `find()` cannot find an element on the screen. It also throws this when you call `click()` or `hover()` on an element that TestDriver did not find.
+Thrown when you call an action on an element that [`find()`](/find) didn't locate:
+
+- `click()`, `doubleClick()`, `rightClick()`
+- `hover()`
+- `mouseDown()`, `mouseUp()`
+
+`find()` itself doesn't throw when nothing matches. It returns an element whose `found()` is `false`. Check `found()` when the element might not be there:
 
 ```javascript
-try {
-  await testdriver.find('nonexistent button').click();
-} catch (error) {
-  if (error instanceof ElementNotFoundError) {
-    console.log(error.description);       // "nonexistent button"
-    console.log(error.screenshotPath);    // path to debug screenshot
-    console.log(error.pixelDiffPath);     // path to pixel diff image
-  }
+const cookieBanner = await testdriver.find('Cookie consent banner', { timeout: 0 });
+if (cookieBanner.found()) {
+  await testdriver.find('Accept all cookies button').click();
 }
 ```
 
 ### Properties
 
-<ParamField path="name" type="string">
+<ResponseField name="name" type="string">
   Always `"ElementNotFoundError"`.
-</ParamField>
+</ResponseField>
 
-<ParamField path="message" type="string">
-  A message with a debug block. The block has the element description, the cache status, the similarity scores, and the AI response details.
-</ParamField>
+<ResponseField name="description" type="string">
+  The description you passed to `find()`.
+</ResponseField>
 
-<ParamField path="description" type="string">
-  The original element description passed to `find()`.
-</ParamField>
+<ResponseField name="message" type="string">
+  Says which element wasn't found, followed by a debug block. See below.
+</ResponseField>
 
-<ParamField path="screenshotPath" type="string | null">
-  Absolute path to a debug screenshot saved at the time of failure. Written to `<os.tmpdir>/testdriver-debug/screenshot-<timestamp>.png`.
-</ParamField>
+<ResponseField name="aiResponse" type="object | null">
+  The response from the `find()` call, with screenshots and other large images removed. Includes fields such as `cacheHit`, `similarity`, and `reasoning` when the API returned them.
+</ResponseField>
 
-<ParamField path="pixelDiffPath" type="string | null">
-  Absolute path to a pixel diff image showing the comparison between the cached and current screenshots. Written to `<os.tmpdir>/testdriver-debug/pixel-diff-error-<timestamp>.png`. Only present when cache was involved.
-</ParamField>
+<ResponseField name="timestamp" type="string">
+  When the error was created, as an ISO 8601 string.
+</ResponseField>
 
-<ParamField path="cachedImagePath" type="string | null">
-  URL to the cached image that was compared against.
-</ParamField>
+### Message
 
-<ParamField path="aiResponse" type="object | null">
-  Sanitized AI response object. Large binary fields (`croppedImage`, `screenshot`, `pixelDiffImage`) are removed. Contains cache metadata like `similarity`, `cacheHit`, `cacheStrategy`, `cacheDiffPercent`, and `threshold`.
-</ParamField>
+The message starts with the element's description, then adds what TestDriver knows about the failed `find()`:
 
-<ParamField path="timestamp" type="string">
-  ISO 8601 timestamp of when the error was created.
-</ParamField>
+```text
+Element "Sign in button" not found.
 
-### Enhanced Message
+=== Debug Information ===
+Element searched for: "Sign in button"
+Cache: MISS
 
-The error message is automatically enhanced with debugging information:
-
-```
-Element not found: "submit button"
-
-=== Element Debug Info ===
-Element: submit button
-Cache Hit: false
-Similarity: 0.23
-Cache Strategy: pixel-diff
-Threshold: 0.05
-AI Response Element: null
+AI Response:
+The page shows a loading spinner. There is no sign in button yet.
 ```
 
-### Stack Trace Cleaning
+Depending on the `find()` call, the debug block can also include:
 
-Stack traces are automatically cleaned to remove internal SDK frames (`Element.*`, `sdk.js` internals), showing only your test code for easier debugging.
+- The cache threshold and the required similarity.
+- When the cache was hit: the cache strategy, the entry's age, and the pixel difference.
+- The similarity score, marked `(below threshold)` when it's too low.
+
+The stack trace starts at your test code, not inside the SDK.
 
 ## AIError
 
-Thrown when `act()` exhausts all retry attempts.
+Thrown when a task you give to `ai()` fails:
 
 ```javascript
+import { AIError } from 'testdriverai';
+
 try {
-  await testdriver.act('perform complex workflow', { tries: 3 });
+  await testdriver.ai('Add the blue T-shirt to the cart', { tries: 3 });
 } catch (error) {
   if (error instanceof AIError) {
-    console.log(error.task);       // "perform complex workflow"
-    console.log(error.tries);     // 3
-    console.log(error.duration);  // 15234 (ms)
-    console.log(error.cause);     // underlying Error
+    console.log(`Stopped after ${error.tries} of ${error.maxTries} tries`);
+    console.log(error.cause?.message); // the error that stopped the task
   }
+  throw error;
 }
 ```
 
+`act()` is the same method under another name and throws the same error.
+
 ### Properties
 
-<ParamField path="name" type="string">
+<ResponseField name="name" type="string">
   Always `"AIError"`.
-</ParamField>
+</ResponseField>
 
-<ParamField path="message" type="string">
-  Enhanced message with execution details block.
-</ParamField>
+<ResponseField name="task" type="string">
+  The task you passed to `ai()`.
+</ResponseField>
 
-<ParamField path="task" type="string">
-  The task description passed to `act()`.
-</ParamField>
+<ResponseField name="tries" type="number">
+  How many check attempts were made.
+</ResponseField>
 
-<ParamField path="tries" type="number">
-  Number of attempts that were made.
-</ParamField>
+<ResponseField name="maxTries" type="number">
+  The `tries` limit for the call. Defaults to `7`.
+</ResponseField>
 
-<ParamField path="maxTries" type="number">
-  Maximum number of attempts configured.
-</ParamField>
+<ResponseField name="duration" type="number">
+  How long the task ran, in milliseconds.
+</ResponseField>
 
-<ParamField path="duration" type="number">
-  Total execution time in milliseconds.
-</ParamField>
+<ResponseField name="cause" type="Error">
+  The error that stopped the task.
+</ResponseField>
 
-<ParamField path="cause" type="Error | undefined">
-  The underlying error that caused the final failure.
-</ParamField>
+<ResponseField name="timestamp" type="string">
+  When the error was created, as an ISO 8601 string.
+</ResponseField>
 
-<ParamField path="timestamp" type="string">
-  ISO 8601 timestamp of when the error was created.
-</ParamField>
+### Message
 
-### Enhanced Message
-
-```
-AI failed: Element not found after 3 attempts
+```text
+AI failed: <the cause's message>
 
 === AI Execution Details ===
-Task: perform complex workflow
-Tries: 3 / 3
-Duration: 15234ms
-Cause: ElementNotFoundError: Element not found: "submit button"
+Task: "Add the blue T-shirt to the cart"
+Tries: 3/3
+Duration: 41250ms
+Timestamp: 2026-10-21T14:30:00.000Z
+Underlying error: <the cause's message>
 ```
 
-## Internal Error Classes
-
-These errors are used internally by the agent and are not exported, but may appear as the `cause` of an `AIError`:
-
-### MatchError
-
-Thrown when element matching fails (text, image, or assertion).
-
-| Property | Type | Description |
-|---|---|---|
-| `fatal` | `boolean` | If `true`, cannot be healed. Default: `false` |
-| `attachScreenshot` | `boolean` | Always `true` — a screenshot is attached to the error |
-
-### CommandError
+## Other errors
 
-Thrown for invalid arguments or unsupported operations.
+These failures throw an error whose class isn't exported. Check the message instead.
 
-| Property | Type | Description |
-|---|---|---|
-| `fatal` | `boolean` | Always `true` |
-| `attachScreenshot` | `boolean` | Always `false` |
-
-## Soft Assert Mode
-
-Inside `act()`, assertions run in **soft assert mode**. When an assertion fails, it returns the failure result instead of throwing, allowing the AI to process the failure and adjust its approach.
-
-```javascript
-// Inside act(), assertion failures don't throw
-await testdriver.act('verify the dashboard shows correct data', {
-  tries: 3,
-});
-// The AI can see assertion results and self-correct
-```
-
-This is automatic — you don't need to configure it. Regular `assert()` calls outside of `act()` will throw normally on failure.
-
-## Error Handling Patterns
-
-### Catching Specific Errors
+| What failed | Message starts with |
+| --- | --- |
+| [`assert()`](/assert) | `AI Assertion failed:` followed by the assertion and the AI's explanation |
+| [`exec()`](/exec) with `sh` or `pwsh`, when the command exits non-zero | `Command failed with exit code <code>:` followed by stderr |
 
 ```javascript
-import TestDriver, { ElementNotFoundError, AIError } from 'testdriverai';
-
 try {
-  await testdriver.find('submit button').click();
+  await testdriver.assert('the cart shows 2 items');
 } catch (error) {
-  if (error instanceof ElementNotFoundError) {
-    // Element wasn't found — check screenshot for debugging
-    console.log('Debug screenshot:', error.screenshotPath);
-  } else if (error instanceof AIError) {
-    // AI exhausted retries
-    console.log(`Failed after ${error.tries} tries in ${error.duration}ms`);
-  } else {
-    throw error; // Unexpected error
+  if (error.message.startsWith('AI Assertion failed:')) {
+    // The assertion didn't hold
   }
+  throw error;
 }
 ```
 
-### Using Debug Screenshots
+<Note>
+  Inside `ai()`, a failed `assert()` resolves to `false` instead of throwing, so the AI can see the result and try another approach.
+</Note>
 
-```javascript
-try {
-  const el = await testdriver.find('checkout button');
-  await el.click();
-} catch (error) {
-  if (error instanceof ElementNotFoundError) {
-    // Screenshot of what the screen looked like
-    console.log('Screen:', error.screenshotPath);
-    // Pixel diff showing cache comparison
-    console.log('Diff:', error.pixelDiffPath);
-    // Full AI response metadata
-    console.log('AI:', JSON.stringify(error.aiResponse, null, 2));
-  }
-}
-```
+## Related
 
-## Types
-
-```typescript
-class ElementNotFoundError extends Error {
-  name: 'ElementNotFoundError';
-  description: string;
-  screenshotPath: string | null;
-  pixelDiffPath: string | null;
-  cachedImagePath: string | null;
-  aiResponse: Record<string, any> | null;
-  timestamp: string;
-}
-
-class AIError extends Error {
-  name: 'AIError';
-  task: string;
-  tries: number;
-  maxTries: number;
-  duration: number;
-  cause?: Error;
-  timestamp: string;
-}
-```
+- [find()](/find): returns an element whose `found()` tells you whether it was located
+- [assert()](/assert): check what's on screen
+- [Debug a failing test](/debugging-with-screenshots): find out why a test failed
+- [Events](/events): listen for errors as they happen