Skip to main content

​
Overview

Capture a screenshot of the current screen and automatically save it to a local file. Screenshots are organized by test file for easy debugging and review.
Automatic Screenshots (Default: Enabled): TestDriver automatically captures screenshots before and after every command (click, type, find, etc.). These are saved with descriptive filenames like 001-click-before-L42-submit-button.png that include the line number from your test file. You can disable this with autoScreenshots: false in your TestDriver options.

​
Syntax

const filePath = await testdriver.screenshot(filename)

​
Parameters

​
filename
string
Custom filename for the screenshot (without .png extension). If not provided, a timestamp-based filename is generated automatically.

​
Returns

Promise<string> - The absolute file path where the screenshot was saved

​
File Organization

Screenshots are automatically saved to .testdriver/screenshots/<test-file-name>/ in your project root: 
.testdriver/
  screenshots/
    login.test/
      001-find-before-L15-email-input.png     # Auto: before find()
      002-find-after-L15-email-input.png      # Auto: after find()
      003-click-before-L16-email-input.png    # Auto: before click()
      004-click-after-L16-email-input.png     # Auto: after click()
      005-type-before-L17-userexamplecom.png  # Auto: before type()
      006-type-after-L17-userexamplecom.png   # Auto: after type()
      custom-screenshot.png                    # Manual: screenshot("custom-screenshot")
    checkout.test/
      001-find-before-L12-checkout-button.png
      ...

​
Automatic Screenshot Naming

When autoScreenshots is enabled (default), filenames follow this format: <seq>-<action>-<phase>-L<line>-<description>.png
ComponentDescriptionExample
seqSequential number (001, 002, …)001
actionCommand nameclick, type, find
phaseBefore, after, or errorbefore, after
L<line>Line number from test fileL42
descriptionElement description or action targetsubmit-button
The screenshot folder for each test file is automatically cleared when the test starts. This ensures you only see screenshots from the most recent test run.

​
Examples

​
Basic Screenshot

// Capture a screenshot with auto-generated filename
const screenshotPath = await testdriver.screenshot();
console.log('Screenshot saved to:', screenshotPath);

​
Custom Filename

// Save with a descriptive filename
await testdriver.screenshot("login-page");
// Saves to: .testdriver/screenshots/<test>/login-page.png

await testdriver.screenshot("after-click");
// Saves to: .testdriver/screenshots/<test>/after-click.png

​
Debugging with Screenshots

import { describe, expect, it } from "vitest";
import { TestDriver } from "testdriverai/lib/vitest/hooks.mjs";

describe("Login Flow", () => {
  it("should log in successfully", async (context) => {
    const testdriver = TestDriver(context);
    
    await testdriver.provision.chrome({
      url: 'https://myapp.com/login',
    });

    // Capture initial state
    await testdriver.screenshot();

    // Fill in login form
    const emailInput = await testdriver.find("email input");
    await emailInput.click();
    await testdriver.type("[email protected]");

    // Capture state after typing
    await testdriver.screenshot();

    const passwordInput = await testdriver.find("password input");
    await passwordInput.click();
    await testdriver.type("password123");

    // Capture before clicking login
    await testdriver.screenshot();

    const loginButton = await testdriver.find("Login button");
    await loginButton.click();

    // Capture after login attempt
    await testdriver.screenshot();

    const result = await testdriver.assert("dashboard is visible");
    expect(result).toBeTruthy();
  });
});

​
Automatic Screenshots

By default, TestDriver captures screenshots automatically before and after every command. This creates a complete visual timeline of your test execution without any additional code.

​
Enabling/Disabling

// Auto-screenshots enabled by default
const testdriver = TestDriver(context);

// Explicitly disable if needed (not recommended)
const testdriver = TestDriver(context, {
  autoScreenshots: false
});

​
What Gets Captured

Automatic screenshots are taken around these commands:
  • find() / findAll()
  • click() / hover() / doubleClick() / rightClick()
  • type() / pressKeys()
  • scroll() / scrollUntilText() / scrollUntilImage()
  • waitForText() / waitForImage()
  • focusApplication()
  • assert() / extract() / exec()

​
Example Output

For this test code: 
// Line 15: Find email input
const emailInput = await testdriver.find("email input");
// Line 16: Click it
await emailInput.click();
// Line 17: Type email
await testdriver.type("[email protected]");
TestDriver automatically saves: 
001-find-before-L15-email-input.png
002-find-after-L15-email-input.png
003-click-before-L16-email-input.png
004-click-after-L16-email-input.png
005-type-before-L17-userexamplecom.png
006-type-after-L17-userexamplecom.png
If an error occurs, the phase will be error instead of after.

​
Best Practices

With autoScreenshots: true (default), you get comprehensive coverage without adding manual screenshot() calls. Only add manual screenshots for specific named checkpoints.
When a test fails intermittently, add screenshots at key steps to capture the actual screen state. This helps identify timing issues or unexpected UI states.
Take a screenshot before making assertions. If the assertion fails, you’ll have a visual record of what the screen looked like.
await testdriver.screenshot();
const result = await testdriver.assert("checkout button is visible");
Add .testdriver/screenshots/ to your .gitignore to avoid committing screenshots to version control:
# .gitignore
.testdriver/screenshots/

​
Viewing Saved Screenshots

After saving screenshots during test execution, you can view them using TestDriver MCP commands. This is especially useful for debugging failed tests or verifying test behavior.

​
MCP Commands for Screenshot Viewing

List all saved screenshots: 
list_local_screenshots()
View a specific screenshot: 
view_local_screenshot({ path: "/full/path/to/screenshot.png" })
These commands allow you to:
  • View screenshots from failed tests to understand what went wrong
  • Review test execution flow by examining screenshots in chronological order
  • Compare screenshots across test runs to identify flaky behavior
For detailed workflows and examples of using these MCP commands for debugging, see the Debugging with Screenshots guide.