Screenshot Testing in Playwright

Introduction

A picture is worth a thousand lines of log files. When an automated test fails, your first instinct is to ask: "What did the page actually look like at that moment?" In Playwright, capturing this visual evidence is not just an option—it's a core feature.

Whether you're generating reports for stakeholders, debugging a tricky intermittent failure, or simply documenting a new feature, Screenshot Testing in Playwright gives you the tools to capture whatever you need, exactly when you need it. In this guide, we'll cover the various ways to capture and manage screenshots in 2026.

---

Basic Screenshot Captures

Playwright allows you to take screenshots at any point during a test.

1. Full Page Screenshot

This captures the entire scrollable height of the page, not just what's currently visible in the viewport.

test('Should take a full page screenshot', async ({ page }) => {
  await page.goto('https://myapp.com');
  await page.screenshot({ path: 'screenshots/homepage.png', fullPage: true });
});

2. Element-Only Screenshot

Sometimes you only care about a specific component.

test('Should take a screenshot of a specific locator', async ({ page }) => {
  await page.goto('https://myapp.com');
  const loginForm = page.locator('#login-form');
  await loginForm.screenshot({ path: 'screenshots/login-form.png' });
});

---

Automatic Screenshots on Failure

One of the best ways to use screenshots is to only capture them when a test fails. This saves disk space and keeps your reports clean.

Configuration

In your playwright.config.ts, set the screenshot option under use:

import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    screenshot: 'only-on-failure', // Options: 'off', 'on', 'only-on-failure'
  },
});

With this setting, Playwright will automatically save a screenshot to the test-results folder if any assertion fails.

---

Advanced Screenshot Features

1. Masking Sensitive Information

If your app displays PII (Personally Identifiable Information) like credit card numbers or user emails, you can mask them before saving the screenshot.

await page.screenshot({ 
  path: 'screenshots/protected.png', 
  mask: [page.locator('.user-credit-card')] 
});

2. Handling Animations

To avoid blurry screenshots caused by CSS transitions, you can disable them during capture.

await page.screenshot({ 
  path: 'screenshots/stable.png', 
  animations: 'disabled' 
});

3. Image Formats

By default, Playwright uses PNG, but you can also export to JPEG for smaller file sizes.

await page.screenshot({ 
  path: 'screenshots/large-page.jpg', 
  type: 'jpeg',
  quality: 80 
});

---

Organizing Your Screenshots

When running thousands of tests, a single screenshots/ folder becomes a mess. Use structured naming conventions:

• screenshots/{browser}/{os}/{test-name}.png
• Use Playwright's default test-results folder for CI/CD portability.

---

Conclusion

Screenshots are an essential bridge between automation and reality. They provide the context needed to understand why a test failed and allow you to prove that a feature is working as intended. By mastering the various screenshot options in Playwright, you'll create a more transparent and robust testing environment that both developers and QA engineers will appreciate.

---