Playwright Screenshots and Videos
This chapter introduces how to use Playwright for screenshots and video recording, helping you quickly locate issues when tests fail.
page.screenshot() Screenshots
Full-page Screenshot
Example
// Save to file
await page.screenshot({ path: 'screenshots/example-homepage.png' });
// Get Buffer data (use directly, do not write to file)
const buffer = await page.screenshot();
await page.screenshot({ path: 'screenshots/example-homepage.png' });
// Get Buffer data (use directly, do not write to file)
const buffer = await page.screenshot();
Screenshot Options
Example
await page.screenshot({
path: 'screenshots/full-page.png',
fullPage: true, // Capture the entire page (not just the viewport)
type: 'png', // Format: 'png' (default) or 'jpeg'
quality: 90, // JPEG quality (0-100, JPEG only)
clip: { // Clip area
x: 0,
y: 0,
width: 800,
height: 600,
},
animations: 'disabled', // Disable CSS animations (more stable screenshots)
omitBackground: false, // Whether to hide the default background
});
path: 'screenshots/full-page.png',
fullPage: true, // Capture the entire page (not just the viewport)
type: 'png', // Format: 'png' (default) or 'jpeg'
quality: 90, // JPEG quality (0-100, JPEG only)
clip: { // Clip area
x: 0,
y: 0,
width: 800,
height: 600,
},
animations: 'disabled', // Disable CSS animations (more stable screenshots)
omitBackground: false, // Whether to hide the default background
});
Element Screenshot
Example
// Take a screenshot of a specific element
await page.getByRole('navigation').screenshot({ path: 'nav.png' });
// Capture a button
await page.getByRole('button', { name: 'Submit' }).screenshot({ path: 'btn.png' });
await page.getByRole('navigation').screenshot({ path: 'nav.png' });
// Capture a button
await page.getByRole('button', { name: 'Submit' }).screenshot({ path: 'btn.png' });
Automatic Screenshot Configuration
Set the automatic screenshot policy in the configuration file without manually calling it in each test:
Example
// File path: playwright.config.ts
export default defineConfig({
use: {
// Automatically take screenshots only when tests fail
screenshot: 'only-on-failure',
// Optional values:
// 'off' — Do not take screenshots
// 'on' — Take a screenshot for every test
// 'only-on-failure' — Only take a screenshot on failure (recommended)
},
});
export default defineConfig({
use: {
// Automatically take screenshots only when tests fail
screenshot: 'only-on-failure',
// Optional values:
// 'off' — Do not take screenshots
// 'on' — Take a screenshot for every test
// 'only-on-failure' — Only take a screenshot on failure (recommended)
},
});
Failure screenshots are saved in thetest-results/directory and displayed in the HTML report.
Video Recording
Configuring Video Recording
Example
// File path: playwright.config.ts
export default defineConfig({
use: {
// Only keep videos on failure
video: 'retain-on-failure',
// Optional values:
// 'off' — Do not record
// 'on' — Record every time
// 'retain-on-failure' — Keep on failure, delete on pass (recommended)
// 'on-first-retry' — Only record on the first retry
},
});
export default defineConfig({
use: {
// Only keep videos on failure
video: 'retain-on-failure',
// Optional values:
// 'off' — Do not record
// 'on' — Record every time
// 'retain-on-failure' — Keep on failure, delete on pass (recommended)
// 'on-first-retry' — Only record on the first retry
},
});
Manual Video Control
Example
test('Manually save video', async ({ page }) => {
await page.goto('https://www.example.com/');
// Perform actions
await page.getByText('EXAMPLE Tutorial').click();
// Get the video object
const video = page.video();
// Save the video to the specified path
await video.saveAs('videos/example-test.mp4');
// Or delete the video
// await video.delete();
});
await page.goto('https://www.example.com/');
// Perform actions
await page.getByText('EXAMPLE Tutorial').click();
// Get the video object
const video = page.video();
// Save the video to the specified path
await video.saveAs('videos/example-test.mp4');
// Or delete the video
// await video.delete();
});
Video Recording Options
Example
// File path: playwright.config.ts
export default defineConfig({
use: {
video: {
mode: 'retain-on-failure',
size: { width: 1280, height: 720 }, // Video size
},
},
});
export default defineConfig({
use: {
video: {
mode: 'retain-on-failure',
size: { width: 1280, height: 720 }, // Video size
},
},
});
Use Cases for Screenshots and Videos
| Scenario | Recommended Solution |
|---|---|
| Quickly understand the page state when CI tests fail | screenshot: 'only-on-failure' |
| View the complete test execution process | video: 'retain-on-failure' |
| Visual regression testing | expect(page).toHaveScreenshot() |
| Debug specific steps | Manual invocationpage.screenshot() |
Other ExtensionsScreenshots and videos increase test execution time and disk usage. It is recommended to use them only in production environments
'only-on-failure'or'retain-on-failure'to avoid generating media files every time.