/testdriver-screenshot

name: testdriver:screenshot
description: Capture and save screenshots during test execution

<!-- 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 st