BackstopJS Getting Started Guide

Overview

BackstopJS is currently optional in this project and is used for visual regression testing to ensure consistency in the UI. To get started with BackstopJS, follow the steps below. The official guide can be found at the BackstopJS GitHub Repository.

Goal

Eventually BackstopJS will be implemented in the pipeline process to help catch errors before they make their way to higher environments.

Prerequisites

Before running BackstopJS, ensure the following:

Both the API and Admin projects must be running.
In the .env file of both the API and Admin projects, make sure the following environment variables are uncommented and set to matching values:
- NOTIFY_E2E_TEST_EMAIL
- NOTIFY_E2E_TEST_PASSWORD

Example:

NOTIFY_E2E_TEST_EMAIL=your-email@example.com
NOTIFY_E2E_TEST_PASSWORD=your-password

How to Run BackstopJS

Step 1: Install Gulp Globally

First, make sure all dependencies are installed and updated:

make bootstrap

Step 2: Run the Gulp Test Task

To run the visual regression tests, use the following command:

gulp backstopTest

If there are new expected changes in the UI, one will need to update the reference images before testing. To do this, run the following command:

gulp backstopReference

Note: After running the gulp backstopReference command, immediately running the test (gulp backstopTest) should pass all tests, assuming the changes are expected.

Adding New Tests

The entry point for BackstopJS configuration can be found in the backstop.config.js file.

To add a new feature or page to be tested, modify the scenarios array. Refer to the official documentation for details on the structure of the object.

In most cases, one will be testing entire pages instead of individual components. To reduce redundancy, helper functions were created with our default settings that will be applied to every URL in the urls.js file. To add a new URL, one would add an object like such:

{ label: 'Support', path: '/support' }

For unique cases that involve UI interaction, scripts linked to the engine_scripts/puppeteer directory can be used to simulate user interactions during tests. An example can be found with countFeatureLinks.js

2.3 KiB Raw Permalink Blame History