grunt-contrib-jasmine/README.md

grunt-contrib-jasmine

Run jasmine specs headlessly through PhantomJS.

Getting Started

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

npm install grunt-contrib-jasmine --save-dev

Jasmine task

Run this task with the grunt jasmine command.

Overview

grunt-contrib-jasmine automatically builds and maintains your spec runner and runs your tests headlessly through phantomjs

Substantial credit goes to Camille Reynders (@creynders) for the first decent implementation of jasmine through grunt which served as motivation for all the future work.

Run specs locally or on an ad hoc server

Run your tests on your local filesystem or via a server task like grunt-contrib-connect.

AMD Support

Includes a SpecRunner template customized for use with AMD modules and requirejs.

Customize your SpecRunner with your own template

Supply your own underscore template to automatically build your SpecRunner custom to your use.

Example application usage

• Pivotal Labs' sample application

Options

src

Type: String|Array

Minimatch - This defines your source files. These are the files that you are testing.

options.specs

Type: String|Array

Minimatch - These are your Jasmine specs.

options.vendor

Type: String|Array

Minimatch - These are third party libraries, generally loaded before anything else happens in your tests. You'll likely add things like jQuery and Backbone here.

options.helpers

Type: String|Array

Minimatch - These are non-source, non-spec helper files. In the default runner these are loaded after vendor files

options.outfile

Type: String Default: _SpecRunner.html

This is the auto-generated specfile that phantomjs will use to run your tests. This is automatically deleted upon normal runs

options.host

Type: String Default: ''

This is the host you want phantomjs to connect against to run your tests.

e.g. if using an ad hoc server from within grunt

host : 'http://127.0.0.1:8000/'

Or, using templates

host : 'http://127.0.0.1:<%= connect.port %>/'

Not defining a host will mean your specs will be run from the local filesystem.

options.template

Type: String Default: default Options: default, requirejs, yourcustomtemplate.tmpl

Specify a custom template to use when generating your Spec Runner. Templates are parsed as underscore templates and provided the expanded list of files needed to build a specrunner.

options.templateOptions

Type: Object Default: {}

These options will be passed to your template as an 'options' hash so that you can provide settings to your template.

Flags

Name: build

Turn on this flag in order to rebuild the specrunner without deleting it. This is useful when troublshooting templates, running in a browser, or as part of a watch chain e.g.

watch: {
  pivotal : {
    files: ['src/**/*.js', 'specs/**/*.js'],
    tasks: 'jasmine:pivotal:build'
  }
}

Template Options

Default template

No specific options are expected or used.

RequireJS template

templateOptions.requirejs

Type: String

The path to requirejs if you need to specify an alternate version.

templateOptions.loaderPlugin

Type: String

The loader plugin to prefix all loaded src files. This is useful for processing your specs through the likes of CoffeeScript or TypeScript plugins. Keep in mind you will need to specify the path to the plugin in the require config.

templateOptions.requireConfig

Type: Object

This object is JSON.stringify()-ed into the template and passed into require.config()

Basic Use

Sample configuration to run Pivotal Labs' example Jasmine application.

// Example configuration
grunt.initConfig({
  jasmine: {
    pivotal: {
      src: 'src/**/*.js'
      options: {
        specs: 'spec/*Spec.js',
        helpers: 'spec/*Helper.js'
      }
    }
  }
}

Supplying a custom template

Supplying a custom template to the above example

// Example configuration
grunt.initConfig({
  jasmine: {
    customTemplate: {
      src: 'src/**/*.js',
      options: {
        specs: 'spec/*Spec.js',
        helpers: 'spec/*Helper.js'
        template: 'custom.tmpl'
      }
    }
  }
}

Sample RequireJS usage

// Example configuration
grunt.initConfig({
  connect: {
    test : {
      port : 8000
    }
  }
  jasmine: {
    requirejs: {
      src: 'src/**/*.js',
      options: {
        specs: 'spec/*Spec.js',
        helpers: 'spec/*Helper.js',
        host: 'http://127.0.0.1:8000/',
        template: 'requirejs',
        templateOptions: {
          requireConfig: {
            baseUrl: 'src/'
          }
        }
      }
    }
  }
}

Note the usage of the 'connect' task configuration. You will need to use a task like grunt-contrib-connect if you need to test your tasks on a running server.

RequireJS notes

If you end up using the requirejs template, it's worth looking at the RequireJS template source in order to familiarize yourself with how it loads your files. The load process essentially consists of a series of nested require blocks, incrementally loading your source and specs:

require([*YOUR SOURCE*], function() {
  require([*YOUR SPECS*], function() {
    require([*GRUNT-CONTRIB-JASMINE FILES*], function() {
      // at this point your tests are already running.
    }
  }
}

Release History

• 2012-12-02   v0.2.0   Generalized requirejs template config, added loader plugin, tests for templates, updated jasmine to 1.3.0
• 2012-11-23   v0.1.2   Updated for new grunt/grunt-contrib apis
• 2012-11-06   v0.1.1   Fixed race condition in requirejs template
• 2012-11-06   v0.1.0   Ported grunt-jasmine-runner and grunt-jasmine-task to grunt-contrib

---

Task submitted by Jarrod Overson

This file was generated on Mon Dec 03 2012 00:32:53.