rails31-evergreen 0.4.1

data/README.rdoc

@@ -0,0 +1,193 @@
+= Evergreen
+
+"Because green is the new Blue(Ridge)"
+
+Evergreen is a tool to run javascript unit tests for client side JavaScript. It
+combines a server which allows you to serve up and run your specs in a browser,
+as well as a runner which uses Capybara and any of its drivers to run your
+specs. Evergreen uses the Jasmine unit testing framework for JavaScript.
+
+http://github.com/jnicklas/evergreen
+
+== Philosophy
+
+Evergreen is a unit testing tool. Its purpose is to test JavaScript in
+isolation from your application. If you need a tool that tests how your
+JavaScript integrates with your application you should use an integration
+testing framework, such as {Capybara}[http://github.com/jnicklas/capybara].
+
+== Installation
+
+Install as a Ruby gem:
+
+    gem install evergreen
+
+== Usage
+
+Evergreen assumes a file and directory structure, place all your javascript
+code inside ./public and all spec files inside ./spec/javascripts. All spec
+files should end in _spec.js. For example:
+
+    public/widget.js
+    spec/javascripts/widget_spec.js
+
+You can require files from the public directory inside your spec file:
+
+    require('/widget.js')
+
+    describe('a widget', function() {
+      ...
+    });
+
+You can now look at your spec files inside a browser by starting up the
+Evergreen server:
+
+    evergreen serve
+
+Alternatively you can run the specs headlessly by running:
+
+    evergreen run
+
+== Integrating with Rails 3
+
+Add Evergreen to your Gemfile:
+
+    gem 'evergreen', :require => 'evergreen/rails'
+
+Start your rails application and navigate to /evergreen. You should now see a
+list of all spec files, click on one to run it.
+
+There's a rake task provided for you that you can use to run your specs:
+
+    rake spec:javascripts
+
+== Integrating with Rails 2
+
+Add the following line to your Rakefile:
+
+    require 'evergreen/tasks'
+
+This will give you the `spec:javascripts` rake task. Note that mounting is not
+possible under Rails 2 and that `require 'evergreen/rails'` will fail.
+
+== Configuration
+
+By default, Evergreen uses Selenium to run your specs and assumes a certain
+directory structure. If this standard is fine for you, then you don't need to
+do anything else. If you need to configure Evergreen to suit your needs,
+Evergreen will automatically look for and load the following files:
+
+    config/evergreen.rb
+    .evergreen
+    ~/.evergreen
+
+The content of these files could look like this:
+
+    require 'capybara/envjs'
+
+    Evergreen.configure do |config|
+      config.driver = :envjs
+      config.public_dir = 'public_html'
+      config.template_dir = 'templates'
+      config.spec_dir = 'spec'
+    end
+
+== 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. Evergreen 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', function() {
+      it("should add stuff in one test...", function() {
+        $('#test').append('<h1 id="added">New Stuff</h1>');
+        expect($('#test h1#added').length).toEqual(1);
+      });
+
+      it("... should have been removed before the next starts", function() {
+        expect($('#test h1#added').length).toEqual(0);
+      });
+    });
+
+== Templates
+
+Even more powerful than that, Evergreen allows you to create HTML templates to
+go along with your specs. Put the templates in their own folder like this:
+
+    spec/javascripts/templates/one_template.html
+    spec/javascripts/templates/another_template.html
+
+You can then load the template into the test div, by calling the template
+function in your specs:
+
+    describe('transactions', function() {
+      template('one_template.html')
+
+      it("should load the template in this test", function() {
+        ...
+      });
+    });
+
+== Spec Helper
+
+If you add a spec_helper file like so:
+
+    spec/javascripts/spec_helper.js
+
+It will automatically be loaded. This is a great place for adding custom
+matchers and the like.
+
+== CoffeeScript
+
+Evergreen supports specs written in
+{CoffeeScript}[http://github.com/jashkenas/coffee-script]. Just name your spec
+file _spec.coffee and it will automatically be translated for you.
+
+You can also add a CoffeeScript spec helper, but remember that CoffeeScript
+encloses individual files in a closure, if you need something you define in the
+spec helper to be available in your spec files, attach it to the window object:
+
+    # spec/javascripts/spec_helper.coffee
+
+    MyThing: "foo"          # local to spec helper
+    window.MyThing: "foo"   # global
+
+== Development
+
+If you plan to work on Evergreen, you need to checkout the Jasmine gem, which
+is added as a git submodule. Run the following command:
+
+    git submodule update --init
+
+If you're using a version of Evergreen from git with bundler, you need to tell
+bundler to use submodules, this can be achieved with the following command:
+
+    gem 'evergreen', :submodules => true, :git => 'git://github.com/jnicklas/evergreen.git'
+
+== License:
+
+(The MIT License)
+
+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.

data/bin/evergreen

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+
+$:.unshift(File.dirname(__FILE__) + '/../lib') unless $:.include?(File.dirname(__FILE__) + '/../lib')
+
+require 'evergreen'
+
+begin
+  # The dup is to keep ARGV intact, so that tools like ruby-debug can respawn.
+  success = Evergreen::Cli.execute(ARGV.dup)
+  Kernel.exit(success ? 0 : 1)
+rescue SystemExit => e
+  Kernel.exit(e.status)
+rescue Exception => e
+  STDERR.puts("#{e.message} (#{e.class})")
+  STDERR.puts(e.backtrace.join("\n"))
+  Kernel.exit(1)
+end
+

data/config/routes.rb

@@ -0,0 +1,3 @@
+Rails.application.routes.draw do
+  mount Evergreen.rails, :at => '/evergreen'
+end

data/lib/evergreen.rb

@@ -0,0 +1,41 @@
+require 'rubygems'
+require 'sinatra/base'
+require 'capybara'
+require 'launchy'
+require 'evergreen/version'
+require 'evergreen/application'
+require 'json'
+
+module Evergreen
+  autoload :Cli, 'evergreen/cli'
+  autoload :Server, 'evergreen/server'
+  autoload :Runner, 'evergreen/runner'
+  autoload :Suite, 'evergreen/suite'
+  autoload :Spec, 'evergreen/spec'
+  autoload :Template, 'evergreen/template'
+  autoload :Reports, 'evergreen/reports'
+
+  class << self
+    attr_accessor :driver, :public_dir, :template_dir, :spec_dir
+
+    def configure
+      yield self
+    end
+
+    def extensions(&block)
+      @extensions = block if block
+      @extensions
+    end
+
+    def use_defaults!
+      configure do |config|
+        config.driver = :selenium
+        config.public_dir = 'public'
+        config.spec_dir = 'spec/javascripts'
+        config.template_dir = 'spec/javascripts/templates'
+      end
+    end
+  end
+end
+
+Evergreen.use_defaults!

data/lib/evergreen/application.rb

@@ -0,0 +1,43 @@
+module Evergreen
+  def self.application(suite)
+    Rack::Builder.new do
+      instance_eval(&Evergreen.extensions) if Evergreen.extensions
+
+      map "/resources" do
+        use Rack::Static, :urls => ["/"], :root => File.expand_path('resources', File.dirname(__FILE__))
+        run lambda { |env| [404, {}, "No such file"]}
+      end
+
+      map "/" do
+        app = Class.new(Sinatra::Base).tap do |app|
+          app.reset!
+          app.class_eval do
+            set :static, true
+            set :root, File.expand_path('.', File.dirname(__FILE__))
+            set :public, File.expand_path(File.join(suite.root, Evergreen.public_dir), File.dirname(__FILE__))
+
+            helpers do
+              def url(path)
+                request.env['SCRIPT_NAME'].to_s + path.to_s
+              end
+            end
+
+            get '/' do
+              @suite = suite
+              erb :list
+            end
+
+            get '/run/*' do |name|
+              @suite = suite
+              @spec = suite.get_spec(name)
+              @js_spec_helper = suite.get_spec('spec_helper.js')
+              @coffee_spec_helper = suite.get_spec('spec_helper.coffee')
+              erb :spec
+            end
+          end
+        end
+        run app
+      end
+    end
+  end
+end

data/lib/evergreen/cli.rb

@@ -0,0 +1,23 @@
+module Evergreen
+  class Cli
+    def self.execute(argv)
+      new.execute(argv)
+    end
+
+    def execute(argv)
+      command = argv.shift
+      root    = File.expand_path(argv.shift || '.', Dir.pwd)
+
+      case command
+      when "serve"
+        Evergreen::Suite.new(root).serve
+        return true
+      when "run"
+        return Evergreen::Suite.new(root).run
+      else
+        puts "no such command '#{command}'"
+        return false
+      end
+    end
+  end
+end

data/lib/evergreen/rails.rb

@@ -0,0 +1,12 @@
+require 'evergreen'
+require 'rails'
+
+module Evergreen
+  def self.rails
+    Evergreen::Suite.new(Rails.root).application
+  end
+
+  class Railtie < Rails::Engine
+  end
+end
+

data/lib/evergreen/reports.rb

@@ -0,0 +1,79 @@
+require 'builder'
+
+# generates reports in junit xml for ci/jenkins
+module Evergreen
+  module Reports
+    def self.filename(spec_result, index)
+      File.join(dir, "#{spec_result[:name]}.#{index}.xml")
+    end
+    
+    def self.dir
+      ENV['CI_REPORTS'] || File.expand_path("#{Dir.getwd}/reports")
+    end
+    
+    def self.collect_data(suite)
+      # open new reporter
+      runners = suite.runner.instance_eval('spec_runners')
+      result_data = runners.map do |specrunner|
+        {
+          :name => specrunner.spec.name,
+          :passed => specrunner.spec.passed?,
+          :results => specrunner.examples.map { |r|
+            row = r.instance_variable_get("@row")
+            hash = {}
+            row.each {|k,v| hash[k] = v}
+            hash
+          }
+        }
+      end
+    end
+    
+    def self.find_filename(spec_result)
+      index = 0
+      while File.exists?(filename(spec_result, index))
+        index = index + 1
+      end
+      filename(spec_result, index)
+    end
+    
+    def self.publish_spec(spec_result)
+      File.open(find_filename(spec_result), "w") do |f|
+        builder = Builder::XmlMarkup.new(:target => f, :indent => 2, :escape_attrs => true)    
+        builder.instruct!
+
+        tests = 0
+        failures = 0
+        spec_result[:results].each do |result|
+          tests = tests + 1
+          failures = failures + 1 unless result['passed']
+        end
+        
+        builder.testsuite({:name => spec_result[:name], :tests => tests, :failures => failures}) do
+          spec_result[:results].each do |result|
+            builder.testcase({'name' => "#{spec_result[:name]} - #{result['name']}"}) do
+              unless result['passed']
+                builder.failure(:message => result['message']) do
+                  builder.text!('Failed: '+result['name']+' '+result['message'])
+                  if result['trace']
+                    builder.text!(" -> in #{result['trace']['fileName']}:#{result['trace']['lineNumber']}")
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+    
+    def self.publish!(suite)
+      result_data = collect_data(suite)
+      
+      FileUtils.rm_rf(dir)
+      FileUtils.mkdir_p(dir)
+      
+      result_data.each do |spec_result|
+        publish_spec(spec_result)
+      end
+    end
+  end
+end

data/lib/evergreen/resources/evergreen.css

@@ -0,0 +1,64 @@
+body {
+  font-family: 'Lucida grande', 'sans-serif';
+  background: #f0f0f0;
+}
+
+a {
+  color: #00A500;
+}
+
+#page, #test, .jasmine_reporter {
+  width: 800px;
+  background: white;
+  -moz-border-radius: 3px;
+  padding: 20px;
+  margin: 50px auto 30px;
+  border: 1px solid #ddd
+}
+
+#test {
+  min-height: 50px;
+  max-height: 300px;
+  overflow: auto;
+  margin: 30px auto 30px;
+}
+
+.jasmine_reporter {
+  margin: 30px auto 30px;
+}
+
+#page h1 {
+  font-size: 24px;
+  margin: 0 0 15px;
+}
+
+#page a.back {
+  font-size: 12px;
+}
+
+#page ul {
+  margin: 0;
+  padding: 0;
+}
+
+#page ul li {
+  list-style: none;
+  border: 1px solid #ddd;
+  -moz-border-radius: 3px;
+  margin: 10px 0;
+  background: #f5f5f5;
+}
+
+#page ul li a {
+  padding: 7px 10px;
+  display: block;
+  text-decoration: none;
+}
+
+#footer {
+  margin: 0 auto 30px;
+  width: 600px;
+  text-align: center;
+  font-size: 13px;
+  color: #aaa;
+}