BackstopJS

To check if BackstopJS can install and run correctly in your current environment (requires Node.js 8+), run the following command sequence. This creates a temporary directory, installs the package locally, and executes the init, reference, and test commands.

Standard Sanity Test:

mkdir backstopSanityTest; cd backstopSanityTest; mkdir node_modules; npm install backstopjs; ./node_modules/.bin/backstop init; ./node_modules/.bin/backstop reference; ./node_modules/.bin/backstop test

Sanity Test using Docker:

mkdir backstopSanityTest; cd backstopSanityTest; mkdir node_modules; npm install backstopjs; ./node_modules/.bin/backstop init; ./node_modules/.bin/backstop reference --docker; ./node_modules/.bin/backstop test --docker

The HTML report UI is a React project. To build the resource bundle required for the BackstopJS report UI, run the build-compare script. This process generates /compare/output/index_bundle.js, which contains all the necessary styles and JavaScript for the HTML report.

In standard BackstopJS operations (e.g., running backstop test), this bundle is automatically copied into the appropriate HTML report directory once bitmap generation is complete.

npm run build-compare

You can write custom JavaScript to simulate complex user actions. Place these scripts in your project's engine_scripts directory (defined in paths.engine_scripts).

Script Signature:

• onBefore(page, scenario, viewport, isReference, Engine, config)
• onReady(page, scenario, viewport)

Example onReady script structure:

module.exports = async (page, scenario, vp) => {
  console.log('SCENARIO > ' + scenario.label);
  await require('./clickAndHoverHelper')(page, scenario);

  if (vp.label === 'phone') {
    console.log('doing stuff for just phone viewport here');
  }
};

To ensure consistent rendering across different operating systems, run BackstopJS inside a Docker container using the --docker flag.

CLI usage:

backstop test --docker

Node.js usage:

const backstop = require('backstopjs');
backstop('test', {docker: true});

Note for Mac/Windows users: When using Docker, localhost in your scenarios will not work. Use host.docker.internal instead:

"url": "https://host.docker.internal/?someCoolAppParameter=true"

To build and push a multi-architecture image (supporting both linux/amd64 and linux/arm64), use docker buildx.

First, ensure you have a builder instance created:

docker buildx create --name mybuilder --use --bootstrap

Then, build and push using the BACKSTOPJS_VERSION environment variable:

export BACKSTOPJS_VERSION=6.1.4
docker buildx build --push --build-arg BACKSTOPJS_VERSION --platform linux/amd64,linux/arm64 --tag backstopjs/backstopjs:$BACKSTOPJS_VERSION docker

The standard visual regression testing workflow consists of three main commands:

1. backstop init: Sets up the project instance, defining URLs, cookies, screen sizes, and interactions.
2. backstop test: Generates new test screenshots and compares them against existing reference screenshots. Visual differences are reported in a UI or CLI.
3. backstop approve: Promotes the latest test results to the reference collection. Use this when changes are intentional to update your baseline for future tests.

To ensure screenshots are taken only after an SPA or Ajax content has loaded, use one of these three methods:

1. readySelector: Wait until a specific CSS selector exists in the DOM.
2. readyEvent: Wait until a specific string is logged to the browser console via console.log().
3. delay: Pause for a specified number of milliseconds after the ready condition is met.

By default, BackstopJS captures only the first occurrence of a selector. To capture all matching elements, set selectorExpansion to true. You can also use the expect property to ensure a specific number of elements are found; the test will fail if the count does not match.

scenarios: [
  {
    "selectors": [
      ".aListOfStuff li"
    ],
    "selectorExpansion": true,
    "expect": 5
  }
]

To prevent dynamic content (like ads or unpredictable banners) from causing test failures:

• Use hideSelectors to set an element to visibility: hidden. This hides the content but preserves the layout flow.
• Use removeSelectors to completely remove an element from the DOM before the screenshot is taken.

"hideSelectors": [
  "#someFixedSizeDomSelector"
],
"removeSelectors": [
  "#someUnpredictableSizedDomSelector"
]

Use the backstopjs/backstopjs Docker image to run BackstopJS without external dependencies. The image includes BackstopJS v3 and Headless Chrome.

Important: You must mount your local working directory to /src inside the container for the commands to work.

docker run --rm -v $(pwd):/src backstopjs/backstopjs --version

To set up a new BackstopJS instance with default configuration and scaffolding in your current working directory, run the backstop init command.

Warning: This will overwrite any existing files in the directory.

For local installation, you can require BackstopJS directly in your code to use it as a module.

const backstop = require('backstopjs');