@testdriverai/mcp 7.9.150-test → 7.9.152-test

package/docs/v7/debugging-with-screenshots.mdx

@@ -1,13 +1,13 @@
 ---
-title: "Debugging with Screenshots"
-sidebarTitle: "Debugging with Screenshots"
-description: "View and analyze saved screenshots using MCP commands for test debugging and development"
-icon: "magnifying-glass"
+title: "Debug"
+sidebarTitle: "Debug"
+description: "Diagnose failing tests with screenshots, replays, and logs"
+icon: "bug"
 ---
 
 ## Overview
 
-TestDriver MCP provides powerful commands to view and analyze screenshots saved during test execution. This enables rapid debugging, test development, and comparison workflows without manually opening image files.
+When a test fails, debug it by seeing exactly what happened — don't guess. TestDriver captures screenshots, video replays, and logs as your test runs, so you can replay the moment of failure instead of squinting at a stack trace. TestDriver MCP provides powerful commands to view and analyze the screenshots saved during test execution, enabling rapid debugging, test development, and comparison workflows without manually opening image files.
 
 <Note>
   **Automatic Screenshots (Default: Enabled)**: TestDriver automatically captures screenshots before and after every command. Screenshots are named with the line number and action, making it easy to trace exactly which line of code produced each screenshot. For example: `001-click-before-L42-submit-button.png`
@@ -123,7 +123,7 @@ view_local_screenshot({ path: "/full/path/to/screenshot.png" })
 
 ### Test Debugging After Failures
 
-When a test fails, use powerful filtering to quickly find relevant screenshots:
+When a test fails, you don't have to wonder what went wrong — use powerful filtering to quickly find the screenshots that show exactly what happened:
 
 **1. Find screenshots at the failing line:**
 
@@ -359,7 +359,7 @@ This helps verify your test logic before running the full test file.
 
 ### After Test Runs
 
-When tests fail or behave unexpectedly:
+When tests fail or behave unexpectedly, replay what happened step by step:
 
 1. **Run the test** with `vitest run tests/my-test.test.mjs`
 2. **List screenshots** using `list_local_screenshots`
@@ -409,8 +409,18 @@ When tests fail or behave unexpectedly:
   </Accordion>
 </AccordionGroup>
 
+## Where this fits in the Guide
+
+Debugging is what you reach for when a [Run](/v7/copilot/running-tests) goes sideways or a [Validate](/v7/making-assertions) assertion fails — the screenshots show you precisely what the AI saw before it acted. Once you've diagnosed the failure, the next step is to stop it from recurring.
+
 ## Related
 
 - [screenshot()](/v7/screenshot) - Capture screenshots during test execution
 - [Dashcam](/v7/dashcam) - Record full test sessions with video and logs
 - [assert()](/v7/assert) - Make AI-powered assertions that benefit from screenshot context
+
+## Next
+
+<Card title="Prevent" icon="shield-check" href="/v7/copilot/auto-healing">
+  You've seen what went wrong — now keep it from happening again. Let auto-healing repair flaky tests automatically before they fail your suite.
+</Card>

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/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/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).
@@ -36,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:
 
@@ -51,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>