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.
-
Install Snapdragon and PhantomJS as outlined above.
-
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"); }); }); });
-
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"; } };
-
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.
- Getting up and running with Jasmine is quite a pain and the examples of how to setup your SpecRunner.html are sparse.
- Having to manually add the dependency files and spec files to the SpecRunner.html is a huge pain in the ass.
- 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.
- 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.
- 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
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Write your tests & dev your feature using BDD/TDD with RSpec.
- Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request