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

```javascript
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

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

### Custom Filename

```javascript
// 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

```javascript
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

```javascript
// 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:

```javascript
// 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](/debugging-with-screenshots) - View and analyze saved screenshots using MCP
- [assert()](/assert) - Make AI-powered assertions
- [find()](/find) - Locate elements on screen