rsutphin-shenandoah 0.1.0

data/.braids

@@ -0,0 +1,8 @@
+--- 
+vendor/buildr: 
+  squashed: true
+  url: git://github.com/apache/buildr.git
+  type: git
+  revision: f726a65f42f8ecd4afe36569f448506183fc1d0a
+  branch: trunk
+  remote: braid/vendor/buildr

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,6 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg
+spec/tmp

data/ChangeLog.markdown

@@ -0,0 +1,13 @@
+0.1.0
+=====
+
+* Supports easier configuration with rails
+  * script/generate shenandoah to outfit a rails project
+  * script/generate shen_spec *name* to generate a spec and a fixture
+
+shenandoah 0.0.0
+================
+
+* Initial version -- extracted from PSC's buildr-ridge extension, which was itself derived from the Blue Ridge JavaScript Testing Plugin
+* Supports buildr
+* Supports generic execution with rake

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Rhett Sutphin
+
+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.

data/LICENSE-Blue-Ridge

@@ -0,0 +1,20 @@
+Copyright (c) 2008-2009 Relevance, Inc.
+
+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.

data/LICENSE-Screw.Unit

@@ -0,0 +1,22 @@
+Copyright (c) 2008 Nick Kallen
+ 
+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.

data/LICENSE-Smoke

@@ -0,0 +1,22 @@
+Copyright (c) 2008 Andy Kent
+
+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.

data/README.markdown

@@ -0,0 +1,280 @@
+Shenandoah JavaScript Testing metapackage
+=========================================
+
+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 interpreter
+* `Screw.Unit` - a behaviour-driven development syntax for JavaScript similar to RSpec
+* `Smoke` - a JavaScript mocking & stubbing library similar to Mocha
+* `env.js` - a DOM implementation written entirely in JavaScript
+
+Shenandoah is a generalization of the [Blue Ridge][blue-ridge] plugin for rails.  (See below for differences.)
+
+[blue-ridge]: http://github.com/relevance/blue-ridge
+
+General Use
+-----------
+
+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/](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.
+
+Installing and Running
+----------------------
+
+To install:
+
+    $ gem install shenandoah
+
+### Use with buildr
+
+    # In your buildfile
+    require 'shenandoah/buildr'
+    # ...
+    define :web_js do
+      test.using :shenandoah, :main_path => project('web')._("src/main/webapp/js")
+    end
+
+In 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:test
+
+To run an individual spec file called "application_spec.js":
+
+    $ cd web_js
+    web_js$ buildr test:application
+
+To start the server:
+
+    $ buildr web_js:shen:serve
+
+To start the shell:
+
+    $ buildr web_js:shen:shell
+
+### Use with Rails
+
+Add a config.gem entry in environment.rb:
+
+    config.gem "shenandoah", :version => '0.1.0', :lib => false
+
+Install the rake tasks:
+
+    $ script/generate shenandoah
+
+In 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:spec
+
+To run an individual spec file called "application_spec.js":
+
+    $ rake shen:spec SHEN_SPEC=application
+
+To start the server:
+
+    $ rake shen:serve
+
+To start the shell:
+
+    $ rake shen:shell
+
+### Use with rake (in general)
+
+    # 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:spec
+
+To run an individual spec file called "application_spec.js":
+
+    $ rake shen:spec SHEN_SPEC=application
+
+To start the server:
+
+    $ rake shen:serve
+
+To start the shell:
+
+    $ rake shen:shell
+
+Specs and Fixtures
+------------------
+
+Each 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.
+
+Example Using jQuery
+--------------------
+
+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.)
+
+Example Using Prototype
+-----------------------
+
+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);
+        });
+      });
+    });
+
+More Examples
+-------------
+
+To see Shenandoah in action inside a working Rails app, check out the [Shenandoah sample application](http://github.com/rsutphin/shenandoah-rails-sample-app).  Among other things, this sample app includes examples of:
+
+* using nested `describe` functions
+* setting up per-spec HTML "fixtures"
+* stubbing functions
+* mocking functions
+* running the javascript specs as part of your default Rake task
+
+JavaScript API
+--------------
+
+Shenandoah 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.
+
+### require_main(filename)
+
+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.
+
+### require_spec(filename)
+
+Loads a dependency from the spec path.
+
+Just like `require_main`, but for spec files.
+
+The Shell
+---------
+
+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.)
+
+Mocking Example with Smoke
+--------------------------
+
+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.
+
+Tips & Tricks
+-------------
+* Avoid using `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!)
+
+Bugs & Patches
+--------------
+
+If you see any bugs or possible improvements, please use the project's [GitHub issue tracker](http://github.com/rsutphin/shenandoah/issues) to report them.
+
+If you like, you could even fork the [GitHub repo](http://www.github.com/rsutphin/shenandoah) and start hacking.
+
+Differences from Blue Ridge
+---------------------------
+
+Shenandoah is based on the [Blue Ridge JavaScript Testing Rails Plugin][blue-ridge].  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:
+
+* Blue Ridge requires all specs to be in the same directory (subdirectories are not allowed).  Shenandoah does not have this limitation.
+* Shenandoah's design places the spec js and the fixture html in the same directory.  Blue Ridge puts them in separate directories, leading to parallel hierarchies.
+* Shenandoah provides an in-browser index for the specs.  Blue Ridge requires opening each HTML fixture separately.
+
+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.
+
+Links
+-----
+
+* [Blue Ridge JavaScript Testing Rails Plugin](http://github.com/relevance/blue-ridge)
+* [Blue Ridge Sample App](http://github.com/relevance/blue-ridge-sample-app)
+* [Justin Gehtland's "Fully Headless JSSpec" Blog Post](http://blog.thinkrelevance.com/2008/7/31/fully-headless-jsspec)
+* [Screw.Unit](http://github.com/nkallen/screw-unit)
+* [Screw.Unit Mailing List](http://groups.google.com/group/screw-unit)
+* [Smoke](http://github.com/andykent/smoke)
+* [env.js](http://github.com/thatcher/env-js)
+* [env.js Mailing List](http://groups.google.com/group/envjs)
+* [Mozilla Rhino](http://www.mozilla.org/rhino/)
+* [W3C DOM Specifications](http://www.w3.org/DOM/DOMTR)
+
+Contributors
+------------
+* Justin Gehtland
+* Geof Dagley
+* Larry Karnowski
+* Chris Thatcher (for numerous env.js bug fixes!)
+* Raimonds Simanovskis
+* Jason Rudolph
+
+Copyrights
+------------
+* Copyright © 2009 Rhett Sutphin, under the MIT license
+* Based on blue-ridge, Copyright 2008-2009 [Relevance, Inc.](http://www.thinkrelevance.com/), under the MIT license
+* env.js     - Copyright 2007-2009 John Resig, under the MIT License
+* Screw.Unit - Copyright 2008 Nick Kallen, license attached
+* Rhino      - Copyright 2009 Mozilla Foundation, GPL 2.0
+* Smoke      - Copyright 2008 Andy Kent, license attached

data/Rakefile

@@ -0,0 +1,71 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "shenandoah"
+    gem.summary = %Q{A javascript test framework for buildr, rails, and other ruby-built projects}
+    gem.email = "rhett@detailedbalance.net"
+    gem.homepage = "http://github.com/rsutphin/shenandoah"
+    gem.authors = ["Rhett Sutphin"]
+    gem.rubyforge_project = "detailedbalance"
+
+    # Exclude test-only vendored buildr
+    gem.files.exclude("vendor/**/*")
+
+    gem.add_runtime_dependency('sinatra', '>= 0.9.2')
+    gem.add_runtime_dependency('haml', '>= 2.0.9')
+    gem.add_runtime_dependency('rake')
+    gem.add_runtime_dependency('rails', '>= 2.1.0')
+
+    # Have to use rspec 1.2.4 for buildr compat
+    gem.add_development_dependency('rspec', '= 1.2.4')
+    gem.add_development_dependency('rack-test', '>= 0.3.0')
+    gem.add_development_dependency('rspec_hpricot_matchers', '>= 1.0.0')
+    gem.add_development_dependency('braid', '>= 0.5.0')
+    
+    # These are the dependencies for the vendored buildr (used for testing)
+    gem.add_development_dependency('rake', '= 0.8.4')
+    gem.add_development_dependency('net-ssh', '= 2.0.11')
+    gem.add_development_dependency('net-sftp', '= 2.0.2')
+    gem.add_development_dependency('highline', '= 1.5.0')
+    gem.add_development_dependency('hoe', '= 1.12.2')
+  end
+
+  Jeweler::RubyforgeTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+  # rcov can't tell that /Library/Ruby is a system path
+  spec.rcov_opts = ['--exclude', "spec/*,/Library/Ruby/*"]
+end
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "shenandoah #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+