grunt-phantomcss
Automate CSS regression testing with PhantomCSS
This is a fork of the original grunt-phantomcss, with the following updates and enhancements:
- Anselmh's updates detailed here
- More modular file structure, storing test baseline(s) and result(s) in the directory of the test file itself rather than within a single root directory. This keeps the baselines, results, and tests together with less coupling between tests.
- PhantomJS updated to v1.98 to fix SSLv3 bug
- New rootUrl option, to accomodate testing against multiple envirronments
Currently this fork is not available on npm, however, you can install and use this version by following the steps below.
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 @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');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
phantomjsArgs: [
// optional, array of phantomJS CLI options
]
},
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.
options.phantomjsArgs
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',
]
}
}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 withcasper.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
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');
});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: