/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 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` </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 screenshots by test file or subdirectory (e.g., "login.test", "mcp-screenshots"). If omitted, lists all screenshots. </ParamField>

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

<ParamField path="lineRange" type="object" optional> Filter by 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
list_local_screenshots({ seque