grunt-phantomcss

Automate CSS regression testing with PhantomCSS and SlimerJS

This is a fork of @michagodbolt's version of grunt-phantomcss but swaps out PhantomJS in favor of SlimerJS. SlimerJS supports more modern browser features such as Web Fonts than does the version of Phantom currently supported by PhantomCSS.

---

Getting Started

This plugin requires Grunt ~0.4.5

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin through the following steps.

Install from the command line:

  $ npm install https://github.com/Blackbaud-PaulCrowder/grunt-phantomcss-slimerjs --save-dev

Or add the following line to your package.json:

  "https://github.com/Blackbaud-PaulCrowder/grunt-phantomcss-slimerjs": "^0.4.0"

Then, once the plugin has been installed via npm install, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-phantomcss');

The "phantomcss" task

Overview

In your project's Gruntfile, add a section named phantomcss to the data object passed into grunt.initConfig().

grunt.initConfig({
  phantomcss: {
    options: {
        screenshots: 'test/visual/screenshots/',
        results: 'results/visual/',
        viewportSize: [1280, 800],
        mismatchTolerance: 0.05,
        rootUrl: 'http://localhost:3000/' // Optional
      },
      src: [
        'test/visual/**/*.js'
      ]
    }
});

Options

src

Type: String|Array

The test files to run.

options.mismatchTolerance

Type: Number Default: 0.05

The change percentange tolerated between screenshots (for instance to match anti-aliasing bugs).

options.screenshots

Type: String Default: './screenshots'

The screenshots directory, relative to the src file, where test fixtures (comparison screenshots) are stored. Baseline screenshots will be stored here on the first run if they're not present.

options.results

Type: String Default: './results'

The directory, relative to the src file, to store source, diff, and failure screenshots after tests.

options.viewportSize

Type: Array Default: [1280, 800]

The viewport size to test the site in [width, height] format. Useful when testing responsive layouts.

options.logLevel

Type: String Default: error

The CasperJS log level. See CasperJS: Logging for details.

options.rootUrl

Type: String Default: ``

Optional parameter passed to testfiles for prepending to relative URL's. Useful when testing against multiple environments.

Usage Examples

Basic visual tests

Run tests in test/visual/ against comparison screenshots stored in test/visual/screenshots/, and put the resulting screenshots in results/visual/

grunt.initConfig({
  phantomcss: {
    options: {
      screenshots: 'test/visual/screenshots/',
      results: 'results/visual/'
    },
    src: [
      'test/visual/**/*.js'
    ]
  }
});

Responsive layout testing

Run tests in test/visual/ against comparison screenshots for destop and mobile. Pass rootUrl option to specify testing against http://localhost:3000/.

grunt.initConfig({
  phantomcss: {
    desktop: {
      options: {
        screenshots: 'test/visual/desktop/',
        results: 'results/visual/desktop',
        viewportSize: [1024, 768],
        rootUrl: 'http://localhost:3000/'
      },
      src: [
        'test/visual/**.js'
      ]
    },
    mobile: {
      options: {
        screenshots: 'test/visual/mobile/',
        results: 'results/visual/mobile',
        viewportSize: [320, 480],
        rootUrl: 'http://localhost:3000/mobile/'
      },
      src: [
        'test/visual/**.js'
      ]
    }
  },
});

Sample test file

Test files should do the following:

• Instruct CasperJS to open the URL you want to test. Grunt automatically envokes casper.start() when it begins, so all test files need to start with casper.thenOpen.
• Manipulate the page in some way if necessary. PhantomJS is known to have trouble rendering web fonts and, as such, replacing text with a standard web font may be warranted.
• Take screenshots

var casper = phantom.casper,
    phantomcss = phantom.phantomcss;

casper.thenOpen('http://localhost:3000/todo')
    .then(function() {
      this.evaluate(function() {
        $('*').css('font-family', 'arial, sans-serif');
      });
    })
    .then(function() {
      phantomcss.screenshot('#todo-app', 'Main app');
    })
    .then(function() {
      casper.fill('form.todo-form', {
        todo: 'Item1'
      }, true);

      phantomcss.screenshot('#todo-app', 'Item added');
    })
    .then(function() {
      casper.click('.todo-done');

      phantomcss.screenshot('#todo-app', 'Item checked off');
    });

You can also make URL's relative, prepending the rootUrl to them:

var casper = phantom.casper,
    phantomcss = phantom.phantomcss;

casper.thenOpen(phantom.rootUrl + 'todo')
    .then(function() {
      jQuery('*').css('font-family', 'arial, sans-serif');
    })
    .then(function() {
      phantomcss.screenshot('#todo-app', 'Main app');
    });

Additional Resources

See the CasperJS documentation and the PhantomCSS documentation for more information on using CasperJS and PhantomCSS.

For further examples, refer to the following posts:

• CSS Testing with PhantomCSS, PhantomJS, CasperJS and Grunt
• Sass Bites #73 - Visual Regression Testing with PhantomCSS (Video)
• Visual Regression Testing: How to Test Dynamic Content with PhantomCSS
• Visual Regression Testing Part 2: Extending Grunt-PhantomCSS for Multiple Environments