CSS regression testing with BackstopJS

BackstopJS package

You can add BackstopJS from the root directory of any project.

$ npm install --save-dev backstopjs

This will create the folder structure ./node_modules/backstopjs.

If you don't already have a global Gulp instance… http://gulpjs.com

$ sudo npm install -g gulp

//test for a correct install with...
$ gulp -v
> CLI version 3.8.10
> Local version 3.8.10

If you don't already have a global PhantomJS install… http://phantomjs.org/download.html

$ sudo npm install -g phantomjs

//test for a correct install with...
$ phantomjs -v
> 1.9.8

If you don't already have a global CasperJS install… http://docs.casperjs.org/en/latest/ installation.html

$ sudo npm install -g casperjs

//test for a correct install with...
$ casperjs --version
> 1.1.0-beta3

If you don't already have a BackstopJS config file. The following command will create a config template file which you can modify in your root directory. Note: this will overwrite any existing backstopjs config file.

From ./node_modules/backstopjs …

$ gulp genConfig

This will generate a boilerplate JSON configuration file for you at the root of your project e.g. greenwire-styleguide/source/backstop.json. This is where you can specify the URL's, selectors to test and at which breakpoints you want to test them at.

    {
      "viewports": [
        {
          "name": "phone",
          "width": 320,
          "height": 480
        }, {
          "name": "tablet_small",
          "width": 480,
          "height": 768
        }, {
          "name": "tablet",
          "width": 768,
          "height": 1024
        }, {
           "name": "desktop",
           "width": 1024,
           "height": 768
        }
      ],
      "scenarios": [
        {
          "label": "Forms",
          "url": "http://ggw-prototype.goalgorilla.com/components/forms.html",
          "selectors": [
            "#test-basic-form",
            "#test-horizontal-form"
          ],
          "readyEvent": "domready",
          "delay": 500
        }
      ]
    }

In this configuration you can see three viewports objects, one for phone, one for small tablets, one for iPad tablet landscape and one for desktop, each with a name and a viewport property. You can add as many viewports objects as you need. BackstopJS requires at least one.

Then we have scenarios. This specifies the URLs and element selectors that BackstopJS will test. The selectors generally accept standard CSS selector notation. It's useful to think of every scenario as a test for a specific static page. Here too, you can add as many scenarios as you need. BackstopJS requires at least one.

You may notice that in this config, our URL is pointing to http://ggw-prototype.goalgorilla.com/ (the form page of the UI component library) and that is what we would see if we were to run our test now. This is here to illustrate that BackstopJS can point to local or remote URLs so it's easy to imagine repurposing the same tests for local development, QA, staging and production environments.

ReadyEvent and delay

Because we have developed Greenwire primarely for speed, we initialy do not render any more resources than we need. Once this has completed, javascript progressively loads more content or enhances the user experience. The problem testing this is knowing when to take the screenshot. BackstopJS solves this problem with two config properties: readyEvent and delay.

The readyEvent property enables you to trigger the screen capture by logging a predefined string to the console. For example, the following line will delay screen capture until the page calls console.log("domready"), which we have defined as the last task to execute by javascript.

The delay property enables us to pause screen capturing for a specified duration of time. This delay is applied after readyEvent. In the above example the delay is 0.5 seconds.

Hiding and removing selectors

You will have the option to remove or hide element before the taking the snapshot. For example the cookie message will be in the way on most protype page, so we might want to hide this always. For any regression we want to test on blocks with dynamic content we need to eliminate the dynamic part as in will always fail the test.

When you want to hide a selector we apply the style visibility:hidden. There may also be elements which need to be completely removed from the DOM during testing. For that we have removeSelectors which sets elements to display: none.

  {
    "viewports": [],
    "scenarios": [
      {
        "url": "https://greenwire.greenpeace.org",
        "hideSelectors": [
          "#elementToHide"
        ],
        "removeSelectors": [
          "#elementToRemove"
        ],
        "selectors": [
          "header"
        ]
      }
    ]
  }