@testdriverai/mcp 7.10.0-canary.0 → 7.10.1-test

package/docs/v7/find.mdx

@@ -50,8 +50,12 @@ const element = await testdriver.find(description, options)
       - `"any"` — No wrapping, uses the description as-is (default behavior)
     </ParamField>
     
-    <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 path="zoom" type="boolean" default={false}>
+      Two-phase zoom mode for better precision in crowded UIs with many similar elements. Disabled by default.
+    </ParamField>
+    
+    <ParamField path="verify" type="boolean" default={false}>
+      Enable AI verification of the located element. When `true`, a second AI call checks that the coordinates returned actually correspond to the requested element, catching hallucinated or incorrect positions. Disabled by default for lower latency.
     </ParamField>
     
     <ParamField path="ai" type="object">
@@ -335,17 +339,17 @@ The `timeout` option:
 
 ## Zoom Mode
 
-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.
+Zoom mode is **disabled 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`:
+To enable zoom for a specific find call, pass `zoom: true`:
 
 ```javascript
-// Zoom is on by default — no option needed
-const extensionsBtn = await testdriver.find('extensions puzzle icon in Chrome toolbar');
+// Enable zoom for better precision in crowded UIs
+const extensionsBtn = await testdriver.find('extensions puzzle icon in Chrome toolbar', { zoom: true });
 await extensionsBtn.click();
 
-// Disable zoom for a specific call if needed
-const largeButton = await testdriver.find('big hero button', { zoom: false });
+// Without zoom (default)
+const largeButton = await testdriver.find('big hero button');
 ```
 
 ### How Zoom Mode Works
@@ -358,13 +362,48 @@ const largeButton = await testdriver.find('big hero button', { zoom: false });
 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>
-  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
+  You may want to enable zoom with `zoom: true` when:
+  - Targeting small elements in crowded UIs with many similar elements
+  - You need extra precision for closely spaced UI elements
 </Tip>
 
+## Verify Mode
+
+Verify mode is **disabled by default**. When enabled, a second AI call checks that the coordinates returned by `find()` actually correspond to the requested element, catching hallucinated or incorrect positions.
+
+```javascript
+// Enable verification for critical interactions
+const deleteBtn = await testdriver.find('delete account button', { verify: true });
+await deleteBtn.click();
+```
+
+### How Verify Mode Works
+
+1. **Phase 1**: AI locates the element and returns coordinates
+2. **Phase 2**: A second AI call examines the screenshot at those coordinates to confirm the element matches the description
+3. **Result**: If verification fails, the find is retried or marked as not found
+
+### Combining Zoom and Verify
+
+For maximum accuracy, enable both `zoom` and `verify` together. This is useful for critical interactions where clicking the wrong element could cause cascading failures:
+
+```javascript
+// Maximum accuracy: zoom for precision + verify to catch hallucinations
+const element = await testdriver.find('small cancel icon next to the subscription', {
+  zoom: true,
+  verify: true,
+});
+await element.click();
+```
+
+<Warning>
+  Both `zoom` and `verify` add extra AI calls per `find()` invocation, which increases latency and API usage. When both are enabled, each find may make up to 3 AI calls. **Rate limiting may occur** if many find calls use these options in rapid succession. Use them selectively for critical interactions rather than on every find call.
+</Warning>
+
 ## Cache Options
 
+When a test completes successfully, the result of each `find()` is cached. On later runs, TestDriver reuses the cached match instead of making a fresh AI call, which significantly speeds up locating the same element. The cache lives in your [dashboard](https://console.testdriver.ai/cache) and is shared across runs — see the [Cache](/v7/cache) page for how matching, thresholds, and invalidation work.
+
 Control caching behavior to optimize performance, especially when using dynamic variables in prompts.
 
 ### Custom Cache Key

package/docs/v7/generating-tests.mdx

@@ -1,12 +1,21 @@
 ---
-title: "Generating Tests"
-description: "Use AI coding agents and exploration mode to generate TestDriver tests"
-icon: "wand-magic-sparkles"
+title: "Explore"
+sidebarTitle: "Explore"
+description: "Generate tests by exploring your app with the AI vision agent"
+icon: "compass"
 ---
 
+Start by exploring your app. This is where tests begin: you describe a flow in plain English, and the TestDriver vision agent clicks, types, and reads the screen to figure it out — then writes the test for you. No selectors, no DOM, no brittle locators. Just describe what you want to test and let the agent discover the rest.
+
+There are two ways to explore: chatting interactively with your AI assistant through the TestDriver MCP server, or handing a coding agent our instructions file and prompting it to generate a test.
+
+<Info>
+  Both paths need an MCP-capable AI coding assistant. If you don't have one yet, start with **GitHub Copilot** — there's a [free tier](https://github.com/features/copilot/plans), no credit card required. See [Run → Setup](/v7/copilot/running-tests#setup) for the full install and sign-in walkthrough.
+</Info>
+
 ## Instructions for Coding Agents
 
-We recommend starting with [our quickstart](./quickstart) then supplying your coding agent with our agent instructions file.
+We recommend starting with [our quickstart](./quickstart), then supplying your coding agent with our agent instructions file.
 
 <Card title="TestDriver Agent Instructions" icon="link" arrow="true" horizontal href="https://github.com/testdriverai/testdriverai/blob/main/ai/agents/testdriver.md?plain=1">
   Copy the current version of our agent instructions to provide your coding agent with up-to-date instructions on how to generate TestDriver tests.
@@ -24,13 +33,160 @@ Push Submit button
 Verify new page contains expected text 'logged in'
 ```
 
-## AI Exploration Mode
+<Info>Explicit commands are preferred for production tests, as they are cheaper, faster, and more reliable.</Info>
+
+## Start a Conversation
+
+With TestDriver's MCP server and your AI assistant (GitHub Copilot, Cursor, or Claude Desktop), you can create tests by chatting with an AI agent. The agent spawns a virtual machine, executes actions, and writes test code for you.
+
+Open your AI assistant's chat. If your project has no other agents configured, the TestDriver agent is used by default. Otherwise, select **testdriver** from the agent dropdown in the chat panel.
 
-Within a test, the `ai()` method lets TestDriver autonomously figure out how to accomplish a task. It's useful for dynamic or unpredictable UIs where explicit actions may be difficult to define.
+Describe what you want to test:
 
-```javascript
-// Handle dynamic or unpredictable UI
-await testdriver.ai('dismiss any popups or modals that appear');
+```
+Create a test that logs into my app at https://myapp.com
 ```
 
-<Info>Explicit commands are preferred for production tests, as they are cheaper, faster, and more reliable.</Info>
+The agent will:
+1. Start a new session and spawn a Linux virtual machine
+2. Launch Chrome and navigate to your URL
+3. Execute actions based on your instructions
+4. Write the test code to a `.test.mjs` file
+
+<Note>
+  The TestDriver agent appears in the agent selection dropdown if you have other agents configured (like `copilot-instructions.md` or other `.agent.md` files). Make sure to select **testdriver** to use TestDriver's MCP tools.
+</Note>
+
+## Live Preview Panel
+
+When the agent starts a session, a **live preview panel** opens in your editor. This lets you:
+
+- **Watch tests execute** in real-time
+- **Interact with the VM** — click, type, and navigate manually
+- **Debug issues** — see exactly what the AI sees
+
+<Note>
+  The live preview panel requires the TestDriver VS Code extension. Set `TD_PREVIEW=ide` in your MCP configuration to enable it. See the [Run page](/v7/copilot/running-tests) for all device and preview options.
+</Note>
+
+## Interactive Workflow
+
+The recommended workflow for exploring and creating tests:
+
+<Steps>
+  <Step title="Describe Your Test">
+    Tell the agent what you want to test:
+
+    ```
+    Test the checkout flow on https://shop.example.com
+    ```
+  </Step>
+
+  <Step title="Watch and Guide">
+    The agent will start executing. Watch the preview panel and provide guidance if needed:
+
+    ```
+    The login modal appeared. Use test@example.com and password123
+    ```
+  </Step>
+
+  <Step title="Add Assertions">
+    Ask the agent to verify specific conditions:
+
+    ```
+    Assert that the order confirmation page is shown with the order number
+    ```
+  </Step>
+
+  <Step title="Review the Code">
+    The agent writes test code as it works. Review the generated `.test.mjs` file and make any adjustments.
+  </Step>
+</Steps>
+
+## Example Conversation
+
+Here's a complete example of exploring and creating a login test:
+
+```
+You: Create a test for the login flow at https://console.testdriver.ai
+
+Agent: I'll create a test for the login flow. Starting a session...
+       [Screenshot: Login page loaded]
+
+       I can see the login page. Let me find the email input.
+       [Screenshot: Email input highlighted]
+
+       Now I'll type the email and find the password field...
+
+You: Use test@example.com for the email
+
+Agent: Got it. Typing test@example.com...
+       [Screenshot: Email entered]
+
+       Now entering the password and clicking Sign In...
+       [Screenshot: Dashboard loaded]
+
+       ✅ Login successful! I've written the test to tests/login.test.mjs
+```
+
+## Generated Test Code
+
+The agent generates standard Vitest test files:
+
+```javascript tests/login.test.mjs
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "testdriverai/vitest/hooks";
+
+describe("Login Flow", () => {
+  it("should log in successfully", async (context) => {
+    const testdriver = TestDriver(context);
+
+    await testdriver.provision.chrome({
+      url: "https://console.testdriver.ai"
+    });
+
+    const emailInput = await testdriver.find("email input field");
+    await emailInput.click();
+    await testdriver.type("test@example.com");
+
+    const passwordInput = await testdriver.find("password input field");
+    await passwordInput.click();
+    await testdriver.type("password123");
+
+    const signInButton = await testdriver.find("Sign In button");
+    await signInButton.click();
+
+    const result = await testdriver.assert("dashboard is visible");
+    expect(result).toBeTruthy();
+  });
+});
+```
+
+## Tips for Better Tests
+
+<AccordionGroup>
+  <Accordion title="Be specific with element descriptions">
+    Instead of "click the button", say "click the blue Sign In button in the header". More context helps the AI find the right element.
+  </Accordion>
+  <Accordion title="Add waits for dynamic content">
+    If your app has animations or loading states, tell the agent to wait:
+    ```
+    Wait for the loading spinner to disappear before continuing
+    ```
+  </Accordion>
+  <Accordion title="Use assertions liberally">
+    Add assertions after each major action to catch regressions early:
+    ```
+    Assert that the product was added to the cart
+    ```
+  </Accordion>
+  <Accordion title="Break complex flows into steps">
+    For long workflows, create the test incrementally and verify each step works before moving on.
+  </Accordion>
+</AccordionGroup>
+
+## Next
+
+<Card title="Learn" icon="brain" arrow="true" horizontal href="/v7/caching">
+  Once the agent has explored your app, TestDriver caches what it discovers so your tests replay instantly without re-reasoning over the screen every time.
+</Card>

package/docs/v7/hosted.mdx

@@ -77,7 +77,7 @@ To prevent tests from failing due to exceeding your license slot limit, we recom
 
     ```javascript vitest.config.mjs
     import { defineConfig } from 'vitest/config';
-    import { TestDriver } from 'testdriverai/vitest';
+    import TestDriver from 'testdriverai/vitest';
 
     export default defineConfig({
       test: {

package/docs/v7/making-assertions.mdx

@@ -1,12 +1,83 @@
 ---
-title: "Making Assertions"
-description: "Verify application state with AI-powered assertions"
-icon: "check-double"
+title: "Validate"
+sidebarTitle: "Validate"
+description: "Locate elements and verify app state with AI-powered assertions"
+icon: "circle-check"
 ---
 
+Once a test runs, validate that the app did what it should. Validation has two parts: locating the elements you want to check, and making assertions about the state of your app. TestDriver uses AI as a judge, returning a boolean plus reasoning about whether your app is in the expected state.
+
+## Locating Elements
+
+### Locating Single Elements
+
+Use natural language to describe elements. Descriptions should be specific enough to locate the element, but not too-specific that they break with minor UI changes. For example:
+
+```javascript
+await testdriver.find('email input field');
+await testdriver.find('first product card in the grid');
+await testdriver.find('dropdown menu labeled "Country"');
+```
+
+<Info>TestDriver will cache found elements for improved performance on subsequent calls. Learn more about [element caching here](/v7/caching).</Info>
+
+### Debugging Found Elements
+
+After finding an element, you can inspect its properties for debugging:
+
+```javascript
+const button = await testdriver.find('submit button');
+console.log(button);
+```
+
+This outputs all element properties:
+
+```javascript
+{
+  description: 'submit button',
+  found: true,
+  x: 150,
+  y: 300,
+  coordinates: { x: 150, y: 300, centerX: 200, centerY: 320 },
+  threshold: 0.8,
+  confidence: 0.95,
+  similarity: 0.92,
+  selector: 'button[type="submit"]',
+  cache: {
+    hit: true,
+    strategy: 'pixel-diff',
+    createdAt: '2025-01-15T10:30:00Z',
+    diffPercent: 0.02,
+    imageUrl: 'https://...'
+  }
+}
+```
+
+### Working with Multiple Elements
+
+Find and interact with multiple elements:
+
+```javascript
+// Find all matching elements
+const products = await testdriver.findAll('product card');
+console.log(`Found ${products.length} products`);
+
+// Interact with each
+for (const product of products) {
+  const title = await product.find('title text');
+  console.log('Product:', title.text);
+
+  await product.find('add to cart button').click();
+}
+
+// Or find specific element
+const firstProduct = products[0];
+await firstProduct.click();
+```
+
 ## Making Assertions
 
-Use AI-powered assertions to verify application state:
+Use AI-powered assertions to verify application state. TestDriver acts as a judge: it evaluates your natural-language statement against the current state of the app and returns a boolean plus reasoning explaining the verdict.
 
 ```javascript
 // Verify visibility
@@ -30,3 +101,9 @@ await testdriver.assert('form has red border');
 ```
 
 <Info>Assertions are not cached and always re-evaluated to ensure accuracy.</Info>
+
+## Next
+
+<Card title="Adapt" icon="arrows-rotate" href="/v7/performing-actions">
+  Drive your app forward by performing actions on the elements you've located and validated.
+</Card>

package/docs/v7/parse.mdx

@@ -121,7 +121,7 @@ console.log(`Found ${buttons.length} buttons`);
 
 ```javascript
 import { describe, expect, it } from "vitest";
-import { TestDriver } from "testdriverai/lib/vitest/hooks.mjs";
+import { TestDriver } from "testdriverai/vitest/hooks";
 
 describe("Login Page", () => {
   it("should have expected form elements", async (context) => {

package/docs/v7/performing-actions.mdx

@@ -1,9 +1,14 @@
 ---
-title: "Performing Actions"
-description: "Click, type, hover, scroll and more with TestDriver"
-icon: "computer-mouse"
+title: "Adapt"
+sidebarTitle: "Adapt"
+description: "Perform actions and handle dynamic, async UI so tests adapt to change"
+icon: "arrows-rotate"
 ---
 
+Real apps move, load, and change. Adapt your tests to handle it.
+
+Once you've [generated](/v7/generating-tests) and [learned](/v7/caching) your tests and gotten them [running](/v7/copilot/running-tests), the next challenge is the real world: buttons appear after a spinner, pages navigate, animations play, and content streams in over the network. To keep tests reliable, you need to perform the right actions and handle timing so your tests adapt to how the UI actually behaves instead of breaking.
+
 ## Performing Actions
 
 TestDriver provides a variety of actions you can perform, like [clicking](/v7/click), [typing](/v7/type), [hovering](/v7/hover), and [scrolling](/v7/scroll). For a full list, see the [API Reference](/v7/click).
@@ -27,7 +32,6 @@ await testdriver.find('dropdown menu').hover();
 
 // Scrolling
 await testdriver.scroll('down', 500);
-await testdriver.scrollUntilText('Footer content');
 
 // Waiting
 await testdriver.wait(2000); // Wait 2 seconds for animation/state change
@@ -37,7 +41,7 @@ const price = await testdriver.extract('the total price');
 const orderNumber = await testdriver.extract('the order confirmation number');
 ```
 
-## Chaining Actions
+### Chaining Actions
 
 TestDriver supports method chaining for cleaner code:
 
@@ -52,3 +56,94 @@ Or save element reference for later use:
 const button = await testdriver.find('submit button');
 await button.click();
 ```
+
+## Waiting for Dynamic Content
+
+By default, `find()` automatically polls for up to 10 seconds, retrying every 5 seconds until the element is found. This means most elements that appear after short async operations will be found without any extra configuration.
+
+For longer operations, increase the `timeout`:
+
+```javascript
+// Default behavior - polls for up to 10 seconds automatically
+const element = await testdriver.find('Loading complete indicator');
+await element.click();
+
+// Wait up to 30 seconds for slower operations
+const element = await testdriver.find('Loading complete indicator', { timeout: 30000 });
+await element.click();
+
+// Useful after actions that trigger loading states
+await testdriver.find('submit button').click();
+await testdriver.find('success message', { timeout: 15000 });
+
+// Disable polling for instant checks
+const toast = await testdriver.find('notification toast', { timeout: 0 });
+```
+
+### Flake Prevention
+
+TestDriver automatically waits for the screen and network to stabilize after each action using **redraw detection**. This prevents flaky tests caused by animations, loading states, or dynamic content updates.
+
+<Note>
+  Redraw detection adds a small delay after each action but significantly reduces test flakiness.
+</Note>
+
+For example, when clicking a submit button that navigates to a new page:
+
+```javascript
+// Click submit - TestDriver automatically waits for the new page to load
+await testdriver.find('submit button').click();
+
+// By the time this runs, the page has fully loaded and stabilized
+await testdriver.assert('dashboard is displayed');
+await testdriver.find('welcome message');
+```
+
+Without redraw detection, you'd need manual waits or retries to handle the page transition. TestDriver handles this automatically by detecting when the screen stops changing and network requests complete.
+
+You can disable redraw detection or customize its behavior:
+
+```javascript
+// Disable redraw detection for faster tests (less reliable)
+const testdriver = TestDriver(context, { 
+  redraw: false 
+});
+```
+
+Here is an example of customizing redraw detection:
+
+```javascript
+// Fine-tune redraw detection
+const testdriver = TestDriver(context, { 
+  redraw: {
+    enabled: true,
+    diffThreshold: 0.1,      // Pixel difference threshold (0-1)
+    screenRedraw: true,      // Monitor screen changes
+    networkMonitor: true,    // Wait for network idle
+  }
+});
+```
+
+### Simple Delays with `wait()`
+
+For simple pauses — waiting for animations, transitions, or state changes after an action — use `wait()`:
+
+```javascript
+// Wait for an animation to complete
+await testdriver.find('menu toggle').click();
+await testdriver.wait(2000);
+
+// Wait for a page transition to settle
+await testdriver.find('next page button').click();
+await testdriver.wait(1000);
+```
+
+<Note>
+  For waiting for specific **elements** to appear, prefer `find()` with a `timeout` option. Use `wait()` only for simple time-based pauses.
+</Note>
+
+Once your tests can reliably act on a changing UI and [assert](/v7/making-assertions) the results, the next step is figuring out what happened when something does go wrong.
+
+<Card title="Next: Debug" icon="bug" href="/v7/debugging-with-screenshots">
+  Use screenshots and run output to see exactly what your test saw and pinpoint failures.
+</Card>

package/docs/v7/provision.mdx

@@ -16,10 +16,6 @@ Access provision methods via `testdriver.provision.*`:
 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()
@@ -236,22 +232,6 @@ await testdriver.provision.dashcam({
 });
 ```
 
-## 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