testdriver:screenshot

<!-- Generated from screenshot.mdx. DO NOT EDIT. -->

Overview

Capture a screenshot of the screen. TestDriver saves it to a local file automatically. TestDriver groups the screenshots by test file. This makes debug and review easy.

<Note> **Automatic Screenshots**: TestDriver can capture screenshots automatically before and after each command (click, type, find, and more). It saves them with clear filenames such as `001-click-before-L42-submit-button.png`. The filename includes the line number from your test file. Enable this with `autoScreenshots: true` in your TestDriver options. </Note>

Syntax

const filePath = await testdriver.screenshot(filename)

Parameters

<ParamField path="filename" type="string" optional> A custom filename for the screenshot (without the .png extension). If you do not give one, TestDriver makes a filename from the timestamp automatically. </ParamField>

Returns

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

File Organization

TestDriver saves screenshots automatically 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, filenames follow this format:

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

Component	Description	Example
seq	Sequential number (001, 002, ...)	001
action	Command name	click, type, find
phase	Before, after, or error	before, after
L<line>	Line number from test file	L42
description	Element description or action target	submit-button

<Note> 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. </Note>

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/vitest/hooks";

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("user@example.com");

    // 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()
• 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("user@example.com");

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

<AccordionGroup> <Accordion title="Let automatic screenshots do the work"> With `autoScreenshots: true`, you get comprehensive coverage without adding manual `screenshot()` calls. Only add manual screenshots for specific named checkpoints. </Accordion> <Accordion title="Use screenshots for debugging flaky tests"> 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. </Accordion> <Accordion title="Capture before assertions"> Take a screenshot before making assertions. If the assertion fails, you'll have a visual record of what the screen looked like.

```javascript
await testdriver.screenshot();
const result = await testdriver.assert("checkout button is visible");
```

</Accordion> <Accordion title="Add to .gitignore"> Add `.testdriver/screenshots/` to your `.gitignore` to avoid committing screenshots to version control:

```
# .gitignore
.testdriver/screenshots/
```

</Accordion> </AccordionGroup>

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

<Note> For detailed workflows and examples of using these MCP commands for debugging, see the [Debugging with Screenshots](/debugging-with-screenshots) guide. </Note>

Related

• Debugging with Screenshots - View and analyze saved screenshots using MCP
• assert() - Make AI-powered assertions
• find() - Locate elements on screen