How do I take a screenshot when a Playwright test fails?

Configure screenshot: 'only-on-failure' in the use options in playwright.config.ts or via test.use(). Playwright automatically captures a screenshot when a test fails and attaches it to the test results.

This answer is one piece of Chapter 26: Reporting.

HTML Reports & Custom Reporters
Allure: Reports for Managers
JUnit XML for CI Dashboards

Visual evidence is essential for diagnosing test failures in CI. Rather than writing manual try/catch blocks or afterEach hooks, Playwright provides native declarative configuration for automatic failure screenshots.

In playwright.config.ts or within an individual spec file via test.use(), set screenshot: 'only-on-failure' inside the use options. When a test passes, no screenshot is captured, avoiding unnecessary disk and CPU overhead. When an assertion or action fails, Playwright captures the viewport at the end of the failed test run.

The resulting image is saved into your test artifact directory (test-results/) and attached to the run report. You can also capture on-demand screenshots during normal execution by calling await page.screenshot({ path: 'screenshot.png' }).

screenshot-failure.spec.js(https://practice.learnplayforge.com)

import { test, expect } from '@playwright/test';

test.use({ screenshot: 'only-on-failure' });

test('captures screenshot on assertion failure', async ({ page }) => {
  await page.goto('/catalog.html?mock=static&seed=42');
  await expect(page.locator('#missing-element')).toBeVisible({ timeout: 1000 });
});

Output

Running 1 test using 1 worker

  x  1 screenshot-failure.spec.js:5:1 › captures screenshot on assertion failure (2.1s)

  1) screenshot-failure.spec.js:5:1 › captures screenshot on assertion failure ───────

    Error: expect(locator).toBeVisible() failed

    Locator: locator('#missing-element')
    Expected: visible
    Timeout: 1000ms
    Error: element(s) not found

    attachment #1: screenshot (image/png) ──────────────────────────────────────────────────────────
    test-results/screenshot-failure-captures-screenshot-on-assertion-failure/test-failed-1.png
    ────────────────────────────────────────────────────────────────────────────────────────────────

  1 failed

Test yourself

How can you automatically capture a screenshot on test failure across all tests without writing try/catch blocks?

AI can write the test now. The job is knowing whether it checks anything. That's what the course teaches, one chapter at a time.

163 lessons · 226 drills · start free

How do I take a screenshot when a Playwright test fails?

Related questions