Automate CSS regression testing with PhantomCSS
This is a fork of the original grunt-phantomcss, with the following updates and enhancements:
Currently this fork is not available on npm, however, you can install and use this version by following the steps below.
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 @micahgodbolt/grunt-phantomcss --save-dev
Or add the following line to your package.json
:
"@micahgodbolt/grunt-phantomcss": "^1.0.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');
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
phantomjsArgs: [
// optional, array of phantomJS CLI options
]
},
src: [
'test/visual/**/*.js'
]
}
});
Type: String|Array
The test files to run.
Type: Number
Default: 0.05
The change percentange tolerated between screenshots (for instance to match anti-aliasing bugs).
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.
Type: String
Default: './results'
The directory, relative to the src file, to store source, diff, and failure screenshots after tests.
Type: Array
Default: [1280, 800]
The viewport size to test the site in [width, height]
format. Useful when testing responsive layouts.
Type: String
Default: error
The CasperJS log level. See CasperJS: Logging for details.
Type: String
Default: ``
Optional parameter passed to testfiles for prepending to relative URL's. Useful when testing against multiple environments.
Type: Array
Default: []
Optional array of CLI arguments passed when running phantomJS. See PhantomJS Command-line Options for details.
// Example PhantomJS Command-line Options
phantomcss: {
options: {
[...]
phantomjsArgs: [
'--ssl-protocol=tlsv1',
'--ignore-ssl-errors=true',
]
}
}
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'
]
}
});
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'
]
}
},
});
Test files should do the following:
casper.start()
when it begins, so all test files need to start with casper.thenOpen
.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:
casper.thenOpen(phantom.rootUrl + 'todo')
.then(function() {
jQuery('*').css('font-family', 'arial, sans-serif');
})
.then(function() {
phantomcss.screenshot('#todo-app', 'Main app');
});
See the CasperJS documentation and the PhantomCSS documentation for more information on using CasperJS and PhantomCSS.
For further examples, refer to the following posts: