Behat extension to create screenshots

---

Features

• Captures a screenshot using the I save screenshot step.
• Automatically captures a screenshot when a test fails.
• Supports both HTML and PNG screenshots.
• Configurable screenshot directory.
• Automatically purges screenshots after each test run.
• Adds configurable additional information to screenshots.

Installation

composer require --dev drevops/behat-screenshot

Usage

Example behat.yml with default parameters:

default:
  suites:
    default:
      contexts:
        - DrevOps\BehatScreenshotExtension\Context\ScreenshotContext
        - FeatureContext
  extensions:
    DrevOps\BehatScreenshotExtension: ~

or with parameters:

default:
  suites:
    default:
      contexts:
        - DrevOps\BehatScreenshotExtension\Context\ScreenshotContext
        - FeatureContext
  extensions:
    DrevOps\BehatScreenshotExtension:
      dir: '%paths.base%/screenshots'
      on_failed: true
      purge: false
      failed_prefix: 'failed_'
      filename_pattern: '{datetime:u}.{feature_file}.feature_{step_line}.{ext}'
      filename_pattern_failed: '{datetime:u}.{failed_prefix}{feature_file}.feature_{step_line}.{ext}'

In your feature:

Given I am on "http://google.com"
Then I save screenshot

You may optionally specify the size of the browser window in the screenshot step:

Then I save 1440 x 900 screenshot

or a file name:

Then I save screenshot to "my_screenshot.png"

Options

Name	Default value	Description
dir	%paths.base%/screenshots	Path to directory to save screenshots. Directory structure will be created if the directory does not exist. Override with BEHAT_SCREENSHOT_DIR env var.
on_failed	true	Capture screenshot on failed test.
purge	false	Remove all files from the screenshots directory on each test run. Useful during debugging of tests.
info_types	url, feature, step, datetime	Show additional information on screenshots. Comma-separated list of url, feature, step, datetime, or remove to disable. Ordered as listed.
failed_prefix	failed_	Prefix failed screenshots with failed_ string. Useful to distinguish failed and intended screenshots.
filename_pattern	{datetime:u}.{feature_file}.feature_{step_line}.{ext}	File name pattern for successful assertions.
filename_pattern_failed	{datetime:u}.{failed_prefix}{feature_file}.feature_{step_line}.{ext}	File name pattern for failed assertions.

File name tokens

Token	Substituted with	Example value(s)
{ext}	The extension of the file captured	html or png
{failed_prefix}	The value of failed_prefix from configuration	failed_, error_ (do include the _ suffix, if required)
{url}	Full URL	http_example_com_mypath_subpath_query_myquery_1_plus_2_fragment
{url_origin}	Scheme with domain	http_example_com
{url_relative}	Path + query + fragment	mypath_subpath_query_myquery_1_plus_2_fragment
{url_domain}	Domain	example_com
{url_path}	Path	mypath_subpath
{url_query}	Query	myquery_1_plus_2
{url_fragment}	Fragment	somefragment
{feature_file}	The filename of the .feature file currently being executed, without extension	my_example.feature -> my_example
{step_line}	Step line number	1, 10, 100
{step_line:%03d}	Step line number with leading zeros. Modifiers are from sprintf().	001, 010, 100
{step_name}	Step name without Given/When/Then and lower-cased.	i_am_on_the_test_page
{datetime}	Current date and time. defaults to Ymd_His format.	20010310_171618
{datetime:U}	Current date and time as microtime. Modifiers are from date().	1697490961192498

Auto-purge

By default, the purge option is disabled. This means that the screenshot directory will not be cleared after each test run. This is useful when you want to keep the screenshots for debugging purposes.

If you want to clear the directory after each test run, you can enable the purge option in the configuration.

default:
  extensions:
    DrevOps\BehatScreenshotExtension:
      purge: true

Alternatively, you can use BEHAT_SCREENSHOT_PURGE environment variable to enable the auto-purge feature for a specific test run.

BEHAT_SCREENSHOT_PURGE=1 vendor/bin/behat

Additional information on screenshots

You can enable additional information on screenshots by setting info_types in the configuration. The order of the types will be the order of the information displayed on the screenshot.

By default, the information displayed is the URL, feature file name, step line:

Current URL: http://example.com<br/>
Feature: My feature<br/>
Step: I save screenshot (line 8)<br/>
Datetime: 2025-01-19 00:01:10
<hr/>
<!DOCTYPE html>
<html>
...
</html>

More information can be added by setting the info_types configuration option and using addInfo() method in your context class.

/**
 * @BeforeScenario
 */
public function beforeScenarioUpdateBaseUrl(BeforeScenarioScope $scope): void {
  $environment = $scope->getEnvironment();
  if ($environment instanceof InitializedContextEnvironment) {
    foreach ($environment->getContexts() as $context) {
      if ($context instanceof ScreenshotContext) {
        $context->addInfo('Custom info', 'My custom info');
      }
    }
  }
}

Maintenance

composer install
composer lint
composer lint-fix
composer test-unit
composer test-bdd

BDD tests

There are tests for Selenium and Headless drivers. Selenium requires a Docker container and headless requires a Chromium browser (we will make this more streamlined in the future).

# Start Chromium in container for Selenium-based tests.
docker run -d -p 4444:4444 -p 9222:9222 selenium/standalone-chromium

# Install Chromium with brew.
brew cask install chromedriver
# Launch Chromium with remote debugging.
/opt/homebrew/Caskroom/chromium/latest/chromium.wrapper.sh --remote-debugging-address=0.0.0.0 --remote-debugging-port=9222

composer test-bdd  # Run BDD tests.

BEHAT_CLI_DEBUG=1 composer test-bdd  # Run BDD tests with debug output.

---

Repository created using https://getscaffold.dev/ project scaffold template