README

Behat extension to create screenshots

Features

• Captures a screenshot using the I save screenshot step.
• Captures fullscreen screenshots with the I save fullscreen screenshot step.
• Automatically captures a screenshot when a test fails.
• Supports both HTML and PNG screenshots.
• Supports Selenium and Headless drivers.
• Configurable screenshot directory.
• Automatically purges screenshots after each test run.
• Adds additional information to screenshots.
• Records an animated GIF of a scenario from its per-step 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
      always_fullscreen: 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 can capture fullscreen screenshots:

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

Fullscreen screenshots work by temporarily resizing the browser window to the full height of the page to capture everything in one screenshot.

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

Then I save 1440 x 900 screenshot
# Or with fullscreen
Then I save fullscreen 1440 x 900 screenshot

or a file name:

Then I save screenshot with name "my_screenshot.png"
# Or with fullscreen
Then I save fullscreen screenshot with name "my_screenshot.png"

To always capture fullscreen screenshots, even without explicitly using the fullscreen keyword, set the always_fullscreen configuration option to true:

default:
  extensions:
    DrevOps\BehatScreenshotExtension:
      always_fullscreen: true

Capturing Screenshots After Every Step

To automatically capture a screenshot after every step, you can either:

1. Enable globally in configuration:

default:
  extensions:
    DrevOps\BehatScreenshotExtension:
      on_every_step: true

1. Enable per-scenario using the @screenshots tag:

@screenshots
Scenario: My scenario with automatic screenshots
  Given I am on "http://example.com"
  When I click "Login"
  Then I should see "Welcome"
  # Screenshots will be captured after each of these steps

The @screenshots tag takes precedence over the global configuration, allowing you to enable this feature for specific scenarios even when it's disabled globally.

Note: When both on_every_step and on_failed are enabled, only one screenshot is captured for failed steps (the failed screenshot) to avoid duplicates.

Recording an animated GIF

To record an animated GIF of a scenario from its per-step screenshots, you can either:

1. Enable globally in configuration:

default:
  extensions:
    DrevOps\BehatScreenshotExtension:
      animation:
        enabled: true
        frame_delay: 500

1. Enable per-scenario using the @screenshots:animated tag:

@javascript @screenshots:animated
Scenario: My scenario recorded as an animated GIF
  Given I am on "http://example.com"
  When I click "Login"
  Then I should see "Welcome"
  # An animated GIF is written when the scenario finishes.

When animation is enabled, a screenshot is taken after every passed step, and the frames are combined into a single GIF - named after the feature file and scenario line - when the scenario finishes. frame_delay sets the delay between frames in milliseconds.

The @screenshots:animated tag is read at both the scenario and feature level. Animation requires the gd PHP extension and a driver that can capture screenshots (such as a real browser via @javascript); without GD, the animated GIF is skipped while the per-step screenshots are still written.

Options

File name tokens

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