webfactory/behat-mink-failure-screenshots

Saves the rendered page HTML via Mink and appends URL, HTTP status code and screenshot path to the exception message whenever a Behat scenario fails.

1.0.0 2026-09-01 10:19 UTC

Requires

• php: ^8.4
• behat/behat: ^3.10 || ^4.0
• behat/mink: ^1.11
• friends-of-behat/mink-extension: ^2.7 || ^3.0@alpha

MIT

• webfactory GmbH

Published on Packagist.org on 2026-09-01 10:25 UTC

README

A minimal Behat extension for suites that drive the browser with MinkExtension: Whenever a scenario step fails, it saves the current page's HTML and appends the page URL, HTTP status code and the path to the saved HTML to the exception message, so the extra context shows up right in Behat's normal failure output. It works with any Mink driver, but requires an active Mink session — it has nothing to capture in suites that don't use Mink at all.

This is a from-scratch, LLM-based rewrite inspired by the unmaintained genesis/behat-fail-aid extension, covering only this one particular feature. Everything else from that extension (JS error tracking, debug bar selectors, wait-on-failure, feedback-on-failure, the scenario-debug CLI command, PNG screenshots, site filters) has been dropped.

Compatible with Behat 3.10+ and Behat 4.x, requires PHP 8.4+.

Installation

composer require --dev webfactory/behat-mink-failure-screenshots

Configuration

In your behat.php:

use Behat\Config\Config;
use Behat\Config\Extension;
use Webfactory\BehatMinkFailureScreenshots\ServiceContainer\Extension as BehatFailureScreenshotsExtension;

return (new Config())
    ->withExtension(new Extension(BehatFailureScreenshotsExtension::class, [
        'directory' => '%paths.base%/tmp',
        'autoClean' => false,
    ]));

Or, with the legacy behat.yml:

extensions:
    Webfactory\BehatMinkFailureScreenshots\ServiceContainer\Extension:
        directory: '%paths.base%/tmp'
        autoClean: false

Option	Default	Description
directory	system temp directory	Where failing scenarios' HTML is saved. Created automatically if missing.
autoClean	false	Delete previously saved *.html files from directory before the suite runs.

Usage

Add Webfactory\BehatMinkFailureScreenshots\Context\FailureScreenshotContext to the contexts list of any suite that also uses MinkExtension:

default:
    suites:
        default:
            contexts:
                - FeatureContext
                - Webfactory\BehatMinkFailureScreenshots\Context\FailureScreenshotContext

No steps or hooks need to be called manually — on every failed step, the context's #[AfterStep] hook saves the page HTML and appends the failure details to the exception message automatically.

Credits, Copyright and License

• https://www.webfactory.de

Copyright 2026 webfactory GmbH, Bonn. Code released under the MIT license.