Introduction: Why Automatic Screenshots Are Essential for Debugging Failed Tests in 2026
In modern test automation, simply knowing that a test failed is not enough. QA teams also need to understand why it failed. This is where screenshots become one of the most valuable debugging tools.
Playwright provides built-in support for automatically capturing screenshots when a test fails. These screenshots help testers identify UI issues, missing elements, incorrect page states, or unexpected application behavior without rerunning the test.
If you’re learning how to take screenshot in Playwright on failure, you’re building a skill used daily by QA Automation Engineers, SDETs, and DevOps teams in enterprise automation projects.
Whether you are:
- A QA Automation Engineer
- An SDET
- A Selenium engineer transitioning to Playwright
- A software testing student
- A web developer
- Preparing for Playwright interviews
Learning automatic failure screenshots will improve your debugging skills and make your automation framework easier to maintain.
This beginner-friendly guide covers:
- What is screenshot on failure?
- Why screenshots are important
- Configuring Playwright to capture screenshots automatically
- Taking screenshots manually
- Viewing screenshots in HTML reports
- CI/CD integration
- Real-world examples
- Best practices
- Troubleshooting tips
- Interview questions
- FAQs
What Is Screenshot on Failure in Playwright?
A screenshot on failure is an image automatically captured when a Playwright test does not pass.
Instead of only displaying an error message in the terminal, Playwright records the exact browser state at the time of failure.
Simple Definition
Taking a screenshot on failure in Playwright means automatically capturing the browser screen whenever a test fails to help identify and debug issues quickly.
Benefits
Automatic screenshots help you:
- Debug failed tests faster
- Identify UI rendering issues
- Capture unexpected application states
- Verify missing elements
- Investigate timeout failures
- Improve defect reporting
- Reduce debugging time
Real-World Use Cases
Failure screenshots are useful for:
- Login failures
- Checkout failures
- Missing buttons
- Validation errors
- Cross-browser issues
- Responsive UI problems
- Production defect analysis
- CI/CD test failures
Why Capture Screenshots on Test Failure?
Modern automation frameworks rely on screenshots because they provide visual evidence of what happened during execution.
Advantages
Capturing screenshots helps teams:
- Understand failures quickly
- Reduce investigation time
- Improve communication between QA and developers
- Simplify bug reporting
- Improve regression testing
- Speed up production issue analysis
Real-World Example
Suppose your login automation fails.
Instead of seeing only:
Timeout 30000ms exceeded
You also receive a screenshot showing:
- Login page loaded
- Username entered
- Password field empty
- Login button disabled
The screenshot immediately points to the real problem.
Step-by-Step Guide: How to Take Screenshot in Playwright on Failure
Step 1: Install Playwright
If you haven’t created a project yet:
mkdir playwright-demo
cd playwright-demo
npm init -y
npm init playwright@latest
Run:
npx playwright test
This verifies that Playwright is installed correctly.
Step 2: Configure playwright.config.ts
The easiest way to capture screenshots automatically is by updating your configuration file.
import { defineConfig } from ‘@playwright/test’;
export default defineConfig({
use: {
screenshot: ‘only-on-failure’,
},
});
Explanation
only-on-failure tells Playwright:
- Do not capture screenshots for successful tests.
- Capture a screenshot only when a test fails.
This keeps reports clean while saving storage space.
Screenshot Options
| Option | Description |
| off | Never capture screenshots |
| on | Capture screenshots for every test |
| only-on-failure | Capture screenshots only for failed tests |
For most automation projects, only-on-failure is the recommended option.
Step 3: Capture Screenshots Manually
Sometimes you may want screenshots at specific points during test execution.
import { test } from ‘@playwright/test’;
test(‘Take Screenshot’, async ({ page }) => {
await page.goto(‘https://example.com’);
await page.screenshot({
path: ‘screenshots/homepage.png’,
fullPage: true
});
});
Explanation
This code:
- Opens the website
- Captures a full-page screenshot
- Saves it to the screenshots folder
Manual screenshots are useful for documenting important application states.
Step 4: Capture Screenshot Before an Assertion
import { test, expect } from ‘@playwright/test’;
test(‘Login Test’, async ({ page }) => {
await page.goto(‘https://example.com/login’);
await page.fill(‘#username’, ‘admin’);
await page.fill(‘#password’, ‘password’);
await page.screenshot({
path: ‘screenshots/before-login.png’
});
await page.click(‘#login’);
await expect(page).toHaveTitle(/Dashboard/);
});
Practical Use Case
This helps compare:
- Application state before clicking Login
- Application state after test execution
Step 5: Run Tests
Execute:
npx playwright test
If a test fails, Playwright automatically captures the screenshot according to your configuration.
Step 6: Locate Generated Screenshots
Screenshots are typically stored inside:
test-results/
├── login-test/
│ ├── test-failed-1.png
│ ├── trace.zip
│ └── video.webm
These files are automatically linked to Playwright reports.
Integrating Screenshots with Playwright HTML Reports
npx playwright show-report
The HTML report displays:
- Failed tests
- Error messages
- Screenshots
- Traces
- Videos
- Execution time
This makes debugging much easier than reading console logs alone.
Workflow Diagram
│
▼
Test Pass?
│
┌───┴────┐
│ │
Yes No
│ │
│ ▼
│ Capture Screenshot
│ │
│ Save in test-results
│ │
│ Attach to HTML Report
▼
Finish
Running Screenshot Capture in CI/CD Pipelines
Automatic screenshots are especially useful when tests run on remote build servers.
GitHub Actions
Typical workflow:
↓
↓
Failed Test
↓
Screenshot Generated
↓
HTML Report Published
Developers can download the report and immediately inspect the failure.
Jenkins
In Jenkins:
- Execute Playwright tests
- Archive the test-results folder
- Publish the HTML report
- Review screenshots from the Jenkins build page
Azure DevOps
- Run Playwright tests
- Store screenshots as build artifacts
- Download artifacts for debugging failed tests
Real-World Screenshot Examples
1. Login Failure
await page.fill(‘#username’,’admin’);
await page.fill(‘#password’,’wrongpassword’);
await page.click(‘#login’);
Expected screenshot:
- Error message displayed
- Invalid credentials notification visible
2. Checkout Failure
Automation reaches checkout.
Payment button is missing.
Failure screenshot clearly shows:
- Shopping cart
- Missing checkout button
- Browser state
3. Element Not Found
Example:
await page.click(‘#submit’);
If #submit does not exist, Playwright captures the current page, making it easier to understand why the locator failed.
4. Timeout Error
If an element never becomes visible, the screenshot shows:
- Loading spinner
- Slow network response
- Incomplete page rendering
5. Cross-Browser Failure
A test passes in Chromium but fails in Firefox.
Failure screenshots help compare browser rendering differences without rerunning the test.
Best Practices for Screenshot Management
Follow these recommendations:
- Use only-on-failure in production automation.
- Store screenshots with reports.
- Keep meaningful file names.
- Archive screenshots in CI/CD.
- Delete old screenshots regularly.
- Capture full-page screenshots for debugging layout issues.
- Combine screenshots with traces and videos.
- Avoid capturing screenshots for every passing test unless necessary.
Recommended Folder Structure
playwright-project/
tests/
pages/
screenshots/
reports/
test-results/
playwright.config.ts
This keeps artifacts organized and easy to locate.
Common Screenshot Issues and Troubleshooting Tips
Issue 1: Screenshot Not Generated
Cause
Screenshot option is disabled.
Solution
Verify:
use: {
screenshot: ‘only-on-failure’
}
Issue 2: Blank Screenshot
Cause
Page had not finished loading.
Solution
Use:
await page.waitForLoadState();
before taking the screenshot.
Issue 3: Screenshot Saved in Wrong Location
Solution
Specify a custom path:
await page.screenshot({
path: ‘screenshots/login.png’
});
Issue 4: Screenshot Missing in HTML Report
Solution
Ensure:
- Tests are executed with Playwright Test.
- HTML reporter is enabled.
- Test results are not deleted before opening the report.
Issue 5: CI/CD Does Not Show Screenshots
Solution
Publish the test-results directory as a pipeline artifact.
Playwright Screenshot Interview Questions with Answers
1. How do you automatically capture screenshots on failure?
Configure:
use: {
screenshot: ‘only-on-failure’
}
2. Which method captures screenshots manually?
await page.screenshot();
3. Where are failure screenshots stored?
Usually inside:
test-results/
or the custom directory specified in your code.
4. Can screenshots be attached to Playwright HTML reports?
Yes. Playwright automatically links screenshots, traces, and videos in the HTML report when configured.
5. What is the best screenshot configuration?
For most projects:
screenshot: ‘only-on-failure’
This captures only failed tests and avoids unnecessary storage usage.
FAQs – How to Take Screenshot in Playwright on Failure
Q1. What is screenshot on failure in Playwright?
It is the process of automatically capturing a browser screenshot whenever a Playwright test fails.
Q2. What are the benefits of taking screenshots on failure?
Screenshots help identify UI issues, reduce debugging time, improve defect reports, and provide visual evidence of failures.
Q3. How do I get started with taking screenshots in Playwright on failure?
Update your playwright.config.ts file with:
use: {
screenshot: ‘only-on-failure’
}
Then run your tests normally.
Q4. Is screenshot capture suitable for beginners?
Yes. Playwright provides built-in support that requires only a few lines of configuration.
Q5. Can screenshots be used in CI/CD pipelines?
Yes. GitHub Actions, Jenkins, and Azure DevOps can archive screenshots and include them with Playwright HTML reports.