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

package/ai/.claude-plugin/plugin.json

@@ -1,9 +1,94 @@
 {
   "name": "testdriver",
-  "description": "TestDriver plugin: SDK guidance plus MCP access to test runs and results.",
-  "version": "1.0.0",
+  "version": "7.9.54-test",
+  "description": "TestDriver.ai Claude Code plugin: MCP server, TestDriver expert agent, and skills for authoring computer-use end-to-end tests with Vitest.",
   "author": {
-    "name": "TestDriver"
-  }
+    "name": "TestDriver.ai",
+    "url": "https://testdriver.ai"
+  },
+  "homepage": "https://docs.testdriver.ai",
+  "repository": "https://github.com/testdriverai/testdriverai",
+  "license": "AGPL-3.0",
+  "keywords": [
+    "testdriver",
+    "testing",
+    "e2e",
+    "mcp",
+    "vitest",
+    "automation",
+    "computer-use",
+    "browser",
+    "ai",
+    "qa"
+  ],
+  "mcpServers": {
+    "testdriver": {
+      "command": "npx",
+      "args": ["-p", "testdriverai", "testdriverai-mcp"],
+      "env": {
+        "TD_API_KEY": "${TD_API_KEY}"
+      }
+    }
+  },
+  "agents": [
+    "./agents/testdriver.md"
+  ],
+  "skills": [
+    "./skills/testdriver-ai",
+    "./skills/testdriver-assert",
+    "./skills/testdriver-aws-setup",
+    "./skills/testdriver-cache",
+    "./skills/testdriver-caching",
+    "./skills/testdriver-captcha",
+    "./skills/testdriver-ci-cd",
+    "./skills/testdriver-click",
+    "./skills/testdriver-client",
+    "./skills/testdriver-cloud",
+    "./skills/testdriver-customizing-devices",
+    "./skills/testdriver-dashcam",
+    "./skills/testdriver-debugging-with-screenshots",
+    "./skills/testdriver-device-config",
+    "./skills/testdriver-double-click",
+    "./skills/testdriver-elements",
+    "./skills/testdriver-enterprise",
+    "./skills/testdriver-errors",
+    "./skills/testdriver-events",
+    "./skills/testdriver-examples",
+    "./skills/testdriver-exec",
+    "./skills/testdriver-find",
+    "./skills/testdriver-focus-application",
+    "./skills/testdriver-generating-tests",
+    "./skills/testdriver-hosted",
+    "./skills/testdriver-hover",
+    "./skills/testdriver-locating-elements",
+    "./skills/testdriver-making-assertions",
+    "./skills/testdriver-mcp",
+    "./skills/testdriver-mcp-workflow",
+    "./skills/testdriver-mouse-down",
+    "./skills/testdriver-mouse-up",
+    "./skills/testdriver-parse",
+    "./skills/testdriver-performing-actions",
+    "./skills/testdriver-press-keys",
+    "./skills/testdriver-provision",
+    "./skills/testdriver-quickstart",
+    "./skills/testdriver-redraw",
+    "./skills/testdriver-reusable-code",
+    "./skills/testdriver-right-click",
+    "./skills/testdriver-running-tests",
+    "./skills/testdriver-screenshot",
+    "./skills/testdriver-screenshots",
+    "./skills/testdriver-scroll",
+    "./skills/testdriver-secrets",
+    "./skills/testdriver-self-hosted",
+    "./skills/testdriver-test-results-json",
+    "./skills/testdriver-test-writer",
+    "./skills/testdriver-testdriver",
+    "./skills/testdriver-testdriver-mechanic",
+    "./skills/testdriver-type",
+    "./skills/testdriver-variables",
+    "./skills/testdriver-wait",
+    "./skills/testdriver-waiting-for-elements",
+    "./skills/testdriver-what-is-testdriver"
+  ]
 }
 

package/ai/agents/testdriver.md

@@ -1,7 +1,7 @@
 ---
 name: testdriver
 description: An expert at creating and refining automated tests using TestDriver.ai
-tools: ['vscode/getProjectSetupInfo', 'vscode/installExtension', 'vscode/newWorkspace', 'vscode/openSimpleBrowser', 'vscode/runCommand', 'vscode/askQuestions', 'vscode/switchAgent', 'vscode/vscodeAPI', 'vscode/extensions', 'execute/runNotebookCell', 'execute/testFailure', 'execute/getTerminalOutput', 'execute/awaitTerminal', 'execute/killTerminal', 'execute/runTask', 'execute/createAndRunTask', 'execute/runInTerminal', 'execute/runTests', 'read/getNotebookSummary', 'read/problems', 'read/readFile', 'read/readNotebookCellOutput', 'read/terminalSelection', 'read/terminalLastCommand', 'read/getTaskOutput', 'agent/runSubagent', 'edit/createDirectory', 'edit/createFile', 'edit/createJupyterNotebook', 'edit/editFiles', 'edit/editNotebook', 'search/changes', 'search/codebase', 'search/fileSearch', 'search/listDirectory', 'search/searchResults', 'search/textSearch', 'search/usages', 'search/searchSubagent', 'web/fetch', 'web/githubRepo', 'testdriver/assert', 'testdriver/check', 'testdriver/click', 'testdriver/exec', 'testdriver/find', 'testdriver/find_and_click', 'testdriver/findall', 'testdriver/focus_application', 'testdriver/hover', 'testdriver/list_local_screenshots', 'testdriver/press_keys', 'testdriver/screenshot', 'testdriver/scroll', 'testdriver/session_extend', 'testdriver/session_start', 'testdriver/session_status', 'testdriver/type', 'testdriver/view_local_screenshot', 'testdriver/wait', 'todo']
+tools: ['vscode/getProjectSetupInfo', 'vscode/installExtension', 'vscode/newWorkspace', 'vscode/openSimpleBrowser', 'vscode/runCommand', 'vscode/askQuestions', 'vscode/switchAgent', 'vscode/vscodeAPI', 'vscode/extensions', 'execute/runNotebookCell', 'execute/testFailure', 'execute/getTerminalOutput', 'execute/awaitTerminal', 'execute/killTerminal', 'execute/runTask', 'execute/createAndRunTask', 'execute/runInTerminal', 'execute/runTests', 'read/getNotebookSummary', 'read/problems', 'read/readFile', 'read/readNotebookCellOutput', 'read/terminalSelection', 'read/terminalLastCommand', 'read/getTaskOutput', 'agent/runSubagent', 'edit/createDirectory', 'edit/createFile', 'edit/createJupyterNotebook', 'edit/editFiles', 'edit/editNotebook', 'search/changes', 'search/codebase', 'search/fileSearch', 'search/listDirectory', 'search/searchResults', 'search/textSearch', 'search/usages', 'search/searchSubagent', 'web/fetch', 'web/githubRepo', 'testdriver/assert', 'testdriver/check', 'testdriver/click', 'testdriver/exec', 'testdriver/find', 'testdriver/find_and_click', 'testdriver/findall', 'testdriver/focus_application', 'testdriver/hover', 'testdriver/init', 'testdriver/list_local_screenshots', 'testdriver/press_keys', 'testdriver/screenshot', 'testdriver/scroll', 'testdriver/session_extend', 'testdriver/session_start', 'testdriver/session_status', 'testdriver/type', 'testdriver/view_local_screenshot', 'testdriver/wait', 'todo']
 mcp-servers:
   testdriver:
     command: npx
@@ -44,7 +44,7 @@ Use this agent when the user asks to:
 4. **⚠️ WRITE CODE IMMEDIATELY**: After EVERY successful action, append the generated code to the test file RIGHT AWAY. Do NOT wait until the end.
 5. **Verify Actions**: Use `check` after actions to verify they succeeded (for YOUR understanding only).
 6. **Add Assertions**: Use `assert` for test conditions that should be in the final test file.
-7. **⚠️ RUN THE TEST YOURSELF**: Use `vitest run <testFile> --reporter=dot` to run the test - do NOT tell the user to run it. Iterate until it passes. **NEVER use `npx vitest`** - always use `vitest` directly.
+7. **⚠️ RUN THE TEST YOURSELF**: Use `vitest run <testFile>` to run the test - do NOT tell the user to run it. Iterate until it passes. **NEVER use `npx vitest`** - always use `vitest` directly.
 8. **⚠️ SHARE THE TEST REPORT**: After EVERY test run, find the `TESTDRIVER_RUN_URL` in the output (e.g., `TESTDRIVER_RUN_URL=https://console.testdriver.ai/runs/...`) and share it with the user so they can view the recording and results.
 
 ## Prerequisites
@@ -315,11 +315,9 @@ assert({ assertion: "the dashboard is visible" })
 **⚠️ YOU must run the test - do NOT tell the user to run it. NEVER use `npx vitest` - always use `vitest` directly:**
 
 ```bash
-vitest run tests/login.test.mjs --reporter=dot
+vitest run tests/login.test.mjs
 ```
 
-**Always use `--reporter=dot`** for cleaner, more concise output that's easier to parse.
-
 Analyze the output, fix any issues, and iterate until the test passes.
 
 **⚠️ ALWAYS share the test report link with the user.** After each test run, look for `TESTDRIVER_RUN_URL` in the test output (e.g., `TESTDRIVER_RUN_URL=https://console.testdriver.ai/runs/...`) and share it with the user so they can view the recording and results. This is CRITICAL - users need to see the visual recording to understand test behavior.
@@ -568,8 +566,6 @@ await testdriver.pressKeys(["escape"]);
 
 // Now scroll
 await testdriver.scroll("down");
-await testdriver.scrollUntilText("Footer text");
-await testdriver.scrollUntilImage("Product image at bottom");
 
 // If scroll is not working, try using Page Down key directly
 await testdriver.pressKeys(["pagedown"]);
@@ -614,7 +610,7 @@ await testdriver.screenshot(1, false, true);
 ## Tips for Agents
 
 1. **⚠️ WRITE CODE IMMEDIATELY** - After EVERY successful MCP action, append the generated code to the test file RIGHT AWAY. Do NOT wait until the session ends.
-2. **⚠️ RUN TESTS YOURSELF** - Do NOT tell the user to run tests. YOU must run the tests using `vitest run <testFile> --reporter=dot` (NEVER use `npx vitest` - it breaks the reporter). Always use `--reporter=dot` for cleaner output. Analyze the output and iterate until the test passes.
+2. **⚠️ RUN TESTS YOURSELF** - Do NOT tell the user to run tests. YOU must run the tests using `vitest run <testFile>` (NEVER use `npx vitest`). Analyze the output and iterate until the test passes.
 3. **⚠️ SHARE THE TEST REPORT URL** - After EVERY test run, find `TESTDRIVER_RUN_URL=https://console.testdriver.ai/runs/...` in the output and share it with the user. This is CRITICAL - users need to view the recording to understand what happened.
 3. **Screenshots are automatic** - TestDriver captures screenshots before/after every command by default. Each screenshot filename includes the line number (e.g., `001-click-before-L42-submit-button.png`) making it easy to trace issues.
 4. **⚠️ USE SCREENSHOT VIEWING FOR DEBUGGING** - When tests fail, use `list_local_screenshots` and `view_local_screenshot` MCP commands to see exactly what the UI looked like. The filenames tell you which line of code triggered each screenshot.

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

@@ -312,4 +312,3 @@ describe('Assertions', () => {
 
 - [`extract()`](/v7/extract) - Extract information for detailed assertions
 - [`find()`](/v7/find) - Locate elements to verify
-- [`ai()`](/v7/ai) - Complex AI-driven tasks

package/ai/skills/testdriver-aws-setup/SKILL.md

@@ -192,7 +192,7 @@ Tests should use `context.ip || process.env.TD_IP` for the IP configuration:
 
 ```javascript
 import { describe, it } from "vitest";
-import { TestDriver } from "testdriverai/lib/vitest/hooks.mjs";
+import { TestDriver } from "testdriverai/vitest/hooks";
 
 describe("My Test", () => {
   it("should run on self-hosted instance", async (context) => {

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

@@ -1,11 +1,12 @@
 ---
 name: testdriver:caching
-description: 1.7x faster test execution with intelligent caching and optimization
+description: How TestDriver learns your app and caches what it discovers for instant, deterministic replays
 ---
 <!-- Generated from caching.mdx. DO NOT EDIT. -->
 
-TestDriver is engineered for performance with intelligent caching that delivers up to **1.7x faster** test execution by skipping redundant AI vision analysis.
+Once the agent has [explored your app](/v7/generating-tests), TestDriver remembers what it found. Every element the AI vision agent discovers is cached with a vision fingerprint—a perceptual hash of the screen state where it was located. On the next run, TestDriver matches against that cache instead of calling the AI again. Passing tests replay instantly, deterministically, and cheaply.
 
+This learning is what makes TestDriver fast. Intelligent caching delivers up to **1.7x faster** test execution by skipping redundant AI vision analysis—the agent only thinks when it sees something new.
 
 ```javascript
 // First run: builds cache
@@ -17,7 +18,7 @@ await testdriver.find('submit button');
 
 ## Automatic Caching
 
-Caching is enabled automatically with zero configuration. The cache key is computed from:
+Learning is enabled automatically with zero configuration. The cache key—the fingerprint TestDriver uses to recognize what it already knows—is computed from:
 
 - **File hash**: SHA-256 hash of the test file contents
 - **Selector prompt**: The exact text description passed to `find()`
@@ -53,7 +54,7 @@ You can clear the cache within the TestDriver console. There, you'll also find p
 
 ## Debugging Cache Hits and Misses
 
-You can track cache performance in your tests:
+You can track what TestDriver has learned by inspecting cache performance in your tests:
 
 ```javascript
 test('monitor cache performance', async (context) => {
@@ -75,7 +76,7 @@ test('monitor cache performance', async (context) => {
 
 ## Configuring the Cache
 
-You can configure cache behavior globally when initializing TestDriver:
+You can configure how TestDriver learns globally when initializing TestDriver:
 
 ```javascript
 import { TestDriver } from 'testdriverai';
@@ -103,7 +104,7 @@ await testdriver.find('submit button', {
 
 ## Caching with Variables
 
-Custom cache keys prevent cache pollution when using variables in prompts, dramatically improving cache hit rates.
+Custom cache keys prevent cache pollution when using variables in prompts, dramatically improving cache hit rates—so TestDriver reuses what it learned even when your data changes.
 
 ```javascript
 // ❌ Without cache key - creates new cache for each variable value
@@ -122,3 +123,9 @@ await testdriver.find(`order ${orderId} status`, {
   cacheKey: 'order-status'  // Same cache for all orders
 });
 ```
+
+## Next
+
+<Card href="/v7/copilot/running-tests" title="Run" icon="play">
+  Now that TestDriver has learned your app, run your tests in CI and locally—replaying the cache for fast, deterministic results.
+</Card>

package/ai/skills/testdriver-ci-cd/SKILL.md

@@ -6,29 +6,72 @@ description: Run TestDriver tests in CI/CD with parallel execution and cross-pla
 
 TestDriver integrates seamlessly with popular CI providers, enabling automated end-to-end testing on every push and pull request.
 
-## Adding Your API Key
+## Authentication
 
-TestDriver requires an API key to authenticate with the TestDriver cloud. Store this securely as a secret in your CI provider.
+On **GitHub Actions, prefer OIDC** via the published `testdriverai/action` —
+there's no `TD_API_KEY` secret to store, copy, or rotate. The action proves the
+workflow is running inside your org and TestDriver exchanges that proof for your
+team's key at run time. See the GitHub Actions tab below.
 
-<Steps>
-  <Step title="Get Your API Key">
-    Go to [console.testdriver.ai/team](https://console.testdriver.ai/team) and copy your team's API key
-  </Step>
-  <Step title="Add Secret to Your CI Provider">
-    Add `TD_API_KEY` as a secret environment variable in your CI provider's settings.
-  </Step>
-</Steps>
+For other CI providers (or self-hosted runners without OIDC), fall back to a
+stored API key from [console.testdriver.ai/team](https://console.testdriver.ai/team),
+added as a `TD_API_KEY` secret in your CI provider's settings.
 
 <Note>
-  Never commit your API key directly in code. Always use your CI provider's secrets management.
+  Never commit your API key directly in code. Always use OIDC or your CI provider's secrets management.
 </Note>
 
 ## CI Provider Examples
 
 <Tabs>
   <Tab title="GitHub Actions">
-    ### Adding Secrets
-    
+    ### Authenticate with OIDC via `testdriverai/action` (recommended)
+
+    Use the published [`testdriverai/action`](https://github.com/testdriverai/action) — it mints the OIDC token, exchanges it for your team's API key, and exports `TD_API_KEY` for the steps that follow. **No `TD_API_KEY` secret to store or rotate.**
+
+    <Note>
+      One-time setup: authorize the [TestDriver GitHub App](https://console.testdriver.ai) for your org so the org → team binding exists. If your org authorized the App before OIDC support shipped, re-authorize once. If the App isn't authorized, the action fails with a console link (or falls back to the `api-key` secret if you provide one).
+    </Note>
+
+    ```yaml .github/workflows/testdriver.yml
+    name: TestDriver Tests
+
+    on:
+      push:
+        branches: [main]
+      pull_request:
+        branches: [main]
+
+    jobs:
+      test:
+        runs-on: ubuntu-latest
+        permissions:
+          id-token: write   # REQUIRED to mint an OIDC token
+          contents: read
+
+        steps:
+          - uses: actions/checkout@v4
+
+          - uses: actions/setup-node@v4
+            with:
+              node-version: '20'
+              cache: 'npm'
+
+          - run: npm ci
+
+          - name: Authenticate to TestDriver
+            uses: testdriverai/action@stable   # pin @stable / @canary / @test to your SDK channel
+            with:
+              api-key: ${{ secrets.TD_API_KEY }}   # optional fallback if OIDC isn't set up
+
+          - name: Run TestDriver tests
+            run: npx vitest run
+    ```
+
+    ### Stored-key fallback
+
+    Only if you can't use OIDC (e.g. self-hosted runners without an OIDC provider). Add the key as a secret and pass it via `env`:
+
     1. Navigate to your GitHub repository
     2. Go to **Settings** → **Secrets and variables** → **Actions**
     3. Click **New repository secret**
@@ -571,7 +614,7 @@ When using multi-platform testing, read the `TD_OS` environment variable in your
 
 ```javascript tests/cross-platform.test.mjs
 import { describe, expect, it } from "vitest";
-import { TestDriver } from "testdriverai/lib/vitest/hooks.mjs";
+import { TestDriver } from "testdriverai/vitest/hooks";
 
 describe("Cross-platform tests", () => {
   it("should work on both Linux and Windows", async (context) => {

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

@@ -29,7 +29,7 @@ const testdriver = new TestDriver(apiKey, options)
     </ParamField>
     
     <ParamField path="resolution" type="string" default="1366x768">
-      Screen resolution for the sandbox (e.g., `'1920x1080'`, `'1366x768'`)
+      Screen resolution for the sandbox (e.g., `'1920x1080'`, `'1366x768'`). Custom resolutions are only available on Enterprise plans.
     </ParamField>
     
     <ParamField path="apiRoot" type="string">
@@ -44,7 +44,7 @@ const testdriver = new TestDriver(apiKey, options)
       Enable or disable console logging
     </ParamField>
     
-    <ParamField path="autoScreenshots" type="boolean" default="true">
+    <ParamField path="autoScreenshots" type="boolean" default="false">
       Automatically capture screenshots before and after each command. Screenshots are saved to `.testdriver/screenshots/<test>/` with descriptive filenames that include the line number and action name. Format: `<seq>-<action>-<phase>-L<line>-<description>.png`
     </ParamField>
     
@@ -53,11 +53,11 @@ const testdriver = new TestDriver(apiKey, options)
     </ParamField>
     
     <ParamField path="reconnect" type="boolean" default="false">
-      Reconnect to the last used sandbox instead of creating a new one. When `true`, provision methods (`chrome`, `vscode`, `installer`, etc.) will be skipped since the application is already running. Throws error if no previous sandbox exists.
+      Reattach to the last used sandbox instead of creating a new one. When `true`, the SDK reads the sandbox id from `.testdriver/last-sandbox` (written automatically on every successful connect) and rejoins that VM. Provision methods (`chrome`, `vscode`, `installer`, etc.) are skipped because the application is already running. The previous sandbox must still be alive — see [`keepAlive`](#keepalive) and the [Run guide](/v7/copilot/running-tests#keeping-machines-alive-between-runs).
     </ParamField>
-    
-    <ParamField path="keepAlive" type="number" default="60000">
-      Keep sandbox alive for the specified number of milliseconds after disconnect. Set to `0` to terminate immediately on disconnect. Useful for debugging or reconnecting to the same sandbox.
+
+    <ParamField path="sandboxId" type="string">
+      Reattach to a specific sandbox id instead of the one recorded in `.testdriver/last-sandbox`. Use this for CI matrices or to pin a chain of tests to a known VM. Implies `reconnect: true` behavior (provision calls are skipped).
     </ParamField>
     
     <ParamField path="preview" type="string" default="browser">
@@ -274,6 +274,10 @@ await testdriver.connect(options)
     <ParamField path="headless" type="boolean" default="false">
       **Deprecated**: Use `preview: "none"` instead. Run in headless mode without opening the debugger.
     </ParamField>
+    
+    <ParamField path="keepAlive" type="number" default="60000">
+      Keep sandbox alive for the specified number of milliseconds after disconnect. Set to `0` to terminate immediately on disconnect. Useful for debugging or reconnecting to the same sandbox.
+    </ParamField>
   </Expandable>
 </ParamField>
 

package/ai/skills/testdriver-customizing-devices/SKILL.md

@@ -39,7 +39,7 @@ const testdriver = TestDriver(context, {
 
   // === Recording & Screenshots ===
   dashcam: true,             // Enable/disable Dashcam video recording (default: true)
-  autoScreenshots: true,     // Capture screenshots before/after each command (default: true)
+  autoScreenshots: true,     // Capture screenshots before/after each command (default: false)
 
   // === AI Configuration ===
   ai: {                      // Global AI sampling configuration
@@ -283,9 +283,9 @@ const testdriver = TestDriver(context, {
 });
 ```
 
-### Reconnecting to Existing Sandbox
+### Connecting to an Existing Sandbox
 
-Speed up test development by reconnecting to an existing sandbox instead of starting fresh each time. This lets you iterate quickly on failing steps without re-running the entire test from the beginning.
+Speed up test development by connecting to an existing sandbox instead of starting fresh each time. This lets you iterate quickly on failing steps without re-running the entire test from the beginning.
 
 Split your test into two files: one for known-good steps that set up the desired state, and another for work-in-progress steps you want to debug.
 
@@ -298,8 +298,10 @@ const testdriver = TestDriver(context, {
 ```javascript work-in-progress.test.mjs
 // Second test file: experiment.test.mjs (run within keepAlive window)
 const testdriver = TestDriver(context, {
-  reconnect: true,  // Reconnect to existing sandbox
+  keepAlive: 60000,
 });
+
+await testdriver.connect({ sandboxId: "sandbox-abc123" });
 ```
 
 Then, you can run both tests in sequence:
@@ -315,5 +317,5 @@ vitest run work-in-progress.test.mjs
 ```
 
 <Warning>
-  Reconnect only works if run within the `keepAlive` window of the previous test.
+  Connecting to the same machine only works if run within the `keepAlive` window of the previous test.
 </Warning>

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

@@ -71,8 +71,8 @@ new Dashcam(client, options)
   Configuration options
 
   <Expandable title="options properties">
-    <ParamField path="apiKey" type="string" default="4e93d8bf-3886-4d26-a144-116c4063522d">
-      Dashcam API key for authentication
+    <ParamField path="apiKey" type="string">
+      Dashcam API key for authentication. Set via `TD_API_KEY` environment variable.
     </ParamField>
 
     <ParamField path="autoStart" type="boolean" default={false}>
@@ -192,6 +192,29 @@ await dashcam.addApplicationLog(application, name)
 await dashcam.addApplicationLog('Google Chrome', 'Browser Logs');
 ```
 
+### addWebLog()
+
+Track web request logs by URL pattern:
+
+```javascript
+await dashcam.addWebLog(pattern, name)
+```
+
+<ParamField path="pattern" type="string" required>
+  URL pattern to match (e.g., `"*example.com*"`)
+</ParamField>
+
+<ParamField path="name" type="string" required>
+  Display name for the log
+</ParamField>
+
+**Returns:** `Promise<void>`
+
+**Example:**
+```javascript
+await dashcam.addWebLog('*example.com*', 'Web Logs');
+```
+
 ### addLog()
 
 Generic method to add any type of log:
@@ -209,7 +232,7 @@ await dashcam.addLog(config)
     </ParamField>
 
     <ParamField path="type" type="string" required>
-      Log type: `'file'`, `'stdout'`, or `'application'`
+      Log type: `'file'`, `'application'`, or `'web'`
     </ParamField>
 
     <ParamField path="path" type="string">
@@ -219,6 +242,10 @@ await dashcam.addLog(config)
     <ParamField path="application" type="string">
       Application name (required for type='application')
     </ParamField>
+
+    <ParamField path="pattern" type="string">
+      URL pattern to match (required for type='web', e.g., `"*example.com*"`)
+    </ParamField>
   </Expandable>
 </ParamField>
 
@@ -237,6 +264,12 @@ await dashcam.addLog({
   type: 'application',
   application: 'Google Chrome'
 });
+
+await dashcam.addLog({
+  name: 'Web Logs',
+  type: 'web',
+  pattern: '*example.com*'
+});
 ```
 
 ### isRecording()

package/ai/skills/testdriver-debugging-with-screenshots/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: testdriver:debugging-with-screenshots
-description: View and analyze saved screenshots using MCP commands for test debugging and development
+description: Diagnose failing tests with screenshots, replays, and logs
 ---
 <!-- Generated from debugging-with-screenshots.mdx. DO NOT EDIT. -->
 
 ## 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`
@@ -122,7 +122,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:**
 
@@ -328,6 +328,20 @@ Understanding the directory structure helps with efficient screenshot viewing:
 - All screenshots are PNG format
 - Disable automatic screenshots with `autoScreenshots: false` if needed
 
+## Interaction List Sidebar (Source of Truth)
+
+When viewing a test run in the TestDriver console, the **interaction list sidebar** displays a screenshot for each interaction call (find, click, type, assert, etc.). These screenshots show exactly what was on the screen at the time each interaction was executed.
+
+<Note>
+  **The sidebar screenshots are the source of truth.** If a test is behaving unexpectedly, check the screenshot attached to the specific interaction in the sidebar — it shows precisely what the AI saw when making its decision. This is more reliable than inferring screen state from test logs or local screenshots alone.
+</Note>
+
+Use the interaction list to:
+- **Verify what the AI saw** — confirm the correct page/state was visible when `find()` or `assert()` ran
+- **Debug misclicks** — see whether the target element was actually on screen
+- **Identify timing issues** — spot cases where the UI hadn't finished loading before an interaction fired
+- **Compare runs** — review interaction screenshots across multiple runs to catch flaky behavior
+
 ## Integration with Test Development
 
 ### During MCP Interactive Development
@@ -344,7 +358,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`
@@ -394,8 +408,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/ai/skills/testdriver-device-config/SKILL.md

@@ -28,7 +28,7 @@ await testdriver.provision.chrome({
 
 ```javascript
 import { describe, expect, it } from "vitest";
-import { TestDriver } from "testdriverai/lib/vitest/hooks.mjs";
+import { TestDriver } from "testdriverai/vitest/hooks";
 
 describe("Login Flow", () => {
   it("should log in successfully", async (context) => {
@@ -113,7 +113,7 @@ await testdriver.provision.chromeExtension({
 
 ```javascript
 import { describe, expect, it } from "vitest";
-import { TestDriver } from "testdriverai/lib/vitest/hooks.mjs";
+import { TestDriver } from "testdriverai/vitest/hooks";
 
 describe("Chrome Extension Test", () => {
   it("should load and interact with extension", async (context) => {
@@ -187,7 +187,7 @@ const filePath = await testdriver.provision.installer({
 
 ```javascript
 import { describe, expect, it } from "vitest";
-import { TestDriver } from "testdriverai/lib/vitest/hooks.mjs";
+import { TestDriver } from "testdriverai/vitest/hooks";
 
 describe("Desktop App Test", () => {
   it("should install and launch app", async (context) => {
@@ -209,7 +209,7 @@ describe("Desktop App Test", () => {
 
 ```javascript
 import { describe, expect, it } from "vitest";
-import { TestDriver } from "testdriverai/lib/vitest/hooks.mjs";
+import { TestDriver } from "testdriverai/vitest/hooks";
 
 describe("Windows App Test", () => {
   it("should install on Windows", async (context) => {
@@ -276,7 +276,7 @@ await testdriver.provision.vscode({
 
 ```javascript
 import { describe, expect, it } from "vitest";
-import { TestDriver } from "testdriverai/lib/vitest/hooks.mjs";
+import { TestDriver } from "testdriverai/vitest/hooks";
 
 describe("VS Code Test", () => {
   it("should open workspace with extensions", async (context) => {