testdriver:screenshot

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.

Syntax

const filePath = await testdriver.screenshot(filename)

Parameters

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

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

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

```
# .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

Related

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