grunt-csstest

Unit testing framework for css

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 with this command:

npm install grunt-csstest --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-csstest');

The "csstest" task

Overview

CSSTest a module for unit testing of css. It works by rendering a series of fixtures in a browser, then comparing the rendering to a set of expectations.

In a typical scenario, the input is a series of html files, which when opened in a browser shows a components in various configurations. ( see test/demo/buttonDemo.html for example )

The output is three image files

1. *_expected.png which represents the expected result of rendering the html.
2. *_actual.png which represents the rending of the current state of the html.
3. *_diff.png which is a diff of expected and actual ( broken pixels are marked in red )

If the expected and actual are the same, the test passes. If there is a difference the test fails and the grunt tast fails.

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

grunt.initConfig({
  csstest: {
    "src": [ "demo/**/*Demo.html" ],
    "image": "image",
    "sizes": [ "iphone4P" ]
  },
});

Typically expected.png files are committed in source control, while actual.png and diff.png files should be ignored

Workflow Tasks

csstest --generate

This tasks should be run when new tests are added and before the first time csstest is run. It generates *_expected.png for each fixture which does not have an existing expectation

csstest --accept

This task should be run when tests have failed, but we wish to accept the results as new expectations. When a change has been made on purpose.

Options

options.src

Type: files globbing pattern Default value: **/*Demo.html

The list of fixtures to generate screenshots from.

options.sizes

Type: Array Default value: [ "iphone4P" ]

An array of strings of devices screen sizes which tests are run against. Possible values are iphone4L, iphone5L, ipadL, iphone4P, iphone5P, ipadP, vga, svga, xvga, 720p, 1080p

options.images

Type: String Default value: images

The root directory for expected, actual and diff images

Caveats

Fragility

CssTests are very fragile with regard to browser version and especially operating system. Internally csstest uses PhanomtJS to render pages, and PhantomJS will use the underlying operating system to render fonts and some elements. Subtle differences in font antialiasing will break tests. Expectations should be generated and tested on known environments.

Quality

PhantomJS is not as good at rendering html as regular desktop browsers, as such the generated renderings may not look perfect compared to other browsers. You should not attempt to use csstest to do acceptance testing, but use csstest as a mechanism to alert you to unexpeted changes.

Other Gotchas

• Avoid tests with scrollbars
• Avoid tests that have asyncronous behaviour (eg ajax requests) - mock these out

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

Release History

0.1.0 Initlal Publish 0.0.1 Initial Release