README.md

• What is DDEV Backstopjs Add-on?
• Getting started
• Using backstopjs
  • Configuration
  • Run tests
  • View test results
• Changes to the original docker image
• Advanced
  • How to add additional hostnames?
  • Change backstop tests directory

What is DDEV Backstopjs Add-on?

This is a ddev-addon for backstop.js based on mmunz addon but optimized for Aljibe. Backstopjs is a visual regression testing tool. Backstop is executed in a docker container based on the official backstopjs docker image.

This addon just provides the basics to run backstopjs and some basic tests, but those need to be adapted to your needs.

Getting started

Install this addon with

ddev get Metadrop/ddev-backstopjs

After that you need to restart the ddev project:

ddev restart

Note: If you haven't downloaded the backstopjs base image before, then it will be downloaded when ddev is restarted. The backstopjs/backstopjs is about 2.6GB, so this may take some time.

Using backstopjs

Configuration

By default, the backstop tests are expected in $DDEV_APPDIR/tests/backstopjs/<environemnt_folder>.

This add-on provide some tests inside "local" environment folder ($DDEV_APPDIR/tests/backstopjs/local). This can be taken as a base to add more tests or provide your own backstop.js or backstop.json configs there.

Hint: have a look at the example from mmunz backstopjs-config

Alternatively you can create a simple backstop.json config with:

ddev backstop init

Run tests

After the config was created it is time to run the tests.

Create reference screenshots:

ddev backstop <environment> reference

Create test images and compare to reference screenshots:

ddev backstop <environment> test

Where is the environment folder name, or 'local' if not especified.

If your config file is not 'backstop.json' you need to use the --config argument, e.g. --config=backstop.js

View test results

The backstop commands 'backstop remote' and 'backstop openReport' do not work in this setup.

But there is a host command that will open the latest test report in your default browser:

ddev backstopjs-report <environment>

Alternatively open the generated HTML-Report with your browser, e.g.:

open tests/backstopjs/<environment>/backstop_data/_mytestproject_/html_report/index.html 

Commands aliases

Command ddev backstopjs can be called as:

• ddev backstop
• ddev bkjs

Command ddev backstopjs-report can be called as:

• ddev backstop-report
• ddev bjsr

Changes to the original docker image

The backstopjs docker image is extended with some functions using a custom docker build, see Dockerfile and uses a custom entrypoint.

In the Dockerfile the following is added/changed:

• add the custom entrypoint.sh to the image
• delete the default 'node' user with uid 1000 and add current ddev user
• install the minimist npm package globally. This is not needed by default but very handy to parse command line args for more complex custom backstopjs configs.

The entrypoint is responsible for:

• add /etc/hosts entries for all hosts configured in the ddev web container automatically
• add sleep command to keep the container running

Advanced

How to add additional hostnames?

If you want to test hosts not configured in the web container, you need to use external_links in docker-compose.backstop.yaml.

See: ddev FAQ: Can different projects communicate with each other?

Do not forget to remove the #ddev-generated line!

Change backstop tests directory

Per default the backstop directory containing backstop config etc. is expected in your project directory (besides the .ddev folder) in the directory tests/backstop.

If you want to change that edit the file docker-compose.backstop.yaml and change the line in volumes to the path you want to use, move the files to the new directory and restart ddev.

Make sure to remove the #ddev-generated line from the file to prevent ddev from making changes to it.