Testdriver:Debugging With Screenshots

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.

MCP Commands

list_local_screenshots

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

Copy code
list_local_screenshots()

Filter Parameters:

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:

jsonCopy code
// 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:

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

Parameters:

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:

Copy code
// 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:

Copy code
// 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:

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

4. View the final state before failure:

Copy code
// 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:

Copy code
// 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:

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

// Get just the first 10 actions
list_local_screenshots({ sequenceRange: { start: 1, end: 10 }, sortBy: "sequence" })

// Get just the last 10 actions
list_local_screenshots({ directory: "checkout.test", sortBy: "sequence", limit: 10 })

Interactive Test Development

While building tests using MCP tools, view screenshots to verify your test logic:

1. After a test run, filter screenshots to see specific actions:

Copy code
// See all assertions
list_local_screenshots({ action: "assert" })

// See what happened at a specific line you're debugging
list_local_screenshots({ line: 25 })

2. Review key points in the test execution:

Copy code
view_local_screenshot({ path: ".testdriver/screenshots/my-test.test/after-login.png" })

3. Verify element locations and states before adding assertions

4. Iterate - adjust your test code based on what you see in the screenshots

Comparison and Analysis

Compare screenshots to identify issues:

Using phase filtering for before/after comparison:

Copy code
// See state before all clicks
list_local_screenshots({ action: "click", phase: "before" })

// See state after all clicks  
list_local_screenshots({ action: "click", phase: "after" })

Using line-based debugging:

Copy code
// Something went wrong around line 50
list_local_screenshots({ lineRange: { start: 45, end: 55 } })

Using regex patterns:

Copy code
// Find screenshots related to login functionality
list_local_screenshots({ pattern: "login|signin|email|password" })

Best Practices

Copy code
```javascript
await testdriver.screenshot("initial-page-load");
await testdriver.screenshot("after-login-click");
await testdriver.screenshot("dashboard-loaded");
```

Then when listing screenshots, you can quickly identify key moments without viewing every image.

Copy code
```
list_local_screenshots({ directory: "problematic-test.test" })
```

This avoids clutter from other tests.

Copy code
```bash
# Copy screenshots before next run
cp -r .testdriver/screenshots/my-test.test .testdriver/screenshots-backup/
```

Screenshot File Organization

Understanding the directory structure helps with efficient screenshot viewing:

Copy code
.testdriver/
  screenshots/
    login.test/              # Test file name (without .mjs extension)
      001-find-before-L15-email-input.png     # Auto: before find() at line 15
      002-find-after-L15-email-input.png      # Auto: after find() at line 15
      003-click-before-L16-email-input.png    # Auto: before click() at line 16
      004-click-after-L16-email-input.png     # Auto: after click() at line 16
      login-complete.png                       # Manual: screenshot("login-complete")
    checkout.test/
      001-find-before-L12-add-to-cart.png
      002-find-after-L12-add-to-cart.png
      ...

Automatic Screenshot Naming Format

<seq>-<action>-<phase>-L<line>-<description>.png

Key Points

• Each test file gets its own subdirectory
• Automatic screenshots include line numbers for easy tracing
• Manual screenshot() calls use custom names you provide
• Folders are cleared at the start of each test run
• 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.

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

When using TestDriver MCP tools (session_start, find_and_click, etc.), screenshots are automatically captured and displayed. Additionally, you can view previously saved screenshots:

Copy code
# After test development session
list_local_screenshots({ directory: "my-new-test.test" })
view_local_screenshot({ path: ".testdriver/screenshots/my-new-test.test/login-page.png" })

This helps verify your test logic before running the full test file.

After Test Runs

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
3. View relevant screenshots to diagnose the issue
4. Update test code based on what you see
5. Re-run and verify the fix

Troubleshooting

Copy code
- Ensure your test includes `await testdriver.screenshot()` calls
- Verify the test actually ran (check test output)
- Check that `.testdriver/screenshots/` directory exists
- Confirm you're in the correct project directory

Copy code
- Verify the path is exactly as returned by `list_local_screenshots`
- Check file permissions - ensure the screenshot file is readable
- Confirm the file hasn't been deleted or moved

Copy code
- Filter by test file: `list_local_screenshots({ directory: "my-test.test" })`
- Filter by line number: `list_local_screenshots({ line: 42 })` or `list_local_screenshots({ lineRange: { start: 40, end: 50 } })`
- Filter by action: `list_local_screenshots({ action: "click" })`
- Filter by phase: `list_local_screenshots({ phase: "before" })`
- Use regex: `list_local_screenshots({ pattern: "submit|login" })`
- Limit results: `list_local_screenshots({ limit: 10 })`
- Sort by line: `list_local_screenshots({ sortBy: "line" })`
- Clean up old folders: `rm -rf .testdriver/screenshots/*`

Copy code
- The test may not have run recently
- Or the test failed before reaching the clearing logic
- Manually clear: `rm -rf .testdriver/screenshots/<test-name>/`

Where this fits in the Guide

Debugging is what you reach for when a Run goes sideways or a Validate 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() - Capture screenshots during test execution
• Dashcam - Record full test sessions with video and logs
• assert() - Make AI-powered assertions that benefit from screenshot context

Next