The failure message that leaves out the page: a failed browser test
If your platform has automated browser tests, you have read this message. A check looked for something on the page and did not find it. That is the whole report.
What you actually want to know is what the page was showing at that moment:
- whether it rendered at all
- whether it sent the visitor somewhere unexpected
- whether a form came back carrying an error nobody has seen before
Without that, fixing it is guesswork. The loop goes like this:
- change something
- push
- wait for the pipeline
- read a message that still does not describe what happened
Each of those loops costs a real slice of the day, and after 2 or 3 of them the temptation to write the test off as unreliable and move on gets harder to resist. That is the moment a test suite starts losing the team's trust, and a suite nobody trusts stops protecting the platform.
Capture the page, not just the verdict: HTML and an image on failure
behat-screenshot(Opens in a new tab/window) is a Behat extension we wrote for exactly that moment. Behat is the testing tool that drives a real browser through the journeys a platform cannot afford to break:
- signing in
- searching
- submitting a form
- completing a purchase
When one of those journeys fails, the extension captures the page as evidence.
It saves 2 things, because either one alone leaves a question open. The rendered HTML is what you need to see what the page really contained, down to the element that was missing. The image is what you need to see what a person would have seen, which is where layout and rendering problems show up and where markup alone tells you nothing.
Together they usually answer the question in seconds, rather than in another pipeline run.
There are 2 ways to trigger a capture. It happens automatically when a scenario fails, and a test author can also capture deliberately, part-way through a scenario, from a single step. That second mode earns its keep when a journey passes but something along the route looks wrong.
Turned on in configuration, not in your test code: adoption without a rewrite
How much a tool costs to adopt decides whether it spreads. This one is switched on in a project's Behat configuration file rather than composed into the test code, so a team can enable it without touching a line of its own suite, and turn it off just as easily.
Small decision, large consequence: it is why the extension ends up switched on across whole platforms rather than on the single project whose developer went looking for it.
The evidence has to leave the build: publishing screenshots as artifacts
A capture nobody can open is not evidence. The extension writes where a build pipeline collects and publishes artifacts, so whoever picks up a failed run opens the page straight from the build interface instead of trying to reproduce the failure locally and hoping it happens again. That closes the loop from "the test failed in CI" to "here is the page it failed on".
For a client, that reads as a shorter path from a red build to a working site: the team spends the afternoon fixing the fault rather than reproducing it.
We took the same idea a step further in Vortex(Opens in a new tab/window), our open-source Drupal(Opens in a new tab/window) project template, which publishes captured screenshots somewhere a reviewer will actually look. Evidence that arrives where the conversation is already happening gets used. Evidence sitting in a container does not.
In service since 2017: shipped with Vortex and used beyond our own work
The extension was already part of our testing stack by 2017, documented alongside the rest of our Behat tooling on a long-running clinical trial platform, and it has been maintained ever since. It ships with Vortex, and it is loaded by the test configuration of every repository in the Victorian Government's central content platform.
The part we value most is the part we did not write. Developers with no connection to our practice and no connection to our clients have contributed patches to it, which is a signal no self-authored package list can manufacture. People send fixes to tools they depend on.
In our testing stack since 2017, shipped with Vortex, and carrying patches from developers outside the practice.
For a client, that is the quiet part of the value: the tooling under your test suite is maintained by the same people who maintain your platform.
It sits in a small family we maintain and use daily:
- behat-steps(Opens in a new tab/window) for the step definitions
- behat-format-progress-fail(Opens in a new tab/window) for reporting failures as they happen
- this one for showing the page behind them
Used together, they mean a failed run explains itself.
For teams whose test failures do not explain themselves
Everything on this page is 2 of our services pointed at our own tooling: the development of the extension, and the ongoing support and maintenance that has kept it current since 2017. The same standard sits behind our AI-assisted delivery: however a change gets written, a failing test still has to show you the page before anyone calls it safe.
If you run a platform whose browser tests the team has started ignoring, or a pipeline whose failures nobody can diagnose without re-running them locally, this is the shape the engagement takes: the critical journeys get covered by tests, every failure captures the page behind it, and the evidence lands where the person picking up the build will see it.
If your team has started skipping a red test because nobody can tell what it means, show us the failing run.