README

Behat-ScreenshotExtension helps you debug Behat scenarios by taking screenshot of the failing steps.

By default the extension takes the screenshot and save it to the preconfigured directory (by default it will save the image to the default temporary system directory).

Also the extension allows you to specify an image driver which can upload the image to a host, in this case you will see the image url in the terminal right after the failing step. See available image drivers below.

You can also create your own image driver easily, for more information see this section.

Installation

Install by adding to your composer.json:

composer require --dev bex/behat-screenshot

Configuration

Enable the extension in behat.yml like this:

default:
  extensions:
    Bex\Behat\ScreenshotExtension: ~

You can configure the screenshot directory like this:

default:
  extensions:
    Bex\Behat\ScreenshotExtension:
      image_drivers:
        local:
          screenshot_directory: /your/desired/path/for/screenshots
          clear_screenshot_directory: true  # Enable removing all images before each test run. It is false by default.

If you are using another image driver you can enable it like this:

default:
  extensions:
    Bex\Behat\ScreenshotExtension:
      active_image_drivers: customdriver
      image_drivers: # this node and the driver subnodes are optional, if you remove it then the driver's default values will be used
        customdriver:
          #... custom driver config goes here ...

You can even enable more than one image driver at once:

default:
  extensions:
    Bex\Behat\ScreenshotExtension:
      active_image_drivers: [local, customdriver]
      image_drivers:
        local:
          #... local driver config goes here ...
        customdriver:
          #... custom driver config goes here ...

You can make a combined screenshot including previous steps:

default:
  extensions:
    Bex\Behat\ScreenshotExtension:
      screenshot_taking_mode: failed_scenarios
        # Available modes:
        #  - failed_steps: Image contains only the screenshot of the failed step. [Default]
        #  - failed_scenarios: Image contains screenshots of all steps in a failed scenario.
        #  - all_scenarios: Each scenario has a combined image created, regardless of failing or passing.

You can disable the extension by removing from the behat.yml or you can disable it for a profile by using the enabled parameter, e.g.:

ci:
  extensions:
    Bex\Behat\ScreenshotExtension:
      enabled: false

Usage

When you run behat and a step fails then the extension will automatically take the screenshot and you will see the filepath or the image URL of the screenshot (based on the configured image driver). So you will see something like this:

  Scenario:                           # features/feature.feature:2
    Given I have a step               # FeatureContext::passingStep()
    When I have a failing step        # FeatureContext::failingStep()
      Error (Exception)
Screenshot has been taken. Open image at /tmp/behat-screenshot/i_have_a_failing_step.png
    Then I should have a skipped step # FeatureContext::skippedStep()

Available Image Drivers

How to create your own image driver

Implement the Bex\Behat\ScreenshotExtension\Driver\ImageDriverInterface
Put your class under the Bex\Behat\ScreenshotExtension\Driver namespace

That's it!

See example here: https://github.com/tkotosz/behat-screenshot-image-driver-dummy

bex / behat-screenshot

Maintainers

Details