matcha 0.9.0

data/.gitignore

@@ -0,0 +1,19 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+node_modules
+spec/dummy/log

data/Gemfile

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+gemspec
+
+# This is a runtime dependency in the gemspec, so it shouldn't be necessary to
+# specify it again, but bundler is buggy:
+#  https://github.com/carlhuda/bundler/issues/1041
+gem "jquery-rails"

data/LICENSE

@@ -0,0 +1,90 @@
+Copyright (c) 2012 John Firebaugh
+
+MIT License
+
+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.
+
+Portions derived from Evergreen (https://github.com/jnicklas/evergreen):
+
+Copyright (c) 2009 Jonas Nicklas
+
+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.
+
+Portions derived from Mocha (https://github.com/visionmedia/mocha)
+
+Copyright (c) 20011-2012 TJ Holowaychuk <tj@vision-media.ca>
+
+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.
+
+Portions derived from Chai (https://github.com/logicalparadox/chai)
+
+Copyright (c) 2011 Jake Luer <jake@alogicalparadox.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.

data/README.md

@@ -0,0 +1,194 @@
+# Matcha
+
+Matcha is a Rails engine that allows you to test your JavaScript with the
+[mocha](http://visionmedia.github.com/mocha/) test framework and [chai](http://chaijs.com/)
+assertion library.
+
+It is similar to [Jasmine](https://github.com/pivotal/jasmine-gem) and
+[Evergreen](https://github.com/jnicklas/evergreen), but does not attempt to be framework
+agnostic. By sticking with Rails, Matcha can take full advantage of features such as
+the asset pipeline and engines.
+
+## Installation
+
+Add matcha to the `:test` and `:development` groups in the Gemfile:
+
+    group :test, :development do
+      gem "matcha"
+    end
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install matcha
+
+## Usage
+
+Create a `spec/javascripts` directory and name the files in it with a `_spec` suffix.
+You can write the specs in either JavaScript or CoffeeScript, using a `.js` or
+`.js.coffee` extension respectively, like you would any other script asset.
+
+Require the assets under test and any other dependencies using Sprockets directives.
+For example, suppose you wanted to test your cool JavaScript `Array#sum` method, which
+you placed in `app/assets/javascripts/array_sum.js`. Write the specs in JavaScript in
+the file `spec/javascripts/array_sum_spec.js`:
+
+    //= require array_sum
+
+    describe("Array#sum", function(){
+      it("returns 0 when the Array is empty", function(){
+        [].sum().should.equal(0);
+      });
+
+      it("returns the sum of numeric elements", function(){
+        [1,2,3].sum().should.equal(6);
+      });
+    });
+
+Or, if you prefer CoffeeScript, in `spec/javascripts/array_sum_spec.js.coffee`:
+
+    #= require array_sum
+
+    describe "Array#sum", ->
+      it "returns 0 when the Array is empty", ->
+        [].sum().should.equal(0)
+
+      it "returns the sum of numeric elements", ->
+        [1,2,3].sum().should.equal(6)
+
+The `matcha:server` rake task starts a server for your tests. You can go to the root
+page to run all specs (e.g. `http://localhost:8888/`), or a sub page to run an individual
+spec file (e.g. `http://localhost:8888/array_sum_spec`).
+
+Alternatively, you can run the specs headlessly with the `matcha:ci` task.
+
+## Spec Helper
+
+Since Matcha integrates with the asset pipeline, using setup helpers in your specs is
+easy. Just create a `spec_helper.js` or `spec_helper.js.coffee` file in `specs/javascripts`
+and require it in your tests:
+
+    //= require spec_helper
+    //= require array_sum
+
+    describe("Array#sum", function(){
+      ...
+    });
+
+## Directives and Asset Bundling
+
+We suggest that you explicitly require just the assets necessary for each spec. In CI
+mode, Matcha will run each spec in isolation, and requiring things explicitly will help
+ensure your scripts don't accumulate hidden dependencies and tight coupling.
+
+However, you are free to ignore this advice and require the entire application.js asset
+bundle in your specs or spec helper, or a bundled subset of assets. Requiring bundled
+assets works like it does in Rails development mode -- Matcha will detect the complete
+set of dependencies and generate a separate script tag for each one. You won't have to
+search through a many thousand line application.js bundle to debug a spec failure.
+
+## Configuration
+
+Matcha can be configured in an initializer, e.g. `config/initializers/matcha.rb`:
+
+    Matcha.configure do |config|
+      config.spec_dir  = "spec/javascripts"
+      config.interface = :bdd
+      config.driver    = :selenium
+    end if defined?(Matcha)
+
+The `defined?` check is necessary to avoid a dependency on Matcha in the production
+environment.
+
+The `spec_dir` option tells Matcha where to find JavaScript specs. The `interface`
+option specifies the test interface used by Mocha (see below). `driver` names a
+Capybara driver used for the CI task (try `:webkit`, after installing
+[capybara-webkit](https://github.com/thoughtbot/capybara-webkit)).
+
+The values above are the defaults.
+
+## Test Interface and Assertions
+
+Matcha includes a vendored copy of mocha.js and the [chai](http://chaijs.com/)
+assertion libraries.
+
+By default, it will assume that you want to use Mocha's "BDD" test interface, which
+provides `describe()`, `it()`, `before()`, `after()`, `beforeEach()`, and `afterEach()`.
+If you want to use the TDD, Exports, or QUnit interfaces instead, set the `interface`
+configuration option in an initializer:
+
+    Matcha.configure do |config|
+      config.interface = :tdd # Or :exports or :qunit
+    end if defined?(Matcha)
+
+Matcha will make all three of chai's assertion styles available to you: `expect`,
+`should`, and `assert`. See the chai documentation for the details.
+
+If you use jQuery, you may want to check out [chai-jquery](https://github.com/jfirebaugh/chai-jquery)
+for some jQuery-specific assertions.
+
+## Transactions
+
+One problem often faced when writing unit tests for client side code is that changes
+to the page are not reverted for the next example, so that successive examples become
+dependent on each other. Matcha adds a special div to your page with an id of `test`.
+This div is automatically emptied before each example. You should avoid appending markup
+to the page body and instead append it to this test div:
+
+    describe "transactions", ->
+      it "should add stuff in one test...", ->
+        $('#test').append('<h1 id="added">New Stuff</h1>')
+        $('#test h1#added').length.should.equal(1)
+
+      it "... should have been removed before the next starts", ->
+        $('#test h1#added').length.should.equal(0)
+
+Note: this functionality is available only for the "BDD" (default) and "TDD" mocha interfaces,
+and not for the "exports" or "QUnit" interfaces.
+
+## Templates / Fixtures
+
+Matcha has no template (a.k.a. HTML fixture) support of its own. Instead, we suggest you use
+Sprocket's built in support for JavaScript template (`.jst`) files. Add a `spec/javascripts/templates`
+directory, place template files there (using any JS template language supported by Sprockets),
+require them in your spec or spec_helper, and render them into the `#test` div.
+
+For example, in `spec/javascripts/templates/hello.jst.ejs`:
+
+    <h1>Hello Matcha!</h1>
+
+In `spec_helper.js`:
+
+    //= require_tree ./templates
+
+And your spec:
+
+    //= require spec_helper
+
+    describe("templating", function(){
+      it("is built in to Sprockets", function(){
+        $('#test').html(JST['templates/hello']());
+        $('#test h1').text().should.equal('Hello Matcha!');
+      });
+    });
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## License
+
+Copyright (c) 2012 John Firebaugh
+
+MIT License (see the LICENSE file)
+
+Portions: Copyright (c) 2009 Jonas Nicklas, Copyright (c) 20011-2012 TJ Holowaychuk
+<tj@vision-media.ca>, Copyright (c) 2011 Jake Luer <jake@alogicalparadox.com>. See
+LICENSE file for details.

data/Rakefile

@@ -0,0 +1,8 @@
+#!/usr/bin/env rake
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new :spec
+
+task :default => :spec

data/app/controllers/matcha/specs_controller.rb

@@ -0,0 +1,22 @@
+module Matcha
+  class SpecsController < ActionController::Base
+    before_filter :set_interface, :set_mode
+
+    def set_interface
+      @interface = Matcha.interface
+    end
+
+    def set_mode
+      @mode = Matcha.mode
+    end
+
+    def index
+      @specs = Matcha::Spec.all
+    end
+
+    def show
+      @spec = Matcha::Spec.find(params[:spec])
+      @spec or render :text => "Not Found", :status => 404
+    end
+  end
+end

data/app/models/matcha/spec.rb

@@ -0,0 +1,25 @@
+module Matcha
+  class Spec
+    def self.all
+      Matcha.spec_paths.map { |path| new(path) }
+    end
+
+    def self.find(basename)
+      all.find { |spec| spec.basename == basename }
+    end
+
+    attr_accessor :path
+
+    def initialize(path)
+      @path = path
+    end
+
+    def url
+      "/#{basename}"
+    end
+
+    def basename
+      path[/.*(?=\.js.*$)/]
+    end
+  end
+end

data/app/views/layouts/matcha/specs.html.erb

@@ -0,0 +1,31 @@
+<!doctype html>
+<html>
+  <head>
+    <meta http-equiv="content-type" content="text/html;charset=utf-8" />
+    <title>Mocha Tests</title>
+    <%= stylesheet_link_tag "mocha" %>
+    <%= javascript_include_tag "jquery", "mocha", "chai", "matcha/#{@mode}" %>
+    <script>
+      mocha.setup(<%= raw @interface.to_json %>);
+      var expect = chai.expect,
+          should = chai.should(),
+          assert = chai.assert;
+      window.onload = mocha.run;
+
+      <% if @interface == :bdd %>
+        beforeEach(function() {
+          document.getElementById('test').innerHTML = "";
+        });
+      <% elsif @interface == :tdd %>
+        setup(function() {
+          document.getElementById('test').innerHTML = "";
+        });
+      <% end %>
+    </script>
+    <%= yield %>
+  </head>
+  <body>
+    <div id="mocha"></div>
+    <div id="test"></div>
+  </body>
+</html>

data/app/views/matcha/specs/index.html.erb

@@ -0,0 +1 @@
+<%= javascript_include_tag *@specs.map(&:basename) %>

data/app/views/matcha/specs/show.html.erb

@@ -0,0 +1 @@
+<%= javascript_include_tag @spec.basename %>

data/config/routes.rb

@@ -0,0 +1,4 @@
+Matcha::Engine.routes.draw do
+  match "/"      => "matcha/specs#index"
+  match "/*spec" => "matcha/specs#show"
+end

data/lib/matcha.rb

@@ -0,0 +1,41 @@
+require "matcha/engine"
+require "matcha/runner"
+require "matcha/server"
+
+module Matcha
+  class << self
+    attr_accessor :mode
+
+    def serve
+      puts "your tests are here:"
+      puts "  http://localhost:#{port}/"
+      self.mode = :server
+      Matcha::Server.start
+    end
+
+    def run
+      self.mode = :runner
+      Matcha::Runner.start
+    end
+
+    def config
+      Matcha::Engine.config.matcha
+    end
+
+    def configure
+      yield config
+    end
+
+    delegate :port, :spec_dir, :interface, :application, :driver, :to => :config
+
+    def spec_root
+      File.join(Rails.root, config.spec_dir)
+    end
+
+    def spec_paths
+      Dir[File.join(spec_root, "**/*_spec.*")].map do |path|
+        path.gsub(File.join(spec_root, ''), '')
+      end
+    end
+  end
+end