Visual regression testing: BackstopJS for the win

Maintaining visual consistency across a large, evolving site can be a challenge. Small CSS shifts, design-system updates, layout regressions and unintentional content changes can creep in unnoticed, often accumulating over multiple deployments until they become visible to the public.

At DrupalSouth Community Day 2025, Marji shared a practical and grounded walkthrough of how visual regression testing, powered by BackstopJS, can prevent these issues long before they appear in production.

Marji’s session covered the fundamentals, real-world examples, and an efficient workflow for using BackstopJS across local development, GovCMS SaaS, and CI pipelines.

Why visual regression testing matters

Visual regression testing answers three key questions that teams often struggle with:

• Has anything changed that shouldn’t have?
• Can we quickly find the “needle in the haystack” when something looks off?
• How can we prove a change or deployment did not introduce regressions?

Visual regression tests have proven to be very useful when reviewing updates to a design system where upgrades introduced subtle, but meaningful, changes, such as a navigation shift by a single pixel. Individually small, these discrepancies accumulate over time. Without visual regression testing, they often go unnoticed.

BackstopJS solves this by automatically comparing screenshots between a reference state (e.g., production) and a test site (e.g., a feature environment, local environment, or staging). The result is a visual report showing exactly what moved, changed, or broke.

Introducing BackstopJS

BackstopJS is an open-source, MIT-licensed JavaScript tool designed for screenshot comparison. It ticks a lot of boxes for ease of use:

• Developer-friendly
• CI-compatible
• Highly configurable
• Simple to introduce to existing stacks - even to GovCMS SaaS

The BackstopJS report UI provides before/after screenshots, diff overlays, and a scrubber interface that makes visual changes immediately obvious.

Running BackstopJS the easy way: Docker + Ahoy

It is straightforward to install backstopJS globally via npm, but it can also be run without an installation as a docker command. This makes it easy to add BackstopJS to an existing Docker-based development workflow, regardless whether your project uses ddev, lando or ahoy.

A simple alias or a command definition can wrap the Docker container so developers run:

backstop test (an equivalent of a global installation) or
ahoy my backstop test (resp ddev backstop test or lando backstop test) from a project.

This approach works seamlessly also inside Lagoon/GovCMS development stacks, allowing teams to maintain testing tools directly within their project.

Integrating visual tests into GovCMS workflows

Although GovCMS SaaS does not allow custom CI pipelines,  BackstopJS can still be embedded into each project workflow.

Local and Ahoy workflows

Developers can:

• Compare feature environments with production (from local)
• Validate visual integrity before committing code
• Share reports with the team or client

Ahoy backstop command definition

To embed backstop to a GovCMS SaaS project, define it in the custom/ahoy.yml file:

  backstop:
    usage: Run a backstopJS container
    cmd: |
      docker run --rm --user $(id -u) --shm-size 2048m
        --add-host=MYPROJECT.docker.amazee.io:host-gateway
        -v "$(pwd)/tests/backstop":/src backstopjs/backstopjs:6.3.25 "$@"
        --config=./backstop.config.js

This will introduce the ahoy my backstop command.

CI-based monitoring

For teams with CI flexibility (e.g. PaaS, bespoke hosting), BackstopJS can be set up to monitor production automatically, for example:

• Hourly snapshots
• Slack notifications on change
• Instant triage via visual diffs

This approach has caught unexpected changes, both intentional and accidental, before they became user-visible.

Advanced tools: BackstopJS + Drupal

The Drupal Backstop Generator module (v2) can help with the authoring of tests

 This module:

• Detects viewports automatically
• Generates Backstop configuration profiles

Builds scenario lists from content types 

• Outputs BackstopJS-ready config files

This can significantly reduce the time needed to onboard large or complex sites

Logged-in testing

One of the trickier aspects of visual regression testing is capturing authenticated states.
This can be done by extracting a Drupal session cookie and injecting it into BackstopJS as part of the test run.

The result: accurate snapshots of admin pages or authenticated components, essential for sites with deep editorial workflows.

Who benefits from visual regression testing?

Marji’s presentation offered clear value for multiple audiences

• For site owners: A fast way to check broad changes or content updates before they go live.
• For developers: Confidence that refactors, bug fixes, and design changes have no hidden impact.
• For project managers: Evidence-based assurance that deployments have not regressed key areas.

Final thoughts

Visual regression testing is not just a “nice to have”, it’s a safety net that catches issues before they become production bugs.

With BackstopJS, development teams gain:

• Greater reliability
• Faster detection of regressions
• A smoother deployment pipeline
• Clear visual communication with clients

Whether used locally, as part of CI, or integrated into GovCMS workflows, BackstopJS delivers clarity and confidence in every release.

If you’re looking to strengthen the quality of your Drupal or GovCMS site, visual regression testing is well worth the investment, and BackstopJS is an excellent tool to start with.

Watch the video