JSpec-Rails - Rails integration for JSpec¶ ↑

JSpec-Rails is a plugin that helps integrate the javascript BDD framework JSpec (github.com/visionmedia/jspec) into Rails.

Jspec-rails has the following features:

• detects file changes and refreshes the browser to cause the specifications to run again - for example you can have Safari, Firefox and IE open and all will rerun the tests when a file is changed

• has a built in mechanism for loading html/DOM fixtures into a play area on the page - so you can define separate html snippets for your javascript to run against and load it before you run your tests

• uses a rails controller to deliver spec files and fixtures

• you can use erb, haml, builder etc. in your fixtures

• you can use erb in your specs

• provides a generator to stub in a new javascript library with it’s associated spec files

Getting Started¶ ↑

Install the plugin:¶ ↑

./script/plugin install git://github.com/bhauman/jspec-rails.git

Initialize your app:¶ ↑

./script/generate jspec_init

Now start or restart your app and navigate to it the jspec controller. For example if you are running webrick on port 3000 navigate to:

http://localhost:3000/jspec

You should see the self tests for the jspec_rails.js library run (and pass).

Using jspec-rails¶ ↑

Let’s generate a new javascript library to test.

./script/generate jspec_library widgeteer

This will create the following files:

Javascript Library:   public/javascripts/widgeteer.js
Specification File:   jspec/spec/widgeteer_spec.js
Sample Fixture:       jspec/fixtures/widgeteer.html.erb

This command also adds a line to jspec/jspec.yml under required_libs:

required_libs:
 - prototype
 - effects
 - widgeteer  // this line was added

Now you can edit the jspec/spec/widgeteer_spec.js and add some specifications for it. Note that each time you save the file it will refresh and run the specs in the browser (the browser needs to be open first).

Writing Specifications¶ ↑

Please refer to the JSpec documentation at:

http://github.com/visionmedia/jspec

Fixtures¶ ↑

Fixtures in terms of testing Javascript are files that are loaded into the DOM to run javascript against.

Fixtures are placed in the jspec/fixtures directory and can easly be loaded into the page. For example if you have a fixture named widgeteer.html.erb in the jspec/fixtures directory, you can load it into your environment from your javascript tests with a call to:

JspecRails.load_fixture('widgeteer');

When you load another fixture the previous one will be replaced. But if you want to explicitly unload the current fixture do this:

JspecRails.clear_fixture();

Fixtures are loaded into the play area.

Play Area¶ ↑

The play_area is a hidden dom element where fixtures are loaded into. The current thinking is that it holds one fixture at a time and its contents are replaced by the next fixture loaded.

You can access the play_area from your javascript specs with a call to

JspecRails.play_area

You can access elements in your fixture through the play_area using the Prototype.js select() method

JspecRails.play_area.select('#id_of_element_inside_my_fixture')

Config¶ ↑

The jspec-rails configuration file can be found at jspec/jspec.yml. The generated config should look something like this:

required_libs:
- prototype
- effects
- jspec_rails
watched_dirs:
- public/javascripts
- jspec/fixtures
- jspec/spec
authorization:
  rails_envs: 
  - production
  username:  jspec
  password:  jspecpassword

The required_libs section lists javascript libraries that are to be included for the test in order. Items of this list are passed directly to javascript_include_tag Rails helper.

The watched_dirs section is a list of directories that are watched for changes. The directories are all relative to Rails.root

The authorization section has no effect on the behavior of the plugin as of yet.

Requirements¶ ↑

As of now this plugin is implemented as an Engine and so requires Rails 2.3. That being said the jspec_controller.rb file in the app directory of the plugin is probably the only file that requires Engine functionality to be found. There are various ways to work around this.

As of now the JSpec javascript library is bundled into this plugin for simplicity.

Notes ¶ ↑

This plugin can easily be extended to work with the Scriptaculous testing framework.

License¶ ↑

(The MIT License)

Copyright © 2009 Bruce Hauman <bhauman@gmail.com>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ‘Software’), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Copyright © 2009 Bruce Hauman, released under the MIT license