screenshot()

Save a screenshot of the sandbox screen to a PNG file in your project.

Save what the sandbox screen shows right now as a PNG file. Use it to record a checkpoint you want to look at later.

const screenshotPath = await testdriver.screenshot('cart-before-checkout');

To capture every step without calling it yourself, turn on autoScreenshots instead. See Screenshots.

Signature

testdriver.screenshot(filename?: string): Promise<string>

Parameters

filename · string

The file name. TestDriver adds .png if it’s missing. Without it, the file is named screenshot-<timestamp>.png.

Returns

Promise<string>. The absolute path of the saved file.

Where files are saved

Screenshots go to .testdriver/screenshots/<test file>/ in the directory you run tests from. <test file> is the test file’s name without its last extension, so tests/login.test.mjs saves to .testdriver/screenshots/login.test/.

.testdriver/screenshots/login.test/
  cart-before-checkout.png
  screenshot-1729512345678.png

TestDriver clears each test file’s folder at the start of every run. Copy any screenshot you want to keep.

Add the folder to .gitignore:

.gitignore

.testdriver/screenshots/

Examples

Save a named checkpoint

await testdriver.find('Checkout button').click();
await testdriver.screenshot('checkout-page');

Log the path

const screenshotPath = await testdriver.screenshot();
console.log(screenshotPath);
// /Users/you/my-app/.testdriver/screenshots/login.test/screenshot-1729512345678.png

Complete example

tests/login.test.mjs

import { describe, expect, it } from 'vitest';
import { TestDriver } from 'testdriverai/vitest/hooks';

describe('Login', () => {
  it('shows an error for an empty form', async (context) => {
    const testdriver = TestDriver(context);
    await testdriver.provision.chrome({ url: 'https://testdriver-sandbox.vercel.app/login' });

    await testdriver.screenshot('login-empty');

    await testdriver.find('Sign in button below the password field').click();
    await testdriver.screenshot('login-error');

    const result = await testdriver.assert('an error says the fields are required');
    expect(result).toBe(true);
  });
});

Related

• Screenshots: capture every step automatically with autoScreenshots
• Debug a failing test: view saved screenshots from your AI client
• Dashcam: watch a video replay of the whole test