Unmaintained notice: As of December 22nd 2017 this project will no longer be maintained. What started out as a creative experiment four years ago became a significant tool in Huddle's Web development workflow, as well as the workflows of external Web engineers. But like PhantomCSS, its time to move on.

grunt-phantomflow

A grunt plugin for PhantomFlow

Grunt

Basics

This plugin requires Grunt ~0.4.2

If you are unfamilar with Grunt check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins.

npm install grunt-phantomflow --save-dev

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

grunt.loadNpmTasks('grunt-phantomflow');

Setup

grunt.config.set('phantomflow', {
    app: {
        /*
            How many threads would you like to parallelise on?
            Default value is 4
        */
        threads: 4,

        /*
            Any command line options to be passed down to casper?
            Example: ['--cookies-file=testcookies.txt']
            Default value is []
        */
        casperArgs: [],

        /*
            Should a report/visualisation be generated after
            the test run? Default value is false
        */
        createReport: false,

        /*
            Should the report output live somewhere else, e.g. for
            proxying through a real webserver?
            Example: '../visualtest/htdocs'
            Default value is undefined.
            If unset, the default set by PhantomFlow will be used.
        */
        reports: null,
        
        /*
            Do you have scripts to include?
            Default value is ./include
        */
        includes: './include',
        
        /*
            Where do the tests live?
            Default value is ./test
        */
        tests: './test',
        
        /*
            Where should the results go?
            Default value is ./test-results
        */
        results: './test-results',
        
        /*
            Hide elements in the page
        */
        hideElements: ['img', 'input']
    }
});

Command line parameters

Running a specific test

If you're working on a test you can use the test parameter to run a specific test file. The value can be a substring of the file name. Please note that test filenames should follow the *.test.js naming convention.

grunt phantomflow:websitetests --test=mytestfile

Reporting

To show the PhantomFlow visualisation use the 'report' param. You need to have previously generated a report by setting the createReport option to true. Tests will not be executed when the 'report' param is used. The previously generated visualisation will open in your browser.

grunt phantomflow:websitetests --report

Multithreading

By default phantomflow will divide and execute groups of tests concurrantly on different threads. By default this is 4 threads

Use the thread parameter to increase the amount of threads and reduce the feedback time.

grunt phantomflow:websitetests --threads=8

Debugging

Show more logging: grunt phantomflow:websitetests --debug=1

Save screenshots and show more logging: grunt phantomflow:websitetests --debug=2

By default phantomflow will not abort when a test fails, set the earlyexit parameter to true stop the tests upon seeing the first failure.

grunt phantomflow:websitetests --earlyexit=true

Remote debugging using Web Inspector.

PhantomJS supports remote debugging. The following grunt options allow you to start phantom with the correct options.

grunt.config.set('phantomflow', {
    app: {
        remoteDebug: true, // default false
        remoteDebugAutoStart: false, // default false,
        remoteDebugPort: 9000 // default 9000
    }
});

Overview

In your project's Gruntfile, use either grunt.initConfig( {} ) or grunt.config.set( 'phantomflow', {} ).

var phantomflowConfig = {
  test: {
    tests: '/mytests'
  },
  report: {} // this task is reserved for reporting only
};

grunt.initConfig({
  decision: phantomflowConfig
};