Video Steps

Video steps record the browser as a .webm video from inside a scenario - start recording, stop and flush to disk, and reserve a custom filename. Recordings are invaluable for failure forensics on distributed teams: instead of describing a flaky interaction in a bug report, you attach a replay of exactly what the browser did.

Playwright can only enable video at browser-context creation, so the mid-scenario start and stop steps work by tearing down the current page and context and reopening a fresh one with the recording flag flipped. That boundary matters: page state (current URL, cookies set during the scenario, form contents) is lost when the context is rebuilt. Call I start video recording before any navigation in the scenario, and call I stop video recording only when you no longer need the current page state.

Recording can also be enabled without any steps at all, via configuration: worldParameters.video.mode in cucumber.js supports off (default), on, on-failure, and tag modes, and the @video / @no-video scenario tags override the mode per scenario. The steps on this page are for the manual, mid-scenario workflow.

Quick reference

Step	What it does
`When I start video recording`	Reopen the browser with recording enabled; place before any navigation.
`When I stop video recording`	Flush the webm to disk and continue in a fresh, non-recording browser.
`When I save the current video as "checkout-flow.webm"`	Reserve a custom filename for the current scenario's video.
`Then print video path`	Print the path the current video will be written to (diagnostic only).

Steps in detail

`When I start video recording`

Closes the current page and context, then reopens the browser with Playwright's recordVideo option enabled. The output directory (default ./videos, configurable) is created if missing. Because the context is rebuilt, always place this step at the very top of the scenario, before Given I am on .... If the videos directory is not writable, the step fails with a friendly error that names the directory.

When I start video recording
Given I am on "/video-demo.html"
Then I should see "Webship-js Video Demo"

`When I stop video recording`

Closes the recording context - which is what flushes the .webm to disk - saves the file (using the name reserved with save the current video as, or an automatic manual.<timestamp>.webm name), then reopens a fresh, non-recording browser so the rest of the scenario can continue. The saved path is printed to the console as [webship-js] video saved → <path>. If recording was never started, the step is a no-op. Remember that stopping discards the current page state along with the context.

When I press "🎉 Celebrate"
Then I should see "Party time"
When I stop video recording

`When I save the current video as "<name>.webm"`

Reserves a custom filename for the current scenario's video. The actual file write happens later - either when stop video recording runs, or at scenario end - because Playwright's video.saveAs() blocks until recording finishes, so bytes cannot be copied mid-flight. The step fails with a hint if recording is not active (start it first, or set worldParameters.video.mode to "on") or if the filename is empty.

When I start video recording
Given I am on "/video-demo.html"
When I save the current video as "demo.webm"
When I stop video recording

`Then print video path`

Prints the path that the in-flight video will be written to. Purely diagnostic - it never asserts and never fails; when recording is off it simply prints Video path: recording is OFF. Useful when wiring recordings into a CI artifact step and you want the path in the run log.

When I start video recording
Given I am on "/video-demo.html"
Then print video path

Complete example

From tests/features/video.feature, which runs against the fixture page examples/video-demo.html:

@video
Feature: 🎬 Video recording

  As a tester, I want to record a short browser video so that I can attach it
  to a bug report and let reviewers replay what happened.

  Scenario: 🎥 Record a tiny click flow with emojis
    When I start video recording
    Given I am on "/video-demo.html"
    Then I should see "Webship-js Video Demo"
    When I press "👋 Wave"
    Then I should see "Hello, world"
    When I press "🚀 Launch"
    Then I should see "Liftoff!"
    When I press "🎉 Celebrate"
    Then I should see "Party time"
    When I save the current video as "demo.webm"
    When I stop video recording

Configuration

All video settings live under worldParameters.video in cucumber.js, each with an environment-variable override:

Key	Default	Env override	Meaning
`mode`	`off`	`WEBSHIP_VIDEO`	`off` - no recording. `on` - record every scenario. `on-failure` - record every scenario, keep only failures. `tag` - record only scenarios tagged `@video`.
`dir`	`./videos`	`WEBSHIP_VIDEO_DIR`	Output directory for `.webm` files.
`size`	`{ width: 1280, height: 720 }`	-	Viewport size of the recording.
`filenamePattern`	`{datetime}.{feature_file}.{scenario}.{status}.{ext}`	-	Automatic filename template; tokens are sanitized to filesystem-safe characters.

Per-scenario tags override the mode: @video forces recording on regardless of mode, and @no-video suppresses it.

Tips

For "record everything, keep failures" CI runs, prefer WEBSHIP_VIDEO=on-failure over manual steps - no scenario changes needed.
Use the manual steps when you want a demo or bug-report clip of one specific flow with a predictable filename.
Do not sandwich start video recording between navigation steps: the context rebuild logs the browser out and returns to a blank page.

Back to all step groups