grunt-wendy

CasperJS test runner built for GruntJS

This was originally a fork of ronaldlokers/grunt-casperjs but with more features:

• custom casper test runners
• no grunt output (silent flag of grunt-casperjs is always on)
• customizable output parsing
• aggregated results across all casper tasks run
• custom grunt exit status (warns on skips/dubious instead of failing)

Screenshot

Getting Started

This plugin requires Grunt >=0.4.0

This plugin requires phantomjs-prebuilt ~2.1.4. It is specified as a peer dependency, so be sure to install it manually.

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 --save-dev grunt-wendy
# DON'T FORGET THE phantomjs-prebuilt PEER DEPENDENCY

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

grunt.loadNpmTasks('grunt-wendy');

The "wendy" task

Overview

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

Usage Examples

Default Options

grunt.initConfig({
  wendy: {
    options: {
      async: 'eachSeries',
      spawnOpts: null,
      cli: [],
      runner: 'test',
      formatter: formatter, // function in tasks/lib/formatter.js
      formatterOptions: {
        whitespace: true,
        filter: null
      },
      fail: ['failed'],
      warn: ['dubious', 'skipped']
    },
    files: ['tests/e2e/**/*.js']
  },
})

Some nice options for Jenkins / CI servers

grunt.initConfig({
  wendy: {
    options: {
      async: 'each',
      cli: [
        '--no-colors',          // jenkins hates color
        '--log-level=error',    // hide casper logging
        '--web-security=false'  // phantomjs option
      ],
      formatterOptions: {
        whitespace: true,
        // filter out useless headers since we're running async and they'll
        // be out of order
        filter: /(Test file:)|(tests executed)|(^\w*#)/
      },
      fail: ['failed'],   // fail on failed
      warn: ['dubious']   // don't fail on dubious
    },
    files: ['tests/e2e/**/*.js']
  }
});

Reading CLI options from Grunt

CasperJS CLI options can also be passed directly from the command line when running grunt. To use this feature, prefix the args with wendy and they'll be passed through from grunt to casper. E.g.

grunt wendy:myTests --wendy-somearg --wendy-server=http://my.dev --baz=z

Will pass the args to casper as if you had run the command:

casper test --somearg --server=http://my.dev myTests/

Note that the wendy is removed, and args not beginning with wendy, like baz were not included.

Options

Async

Tasks are run in series by default (one after the other). To change how tests are run, set the async option to a node async compatible value such as:

• each - run in parallel
• eachSeries - run in series

wendy: {
  options: {
    async: 'each'
  },
  inparallel: ['tests/e2e/a/*.js'],
  inparallel2: ['tests/e2e/b/*.js']
}

Node child_process options

The task spawns casperJs binary instances as child processes of node. The raw child_process.exec options can be modified with the spawnOpts task option:

wendy: {
  options: {
    spawnOpts: {
      cwd: '../',
      env: {
        SERVER:   'QA',
        API_KEY:  'abc123'
      },
    }
  },
  inparallel: ['tests/e2e/a/*.js'],
  inparallel2: ['tests/e2e/b/*.js']
}

Of note is that you can change where you're running CasperJS from, e.g. in case your node_modules/ folder is for some reason not at the root of your project and you want to run CasperJS from a different directory to so you can require those modules.

Most likely you won't need this or will just want the env key values.

CLI Options

CasperJS CLI options (including user defined ones) can be passed in using 'cli' in the options object

wendy: {
  options: {
    cli: ['--foo=bar', '--no-colors']
  },
  files: ['tests/e2e/**/*.js']
}

See also Reading CLI options from grunt.

Runner

The task uses casper's included test runner by default. If you'd like to use a custom runner, casper allows this. Specify a new test runner JS file to the runner option and wendy will hook it up.

wendy: {
  options: {
    runner: 'tests/e2e-runner.js'
  },
  files: ['tests/e2e/**/*.js']
}

Formatter

This task captures all casper output and allows formatting of that output. The formatter can be customized by passing in a function like so:

wendy: {
  options: {
    formatter: function (grunt, options, data) {
      grunt.log.write(data);
    }
  },
  files: ['tests/e2e/**/*.js']
}

The data argument is always a string, a line from casper's stdout or stderr.

The default formatter uses the clean option as well. See its source here for an example: formatter.js

Formatter Options

This task tries to clean up the casper output whitespace and outputs aggregated test results when multiple suites (multiple files) are run in a single task.

If you change the formatter this option may not apply.

• whitespace: boolean -- true to clean up casper whitespace
• filter: regex -- anything that matches this filter will not be output

wendy: {
  options: {
    formatterOptions: {
      // don't try to clean up whitespace
      whitespace: false,

      // don't output lines saying 'Test file:' name and the suite summary
      filter: /(Test file:)|(tests executed)/
    }
  },
  tests: ['tests/e2e/**/*.js']
}

Grunt exit status

Instead of failing on dubious tests or passing when tests are skipped, this task only fails when a test actually fails. You can go back to default grunt behavior, or customize your own using the fail and warn options. The options take an array with values passed, failed, dubious, and skipped.

wendy: {
  options: {
    fail: ['failed'], // fail the task if any tests failed
    warn: ['dubious'] // grunt warning when tests dubious
  },
  files: ['tests/e2e/**/*.js']
}

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.

Follow the standards of the included eslint and markdownlint.

CHANGELOG

• 3.0.4
  • bump all dependencies
• 3.0.3
  • bump casperjs to 1.1.1
• 3.0.2
  • Update deps to latest stables
• 3.0.1
  • Fix require!
• 3.0.0
  • Update deps
• 2.2.1
  • Update deps
• 2.2.0
  • Expose node child_process spawn opts as a task option.
• 2.1.1
  • License update
• 2.1.0
  • Add custom cli flag support, passing --wendy cli flags to casper
• 2.0.0
  • fix travis build by installing phantom, major bump
• 1.0.5
  • phantomjs is now a peer dependency
• 1.0.4
  • Ensure utf-8 output on process.stdout.write
• 1.0.3
  • Don't need lodash, removed
• 1.0.2
  • Logo :p
• 1.0.1
  • Readme update
• 1.0.0
  • Change clean to formatterOptions.whitespace
  • Add filter to formatterOptions
• 0.0.6
  • Add fail and warn options
• 0.0.5
  • Add formatter option
• 0.0.4
  • Use grunt.util.linefeed for better Windows output
• 0.0.3
  • Add test for dubious output
  • Fix aggregated output (skipped and dubious showing same result)
• 0.0.2
  • Split into modules in lib/
• 0.0.1
  • Forked from ronaldlokers/grunt-casperjs
  • Refactor into single grunt task module
  • Rename task from casperjs to wendy
  • Changed casperjsOptions option key to cli
  • Add support for custom runner
  • Always use silent option from unpublished release of casperjs
  • Expose node async settings
  • parse casper output and show aggregated results for a set of files if clean option is true (default)