testdriver:screenshot

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

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

<Note>
  **Automatic Screenshots**: TestDriver can automatically capture 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. 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>
  Custom filename for the screenshot (without .png extension). If not provided, a timestamp-based filename is generated automatically.
</ParamField>

## 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, 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 asser