Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/bhauman/jspec-rails

Javascript BDD integration for Ruby on Rails
https://github.com/bhauman/jspec-rails

Last synced: 7 days ago
JSON representation

Javascript BDD integration for Ruby on Rails

Awesome Lists containing this project

README 

        
= JSpec-Rails - Rails integration for JSpec



*JSpec*-*Rails* is a plugin that helps integrate the javascript BDD framework 

JSpec (http://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 (c) 2009 Bruce Hauman 



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 (c) 2009 Bruce Hauman, released under the MIT license