Playwright can record your test runs as videos, making it incredibly easy to debug failures by visually replaying exactly what happened.
Here’s a Playwright test that navigates to a page, types into an input, and asserts a value:
import pytest
from playwright.sync_api import Page, expect
def test_example(page: Page):
page.goto("https://www.example.com")
page.locator("input[type='text']").type("hello")
expect(page.locator("input[type='text']")).to_have_value("hello")
To enable video recording, you don’t need to modify your test code. Instead, you control it via the Playwright CLI or the pytest-playwright plugin.
Running with Playwright CLI
When running your tests using npx playwright test, you can enable video recording with the --video option. The most common setting is on, which records a video for every test that runs.
npx playwright test --video on
This command will execute your tests, and for each test file, a videos directory will be created, containing .webm files named after your tests. If a test fails, Playwright automatically attaches a link to the video in the test output.
Running with pytest-playwright
If you’re using pytest with the pytest-playwright plugin, video recording is also controlled via command-line arguments. The syntax is similar:
pytest --video on
Similar to the CLI, this will generate a videos directory alongside your test results. The output will also link to the recorded videos for failed tests.
Capturing Videos Conditionally
You might not want to record videos for every single test, especially in large test suites, as it can consume significant disk space and add overhead. Playwright offers more granular control:
--video off: Disables video recording entirely. This is the default.--video on: Records a video for every test.--video retain-on-failure: Records a video only for tests that fail. This is often the most practical setting for CI/CD pipelines.--video on-first-retry: Records a video for the first run of a test and for any subsequent retries. This is useful when using Playwright’s retry capabilities to debug intermittent failures.
For example, to only record videos for failing tests:
pytest --video retain-on-failure
Video Output Location
By default, Playwright creates a videos directory in the root of your project where all .webm video files are stored. You can change this directory using the --video-output-dir option:
npx playwright test --video on --video-output-dir ./test-recordings
This will place all recorded videos into the test-recordings folder instead of videos.
Understanding the Video Format
Playwright records videos in the .webm format. This is a highly efficient format suitable for web streaming and playback. Most modern browsers can play .webm files directly. If you need to convert them to other formats (like MP4), you can use tools like ffmpeg:
ffmpeg -i my_test_video.webm -c copy my_test_video.mp4
The video captures the entire browser interaction, including page loads, user actions, and any visual changes that occur during the test execution. This makes it invaluable for understanding the exact sequence of events leading to a failure, especially for complex UI interactions or when debugging asynchronous operations.
The Power of Visual Debugging
The true power of Playwright’s video recording lies in its ability to provide a clear, chronological view of your test’s execution. Instead of sifting through logs or trying to mentally reconstruct what happened, you can simply watch the video. This is particularly effective for:
- Visual Regressions: Identifying unexpected visual changes in your UI.
- Complex User Flows: Debugging multi-step interactions that are hard to follow in code.
- Timing Issues: Observing race conditions or timing-related flakiness.
- Understanding State: Seeing the exact state of the application at the moment of failure.
Playwright automatically synchronizes the video playback with the test execution timeline. When a test fails, the video will often stop precisely at the point of failure, highlighting the problematic element or interaction.
Playwright Trace Viewer Integration
While videos are great, Playwright’s Trace Viewer offers an even more comprehensive debugging experience. When you enable tracing (--trace on), Playwright captures a rich set of debugging information, including DOM snapshots, network requests, console logs, and importantly, the video recording.
The Trace Viewer allows you to play back the video within the viewer, synchronized with all other debugging artifacts. This means you can see the video, inspect the DOM at any point, view console logs, and examine network requests all in one place.
To enable tracing along with video:
pytest --trace on --video on
After running your tests, Playwright will output a link to the Trace Viewer. Opening this link in your browser will present a detailed, interactive report of your test run, with the video playback integrated seamlessly.
The most surprising thing about Playwright’s video recording is how it can make even seemingly simple test failures instantly understandable by providing a direct visual narrative of the execution. Instead of inferring state from logs, you see the state.
The next logical step after mastering video recording is to explore Playwright’s built-in tracing capabilities, which offer an even deeper dive into test execution.