Snapdragon

A command-line Jasmine (JavaScript) test runner built with developer workflow in mind.

Installation

Add this line to your application's Gemfile:

gem 'snapdragon'

And then execute:

$ bundle

Or install it yourself as:

$ gem install snapdragon

Install PhantomJS

You need at least PhantomJS 1.8.1. There are no other external dependencies (you don't need Qt, or a running X server, etc.)

Mac OS X

I recommend installing PhantomJS using Homebrew on Mac OS X. Using Homebrew it can be installed as easily as running the following command:

$ brew install phantomjs

Quick Start Guide

If you are a visual learner Brian Miller and I have put together a Free Snapdragon Screencast at The Code Breakdown.

For those of you that like to jump right in and start playing with new tools follow the steps below to get started.

1. Install Snapdragon and PhantomJS as outlined above.

2. Create a simple Jasmine spec file example/spec/hoopty_spec.js with the following content. Note: the // require_relative() directive at the top of the file. This tells Snapdragon what implementation file(s) it needs to run the specs in this file.

   // require_relative('../src/hoopty.js')
   
   describe("Hoopty", function() {
     describe(".hello", function() {
       it("says hello there", function() {
         var f = new Hoopty();
         expect(f.hello()).toBe("Hello There");
       });
     });
   });

3. Create the implementation file for the spec file example/src/hoopty.js with the following content.

   var Hoopty = function() {
     this.hello = function() {
       return "Hello There";
     }
   };

4. Run your spec file with the following command:

   $ snapdragon example/spec/hoopty_spec.js
   

   You should see output that looks similar to the following.

   Running examples...
   
   Finished in 0.001 seconds
   1 example, 0 failures
   

Thats it, you now have Snapdragon running a Jasmine spec.

Usage (snapdragon)

The snapdragon command allows you to run your Jasmine specs from the command-line just as you would with RSpec and other testing tools. The following are some usage examples.

Run a specific describe/it block

The following runs the describe or it block that corresponds to line number 23 in the spec/javascript/foo_spec.js file.

$ snapdragon spec/javascript/foo_spec.js:23

Run an entire spec file(s)

$ snapdragon spec/javascript/foo_spec.js spec/javascript/bar_spec.js

Run an entire directory of spec files

The following recursively explores the given directories contents for files that end in spec.js or Spec.js and runs the tests in the identified spec files.

$ snapdragon spec/javascripts

Run combination of files and directories

$ snapdragon spec/javascript custom_js/tests/foo_spec.js custom_js/test/bar_spec.js

Run test files matched by default pattern (spec/**/*_spec.js)

$ snapdragon

Run test files matched by custom pattern

The following is an example command that specifies a custom pattern to use to match test files to run. Please note the double quote marks around the pattern. These are necessary as without them most shells will try and resolve the pattern for you. Further details on the glob syntax can be found here.

$ snapdragon -P "spec/assets/javascripts/foo/*_spec.js"

Output Usage Details/Help

$ snapdragon --help

Usage (snapdragon_server)

The snapdragon_server command allows you to run your Jasmine specs in your browser. When this command is run it will launch the snapdragon_server and open your default browser to the proper URL to run your specified test suite. This is especially useful if you want to debug some JavaScript as your browser most likely has a JavaScript debugger built into it. A few examples of this commands usage follow.

Run a specific describe/it block

The following runs the describe or it block that corresponds to line number 23 in the spec/javascript/foo_spec.js file.

$ snapdragon_server spec/javascript/foo_spec.js:23

Run an entire spec file(s)

$ snapdragon_server spec/javascript/foo_spec.js spec/javascript/bar_spec.js

Run an entire directory of spec files

The following recursively explores the given directories contents for files that end in spec.js or Spec.js and runs the tests in the identified spec files.

$ snapdragon_server spec/javascript custom_js/specs

Run combination of files and directories

$ snapdragon_server spec/javascript custom_js/tests/foo_spec.js custom_js/test/bar_spec.js

Run test files matched by default pattern (spec/**/*_spec.js)

$ snapdragon_server

Run test files matched by custom pattern

The following is an example command that specifies a custom pattern to use to match test files to run. Please note the double quote marks around the pattern. These are necessary as without them most shells will try and resolve the pattern for you. Further details on the glob syntax can be found here.

$ snapdragon_server -P "spec/assets/javascripts/foo/*_spec.js"

Output Usage Details/Help

$ snapdragon_server --help

Additional Options

Below is a listing of the various options that can be passed to either the snapdragon or snapdragon_server commands.

Version (-v, --version)

When given this option it will output the version that you are using and exit without running any tests.

Help (-h, --help)

When given this option it will output basic usage summary and exit without running any tests.

Format (-f FORMAT, --format FORMAT)

This option allows you to specify the output format of the tests. By default it outputs using the console format. This option is extremely useful when you would like to use snapdragon inside of a CI process because you can instruct it to output in other formats such as junit which CI services can parse.

The following are the currently supported FORMAT values.

• console (default)
• junit

Color (--no-color, --no-colour)

If you would like to disable ANSI color output which is enabled by default, include either the --no-color or --no-colour option.

Pattern (-P PATTERN, --pattern PATTERN)

When this option is not given and no file or directory paths are given it uses the default pattern "spec/**/*_spec.js".

When given this option without any explicit file paths or directory paths it will use the provided glob pattern to identify which test files to run. Any example usage of this option can be seen above in the Run test files matched by custom pattern section. For more details on the glob pattern syntax please refer to the Ruby Dir.glob documentation.

// require_relative() directive

Snapdragon also provides a // require_relative() directive that the Snapdragon preprocessor looks for to identify the necessary implementation files that need to be loaded for the spec files to run. This directive should define the relative path to associated implementation files needed for a spec, relative to that spec file. The following is an example spec and implemantion file.

example/src/hoopty.js

var Hoopty = function() {
  this.hello = function() {
    return "Hello There";
  }
};

example/spec/hoopty_spec.js

// require_relative('../src/hoopty.js')

describe("Hoopty", function() {
  it("exists", function() {
    var f = new Hoopty();
    expect(f).not.toBe(undefined);
  });

  describe(".hello", function() {
    it("says hello there", function() {
      var f = new Hoopty();
      expect(f.hello()).toBe("Hello There");
    });
  });
});

The ChangeLog

Information on notable changes in each release can be found in the ChangeLog.

IRC Channel

We have a persistent IRC channel (#snapdragon-js) on freenode. Feel free to join it and ask questions, make suggestions, talk with developers, or just hang out.

The Back Story

If you have ever used Jasmine for your JavaScript BDD style testing framework I am sure you have run into the following issues just as I have.

1. Getting up and running with Jasmine is quite a pain and the examples of how to setup your SpecRunner.html are sparse.
2. Having to manually add the dependency files and spec files to the SpecRunner.html is a huge pain in the ass.
3. Limiting a test run to a specific spec file is near impossible with the only solution being to comment out script tags in your SpecRunner.html.
4. Limiting a test run to a specific describe or it block is near impossible because the only way to do it is with the spec query param that matches the full description of the describe or it block including all its parents. This can be very long and very prone to typos if you try to do this.
5. Oh, and did I mention that you have to do all of this in a browser with the SpecRunner.html loaded which is not where you actually write your code.

The above issues created a horrible development workflow. Especially since I came from the world of RSpec where the above issues are non-existent and it is easily run from the command line and integrated into most editors.

Snapdragon is my preferred solution to the above listed issues.

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Write your tests & dev your feature using BDD/TDD with RSpec.
4. Commit your changes (git commit -am 'Add some feature')
5. Push to the branch (git push origin my-new-feature)
6. Create new Pull Request