backstop_generator

Introduction

Backstop Generator makes it easy to build, manage, and run visual regression tests for your site using BackstopJS. By providing a user-friendly UI for defining test Profiles, Scenarios, and Viewports, it bridges the gap between your Drupal content and BackstopJS’s powerful screenshot-comparison engine. Whether you’re rolling out a new theme, or simply want confidence that recent changes haven’t introduced visual defects, Backstop Generator streamlines the entire process.

Key Features

• Profiles
  Each Backstop test is represented by a Profile. Each Profile tests a collection of Scenarios through multiple Viewports. Create a single, large Profile to test everything on your system at once, or create multiple smaller Profiles to test specific areas—languages, menus, content types, or paths.
• Scenario Generation
  Each Scenario represents a specific page or path on your site to be tested and can inherit or override Profile–level settings. Quickly spin up Tests for:
  • Enabled languages
  • Your homepage
  • Menu hierarchies (with configurable depth)
  • Random nodes by content type
  • Manually defined paths or node lookups
• Viewport Generation
  Generates Viewports for device sizes automatically from any enabled theme’s breakpoint definitions, or manually define custom viewports (e.g., mobile, tablet, desktop).
• Scenario Defaults & Overrides
  Define global defaults (e.g., hide selectors, delays, click selectors) and then tweak individual Scenarios as needed to handle modals, dynamic content, or edge cases.
• Automated JSON file creation/updates
  Backstop Generator builds and updates a valid backstop.json file per Profile—no manual editing required—ready for your BackstopJS workflow.
• Built‑in Command Snippets
  Copy‑and‑paste commands to generate reference screenshots and Visual Regression Tests (VRT) from your terminal.

How It Works

See the full module documentation
Video tutorial

1. Configure Global Settings
   Under Configuration › Development › Backstop Generator, set your “Test Domain” (typically your Dev or CI URL) and “Reference Domain” (often your live production site). Define default Profile parameters and scenarioDefaults to apply to all new Profiles.
2. Define Viewports
   Visit the Viewports tab. During installation, Backstop Generator will auto–create Viewports using the breakpoints from your default theme. To target other themes, use the Viewport Generator or manually add new ones by clicking the "Add a Viewport" button.
3. Create a Profile
   Under the Profiles tab, click “Add Backstop Profile.”
   1. Choose a title and description.
   2. Select which viewports apply.
   3. Optionally override Profile parameters or scenario defaults (e.g.,
      delay, misMatchThreshold).
4. Generate Scenarios
   Use the Scenario Generator section to auto-generate Scenarios:
   1. Select languages, include the homepage, choose menus (with depth), pick content types and number of random nodes, or specify individual node IDs/paths.
   2. Save the Profile to populate the list of Scenarios, then select/deselect individual items as needed.
5. Run Tests
   Switch to the Commands tab to see ready‑made terminal commands:
   

   cd tests/backstop
   backstop reference --config=backstop.json
   backstop test     --config=backstop.json

   Run the “reference” command first to capture baseline images, then “test” to compare against your current site.

Advanced Capabilities

• Hide Selectors: Mask dynamic elements (e.g., carousels) using CSS
  selectors so they don’t trigger false positives.
• Click Selectors: Automate UI interactions (open modals, expand
  accordions) before capturing screenshots.
• Cookie Management: Set initial cookies (e.g., authentication) via
  cookiePath.
• Parallelization: Control asyncCaptureLimit and
  asyncCompareLimit to tune performance on CI servers.
• Theme‑Aware Viewports: Automatically pick up any theme’s
  .breakpoints.yml file to ensure your tests mirror real‑world responsive
  behavior.

Requirements & Compatibility

• Drupal 10.x / 11.x
• BackstopJS
• Themes with defined breakpoints (for automatic viewport generation)

Other than having BackstopJS installed on your system to run the tests, no additional external libraries are required! Everything is managed via Drupal’s configuration and entity system.

Getting Started

1. Install module with Composer:

   composer require drupal/backstop_generator
   drush en backstop_generator -y

   Visit: https://drupal.org/documentation/install/modules-themes/modules-8 for further information.

2. Configure then run your first Visual Regression Test in the terminal using the commands provided on the Commands tab.

Backstop JS Installation

Visit: https://github.com/garris/BackstopJS for more information and installation instructions.

Inside Project Folder:

mkdir tests
cd tests
mkdir backstop
cd backstop
backstop init

Directory structure:

/my-project (project folder)
-- /docroot (Drupal install folder docroot|web)
-- /tests 
---- /backstop (Backstop JS folder)

Local Development and Config Split

This module is intended to only be run on development environments, and never on production. Use config_split module to save this module's configuration for local installs. Check out the Config Split module page for details.

Maintainers

Current maintainers:
- Wilbur Ince (wylbur) - https://www.drupal.org/u/wylbur
- David Kirkwood (jumpsuitgreen) - https://www.drupal.org/u/jumpsuitgreen

Initial development of this project was provided by Hook 42, a Strategic web consulting and development based in the SF Bay Area, CA.

Ongoing support for Backstop Generator module is provided by Electric Citizen - https://www.drupal.org/electric-citizen.