BRIMIL01 / snapdragon

A Jasmine JavaScript test runner that lets you run tests on the command-line similar to RSpec.

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

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 specific spec files

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

Run all the specs in directories

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

Combine files and directories

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

// 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