The steps let testers capture PNG screenshots at
any point in a Cucumber scenario using Playwright, with support for fullscreen (full-page), sized (custom viewport), and named captures. Auto-capture hooks fire on
failed steps and on every step for scenarios tagged @screenshots.
Filename tokens
Tokens can be used inside any with name "..." step or in the filenamePattern / filenamePatternFailed config keys.
Auto-capture hooks
On failed step
When a step fails, a screenshot is saved automatically with the failedPrefix prepended to the filename. Controlled by onFailed (default true).
Per-step capture (@screenshots tag)
Tag any scenario with @screenshots to save a screenshot after every passing step:
@screenshots
Scenario: Capture every step on the contact page
Given I am on "/contact"
When I fill in "email" with "info@webship.co"
Then I should see "Contact Us" Or enable globally for all scenarios via onEveryStep: true in cucumber.js.
Configuration
All settings live in cucumber.js under worldParameters.screenshot. Every key can be overridden per-run with an environment variable.
// cucumber.js
worldParameters: {
screenshot: {
dir: './screenshots', // WEBSHIP_SCREENSHOT_DIR
purge: false, // WEBSHIP_SCREENSHOT_PURGE
onFailed: true, // WEBSHIP_SCREENSHOT_ON_FAILED
onEveryStep: false, // WEBSHIP_SCREENSHOT_ON_EVERY_STEP
alwaysFullscreen: false, // WEBSHIP_SCREENSHOT_FULLSCREEN
failedPrefix: 'failed_', // WEBSHIP_SCREENSHOT_FAILED_PREFIX
filenamePattern: '{datetime}.{feature_file}.feature_{step_line}.{ext}',
filenamePatternFailed: '{failed_prefix}{datetime}.{feature_file}.feature_{step_line}.{ext}',
infoTypes: '', // WEBSHIP_SCREENSHOT_INFO_TYPES e.g. "url,feature,step,datetime"
},
}
Priority chain (highest → lowest)
- process.env.WEBSHIP_SCREENSHOT_* — shell / CI
- worldParameters.screenshot.* — cucumber.js project defaults
- Built-in defaults
One-off CI example WEBSHIP_SCREENSHOT_DIR=/tmp/ci-shots \
WEBSHIP_SCREENSHOT_PURGE=true \
WEBSHIP_SCREENSHOT_ON_EVERY_STEP=true \
npm test
Output files
Each capture produces two files saved side-by-side:
- .png — Playwright screenshot
.html — Raw page HTML at the moment of capture (works even if the driver has no screenshot support)
If infoTypes is set (e.g. "url,feature,step,datetime"), metadata lines are prepended to the HTML file before saving.