For Playwright Test, set the use.video option in playwright.config.ts. For a script using Playwright directly, pass recordVideo to browser.newContext(). In either case, await the browser context closing before treating a normal recording as complete. Use the Screencast API instead if you need explicit start-and-stop control.
Choose the recording method
Playwright offers two main paths for recording browser activity. If your automation runs under Playwright Test, configure its video option and choose which tests should retain recordings. If you are using the Playwright library without the test runner, enable video when creating a browser context. Both approaches normally finalize their recording when that context closes. For a recording you start and stop yourself, the Screencast API has explicit controls.
| Use case | Method | When recording is saved |
|---|---|---|
| Playwright Test runs | use.video in the test configuration |
When the test’s browser context closes |
| Direct Playwright library script | recordVideo in browser.newContext() |
When the context closes |
| Explicitly controlled recording | page.screencast.start() and page.screencast.stop() |
When the screencast is stopped |
The official Playwright video guide covers test-runner modes and direct library setup. The Browser API, Video API, and Screencast API document the related options and lifecycle behavior.
Record videos in Playwright Test
Video recording is off by default. Set use.video in your Playwright Test configuration to enable it. The choice controls which test executions produce recordings, which matters when retaining every video would create unnecessary artifacts.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11#1 Best Overall
Configure a recording mode
In playwright.config.ts, import defineConfig and choose a mode:
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
video: 'on-first-retry',
},
});The documented modes are:
'off': do not record; this is the default.'on': record every test.'retain-on-failure': record tests, then remove videos for successful runs.'on-first-retry': record on the first retry.
Choose 'on' when you need a video for every run, such as when examining a sequence regardless of outcome. Choose 'retain-on-failure' when the useful artifact is the one associated with a failed test. Choose 'on-first-retry' when you want a recording during a retry without recording every initial run. These modes are retention and capture policies, not a way to control recording partway through a test.
Find the output
Playwright Test writes video files to the test output directory, typically test-results. The recording is saved when the test’s browser context closes at the end of the test. Do not inspect or copy a file as though it were complete before that lifecycle boundary. The exact output location can depend on the test output configuration; the guide describes test-results as the typical directory, not a universal fixed path.
Record video with the Playwright library
When you are not using the test runner, pass a recordVideo object when creating the browser context. Its dir property chooses the output directory; its optional size property sets the frame width and height.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsconst context = await browser.newContext({
recordVideo: {
dir: 'videos/',
size: { width: 1280, height: 800 },
},
});
const page = await context.newPage();
await page.goto('https://example.com');
// Perform the browser actions you want to capture.
await context.close();This example assumes browser is an already-created Playwright browser instance and that the videos/ directory is an appropriate destination. The important save step is await context.close(): normal context recordings are finalized at closure. If your script exits or moves on before awaiting it, you may try to use a recording before it has been saved.
Choose output dimensions
Set recordVideo.size when the resulting video needs known dimensions. If you omit it, the recording follows the viewport scaled to fit within 800 × 800 pixels. If you do not configure a viewport, the documented default is 800 × 450 pixels. These are documented defaults, not a promise that every source viewport will produce the same output dimensions. For a video intended for a particular display or artifact pipeline, set the dimensions explicitly and choose the browser viewport deliberately.
Get, save, or delete a recording
Each page associated with video recording has a Video object. Its methods have different timing and connection behavior, so choose based on whether you need a local path, a copy at a chosen location, or removal.
video.path()returns the output path after the context closes. It throws when connected remotely.video.saveAs(path)saves a copy to the path you choose. It may be called while recording is in progress or after the page closes, and it waits for the page to close and the video to be fully saved.video.delete()deletes the video.
For example, if a local run needs a path after recording, first close the context and then request the path from the page’s video object:
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →const video = page.video();
await context.close();
const path = await video.path();
console.log(path);Keep the remote-connection limitation in mind: the documented path() method throws when connected remotely. If you need to save the artifact at a known destination, use saveAs(path); its documented wait behavior means you can request the copy before the page closes and await completion, rather than assuming an in-progress file is ready.
Start and stop a recording explicitly
Use the Screencast API when the recording boundary should be controlled directly instead of being tied to a browser context’s lifetime. Start with a path and optional size, run the interaction, then stop to save the recording.
await page.screencast.start({
path: 'video.webm',
size: { width: 1280, height: 800 },
});
// Perform the browser actions you want to capture.
await page.screencast.stop();Here, the stop call is the save boundary for the explicit screencast. Use this API when the start/stop point itself is important; use recordVideo for context-based recording and its video-object methods when you need to manage the resulting artifact.
Common problems and fixes
No video appears after a test
Check the configured mode first. 'off' is the default, so it produces no recording. Also check whether the selected policy applies to that execution: 'on-first-retry' records on the first retry, while 'retain-on-failure' removes recordings for successful tests. For direct library use, confirm that the context was created with recordVideo.
Recommended Free Tools
The video file is missing or incomplete
For test-runner and direct context recording, await context closure before assuming the recording has been saved. In a direct script, ensure await context.close() runs after the browser actions. For an explicit screencast, await page.screencast.stop() before using the output.
video.path() throws
The Video API documents that path() throws when connected remotely. Use video.saveAs(path) to save the recording to a chosen destination; it waits for the page to close and the video to be fully saved.
The video dimensions are not what you expected
Set recordVideo.size explicitly when creating the context. Without it, the recording follows the viewport scaled to fit 800 × 800; without an explicit viewport, the documented default is 800 × 450. Check both the viewport you configured and the recording size instead of treating the default frame as a fixed output for every setup.
You need a recording for only part of a scenario
Test-runner video modes select which tests are recorded; direct recordVideo is associated with the browser context. For explicit start-and-stop control within a scenario, use page.screencast.start() and page.screencast.stop().
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Performance, reliability, and artifact handling
Recording creates an output artifact and affects what your test or automation run must manage. Pick the narrowest capture policy that still gives you useful evidence: every test for broad inspection, failure-oriented retention for debugging, or first-retry capture when the retry is the useful run. If you save artifacts to a separate destination, wait for the documented completion boundary before handing them to another process.
For reproducible output, explicitly set dimensions instead of relying on viewport scaling. Keep the distinction between recordVideo and Screencast clear: the former finalizes at context closure, while the latter gives you start/stop methods. The official documentation cited here establishes those APIs and lifecycle rules; it does not establish a performance benchmark or a particular storage, bandwidth, or file-size estimate, so plan those against your own workload rather than assuming a fixed cost.
Or skip the browser setup:
ScreenshotNeo is a website screenshot API, not a browser-video recorder; use it when a still screenshot or PDF is what you need, not as a substitute for Playwright video. Its one-request GET endpoint returns a PNG, JPEG, WebP, or PDF. For example, this cURL command captures a still image of https://example.com:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpSee the ScreenshotNeo documentation for request options. Before the screenshot, it accepts the cookie or consent banner like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each of those steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and whether the request was billed. It also offers an MCP server with take_screenshot, get_page_info, and capture_pdf tools for AI agents. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots.
Free tools Windows power users keep installed
One-click scans. No signup required.
Sign up for free: 1,000 screenshots a month, no card required.
Frequently Asked Questions
Can I call video.path() before the browser context closes?
The documented path becomes available after the context closes. If you want to request a saved copy while recording is in progress, use video.saveAs(path), which waits for the page to close and the video to be fully saved.
Does ScreenshotNeo record browser videos?
No. ScreenshotNeo returns screenshots or PDFs; Playwright’s video and Screencast APIs are the relevant choices for browser video.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
