Shenandoah adds support for command-line and in-browser JavaScript unit tests in your buildr, rails, or other rake-using project. It bundles several great tools together in a convention-over-configuration, Rails-like way. These tools include:
Rhino - a Java-based JavaScript interpreterScrew.Unit - a behaviour-driven development syntax for JavaScript similar to RSpecSmoke - a JavaScript mocking & stubbing library similar to Mochaenv.js - a DOM implementation written entirely in JavaScriptShenandoah is a generalization of the Blue Ridge plugin for rails. (See below for differences.)
Shenandoah provides a command-line runner and a server to enable in-browser testing with simple path management.
The command-line runner is a lot like any other test framework's: It runs some or all of the specs and tells you which ones fail.
The server (after you start it), is available at http://localhost:4410/. The root path will give you a list of specs, linked to the pages where you can run them.
Shenandoah also provides an interactive shell a la irb. You can use it to experiment with javascript in a similar context to the command line runner.
The following sections describe how to invoke Shenandoah with various build systems.
The Shenandoah gem is hosted at Gemcutter. Install it like so:
$ gem install shenandoah# In your buildfile
require 'shenandoah/buildr'
# ...
define :web_js do
test.using :shenandoah, :main_path => project('web')._("src/main/webapp/js")
endIn buildr, Shenandoah expects to find your specs in the src/spec/javascript directory. The main path defaults to src/main/javascript, but may be changed as in the example.
To run the specs from the command line:
$ buildr web_js:testTo run an individual spec file called "application_spec.js":
$ cd web_js
web_js$ buildr test:applicationTo start the server:
$ buildr web_js:shen:serveTo start the shell:
$ buildr web_js:shen:shellAdd a config.gem entry in environment.rb:
config.gem "shenandoah", :version => '0.1.0', :lib => falseInstall the rake tasks:
$ script/generate shenandoahIn a rails project, Shenandoah will look for specs in spec/javascript, examples/javascript, or test/javascript. The main path is public/javascripts.
To run the specs from the command line:
$ rake shen:specTo run an individual spec file called "application_spec.js":
$ rake shen:spec[application]To start the server:
$ rake shen:serveTo start the shell:
$ rake shen:shell# In your Rakefile
require 'rubygems'
require 'shenandoah/tasks'
Shenandoah::Tasks.new(:main_path => 'public/javascript', :spec_path => 'test/javascript')With plain rake, Shenandoah defaults to lib for the main path and spec for the spec path.
To run all the specs from the command_line:
$ rake shen:specTo run an individual spec file called "application_spec.js":
$ rake shen:spec[application]To start the server:
$ rake shen:serveTo start the shell:
$ rake shen:shellEach Shenandoah spec is two files: a javascript spec (e.g. name_spec.js) and and HTML fixture (e.g. name.html). The spec contains the the actual Screw.Unit test definitions. The fixture contains the DOM that the spec (or the code under test) relies on to work.
Shenandoah is opinionated and assumes you're using jQuery by default. The plugin itself actually uses jQuery under the covers to run Screw.Unit.
require_spec("spec_helper.js");
require_main("application.js");
Screw.Unit(function() {
describe("Your application javascript", function() {
it("does something", function() {
expect("hello").to(equal, "hello");
});
it("accesses the DOM from fixtures/application.html", function() {
expect($('.select_me').length).to(equal, 2);
});
});
});(By the way, we don’t actually encourage you to write specs and tests for standard libraries like JQuery and Prototype. It just makes for an easy demo.)
It's very easy to add support for Prototype. Here's an example spec:
jQuery.noConflict();
require_spec("spec_helper.js");
require_main("prototype.js");
require_main("application.js");
Screw.Unit(function() {
describe("Your application javascript", function() {
it("does something", function() {
expect("hello").to(equal, "hello");
});
it("accesses the DOM from fixtures/application.html", function() {
expect($$('.select_me').length).to(equal, 2);
});
});
});To see Shenandoah in action inside a working Rails app, check out the Shenandoah sample application. Among other things, this sample app includes examples of:
describe functionsShenandoah provides a handful of functions that help you write specs that can run inside a web browser as well from the Rhino command-line test runner.
Loads a dependency from the main path.
When running from the command line, require_main becomes a Rhino call to load, resolving the file against the configured main_path. In a web browser, require_main loads and evaluates the script using a synchronous background request to ensure that all the scripts are loaded in order.
Loads a dependency from the spec path.
Just like require_main, but for spec files.
Shenandoah provides an irb-like JavaScript shell for debugging your JavaScript code. jQuery and env.js are pre-loaded for you to make debugging DOM code easy.
=================================================
Rhino JavaScript Shell
To exit type 'exit', 'quit', or 'quit()'.
=================================================
- loaded env.js
- sample DOM loaded
- jQuery-1.2.6 loaded
=================================================
Rhino 1.7 release 2 PRERELEASE 2008 07 28
js> print("Hello World!")
Hello World!
js> Note that if you have rlwrap installed and on the command line path (and you really, really should!), then command-line history and readline arrow-up and down will be properly supported automatically. (You can get rlwrap from your friendly neighborhood package manager.)
Smoke is a JavaScript mocking and stubbing toolkit that is somewhat similar to FlexMock or Mocha. It is automatically wired-in to undo its mocking after each Screw.Unit it block. Here's an example.
it("calculates the total cost of a contract by adding the prices of each component", function() {
var componentX = {}, componentY = {};
mock(SalesContract).should_receive("calculateComponentPrice").with_arguments(componentX).exactly(1, "times").and_return(42);
mock(SalesContract).should_receive("calculateComponentPrice").with_arguments(componentY).exactly(1, "times").and_return(24);
expect(SalesContract.calculateTotalCost([componentX, componentY])).to(equal, 66);
});Note that the flexible nature of the JavaScript the language means that you might not need to use Smoke, especially for stubbing.
print in your tests while debugging. It works fine from the command line but causes lots of headaches in browser. (Just imagine a print dialog opening ten or fifteen times and then Firefox crashing. This is a mistake I've made too many times! Trust me!)If you see any bugs or possible improvements, please use the project's GitHub issue tracker to report them.
If you like, you could even fork the GitHub repo and start hacking.
Shenandoah is based on the Blue Ridge JavaScript Testing Rails Plugin. The main difference is that it works for any project that uses rake or buildr, not just rails projects. If you are using a rails project, you might consider using Shenandoah instead of Blue Ridge anyway:
The cost for all this is that Shenandoah fixtures can't be opened directly in the browser — they can only be opened via the server.