/testdriver-debugging-with-screenshots

name: testdriver:debugging-with-screenshots
description: Diagnose failing tests with screenshots, replays, and logs

<!-- Generated from debugging-with-screenshots.mdx. DO NOT EDIT. -->

Overview

When a test fails, debug it. Look at what happened. Do not guess. TestDriver captures screenshots, video replays, and logs while your test runs. Thus you can replay the moment of the failure. You do not need to look at a stack trace. TestDriver MCP gives commands to view and examine the screenshots that TestDriver saved during the test. This lets you debug quickly, develop tests, and compare, without a manual open of image files.

<Note> **Automatic Screenshots (Default: Enabled)**: TestDriver captures screenshots automatically before and after each command. The screenshot name has the line number and the action. Thus it is easy to see which line of code made each screenshot. For example: `001-click-before-L42-submit-button.png` </Note>

MCP Commands

list_local_screenshots

List and filter screenshots saved in the `.testdriver/screenshots/` directory:

list_local_screenshots()

**Filter Parameters:**

<ParamField path="directory" type="string" optional> Filter the screenshots by test file or subdirectory (for example, "login.test", "mcp-screenshots"). If you do not give this, the tool lists all screenshots. </ParamField>

<ParamField path="line" type="number" optional> Filter by the exact line number from the test file (for example, 42 matches L42 in the filename). </ParamField>

<ParamField path="lineRange" type="object" optional> Filter by a line number range. Example: `{ start: 10, end: 20 }` matches screenshots from lines 10-20. </ParamField>

<ParamField path="action" type="string" optional> Filter by action type: `click`, `find`, `type`, `assert`, `provision`, `scroll`, `hover`, etc. </ParamField>

<ParamField path="phase" type="string" optional> Filter by phase: `"before"` (state before action) or `"after"` (state after action). </ParamField>

<ParamField path="pattern" type="string" optional> Regex pattern to match against filename. Example: `"login|signin"` or `"button.*click"`. </ParamField>

<ParamField path="sequence" type="number" optional> Filter by exact sequence number. </ParamField>

<ParamField path="sequenceRange" type="object" optional> Filter by sequence range. Example: `{ start: 1, end: 10 }` matches first 10 screenshots. </ParamField>

<ParamField path="limit" type="number" optional> Maximum number of results to return (default: 50). </ParamField>

<ParamField path="sortBy" type="string" optional> Sort results by: `"modified"` (newest first, default), `"sequence"` (execution order), or `"line"` (line number). </ParamField>

**Returns:**

Array of screenshot metadata including:

• `path` - Full absolute path to the screenshot file
• `relativePath` - Path relative to `.testdriver/screenshots/`
• `name` - Screenshot filename
• `sizeBytes` - File size in bytes
• `modified` - Last modification timestamp
• `sequence` - Sequential number (from auto-screenshots)
• `action` - Action type (click, find, etc.)
• `phase` - Before/after phase
• `lineNumber` - Line number from test file
• `description` - Element or action description

**Example Responses:**

// Basic listing
[
  {
    "path": "/Users/user/project/.testdriver/screenshots/login.test/001-click-before-L42-submit-button.png",
    "relativePath": "login.test/001-click-before-L42-submit-button.png",
    "name": "001-click-before-L42-submit-button.png",
    "sizeBytes": 145632,
    "modified": "2026-01-23T10:00:00.000Z",
    "sequence": 1,
    "action": "click",
    "phase": "before",
    "lineNumber": 42,
    "description": "submit-button"
  }
]

view_local_screenshot

View a specific screenshot from the list:

view_local_screenshot({ path: "/full/path/to/screenshot.png" })

**Parameters:**

<ParamField path="path" type="string" required> Full absolute path to the screenshot file (as returned by `list_local_screenshots`) </ParamField>

**Returns:**

• Image content (displayed to both AI and user via MCP App)
• Screenshot metadata
• Success/error status

Common Workflows

Test Debugging After Failures

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:**

// If test failed at line 42
list_local_screenshots({ line: 42 })

// View before and after states at that line
view_local_screenshot({ path: ".testdriver/screenshots/login.test/005-click-before-L42-submit-button.png" })
view_local_screenshot({ path: ".testdriver/screenshots/login.test/006-click-after-L42-submit-button.png" })

**2. See what happened leading up to the failure:**

// Get screenshots from lines 35-45 to see context
list_local_screenshots({ directory: "login.test", lineRange: { start: 35, end: 45 } })

**3. Find all assertion screenshots:**

// See what the screen looked like during assertions
list_local_screenshots({ action: "assert" })

**4. View the final state before failure:**

// Get the last 5 screenshots in execution order
list_local_screenshots({ directory: "login.test", sortBy: "sequence", limit: 5 })

Finding Specific Actions

When debugging element interactions:

// Find all click actions
list_local_screenshots({ action: "click" })

// Find what the screen looked like BEFORE each click
list_local_screenshots({ action: "click", phase: "before" })

// Find screenshots related to a specific element using regex
list_local_screenshots({ pattern: "submit|button" })

// Find all type actions (for form filling issues)
list_local_screenshots({ action: "type" })

Understanding Test Flow

View screenshots in execution order to trace test behavior:

// Get screenshots in execution order
list_local_screenshots({ directory: "checkout.test", sortBy: "sequence" })

// Get just the first 10 actions