teabag 0.5.4 → 0.5.5

data/README.md

@@ -37,6 +37,7 @@ If you'd like to use Teabag with [Guard](https://github.com/guard/guard), check
 8. [Support Libraries](#support-libraries)
 9. [CI Support](#ci-support)
 
+
 ## Installation
 
 Add it to your Gemfile. In most cases you'll want to restrict it to the `:asset`, or `:development, :test` groups.
@@ -59,6 +60,8 @@ You can tell the generator which framework you want to use, if you want coffeesc
 rails generate teabag:install --framework=mocha --coffee
 ```
 
+You can optionally [install phantomjs](http://phantomjs.org/download.html).  If phantomjs is found it will be used, otherwise the gem will be used as a fallback -- which might not be optimal.
+
 
 ## Usage
 
@@ -72,7 +75,7 @@ Here's a great [Quick Start Walkthrough](https://github.com/modeset/teabag/wiki/
 http://localhost:3000/teabag
 ```
 
-You can focus tests in various ways (and we might be providing an interface for this eventually). We already provide a way to switch suites, but to run a specific file you can specify the file(s) to focus to with `/teabag?file[]=file1.js&file[]=file2.js` or `/teabag?file=file1.js`. To specify a match for the test description you can use `/teabag?grep=Calculator should add two digits`
+You can focus tests in various ways, and Teabag provides an interface to run focus tests by suite, file, and filter.
 
 ### Rake
 
@@ -92,7 +95,7 @@ The CLI provides several ways of focusing tests. You can specify the suite to ru
 
 ```
 bundle exec teabag --suite=my_fantastic_suite
-bundle exec teabag spec/javascripts/file1.js
+bundle exec teabag spec/javascripts/calculator_spec.js
 bundle exec teabag --filter="Calculator should add two digits"
 ```
 
@@ -157,11 +160,11 @@ If you're using a specific framework and you want to take advantage of the thing
 
 ### Deferring Execution
 
-Teabag allows deferring execution in the cases when you're using AMD or other asynchronous libraries. This is especially useful if you're using [CommonJS](http://www.commonjs.org/) or [RequireJS](http://requirejs.org/), etc.  You can tell Teabag to defer and then execute the runner yourself later -- after loading asychronously.
+Teabag allows deferring execution in the cases when you're using AMD or other asynchronous libraries. This is especially useful if you're using [CommonJS](http://www.commonjs.org/) or [RequireJS](http://requirejs.org/), etc.  You can tell Teabag to defer and then execute the runner yourself later -- after loading asychronously. There's a wiki article about how you can setup your specs and spec helper when using [RequireJS with Teabag](https://github.com/modeset/teabag/wiki/RequireJS-with-Teabag).
 
 ```javascript
-Teabag.defer = true
-setTimeout(Teabag.execute, 1000) // defers execution for 1 second
+Teabag.defer = true;
+setTimeout(Teabag.execute, 1000); // defers execution for 1 second
 ```
 
 
@@ -253,128 +256,165 @@ end
 
 ### Suite Configuration Directives
 
-#### `matcher`
-
-You can specify a file matcher and all matching files will be loaded when the suite is run. It's important that these files are serve-able from sprockets.
-
-**Note:** Can also be set to `nil`.
+<dl>
 
-**default:** `"{spec/javascripts,app/assets}/**/*_spec.{js,js.coffee,coffee}"`
+<dt> matcher </dt><dd>
+  You can specify a file matcher and all matching files will be loaded when the suite is run. It's important that these files can be served via sprockets / are within an asset path.<br/><br/>
 
-#### `helper`
+  <b>Note:</b> Can also be set to <code>nil</code>.<br/><br/>
 
-Each suite can load a different spec helper, which can in turn require additional files. This file is loaded before your specs are loaded, and can be used as a manifest.
+  <b>default:</b> <code>"{spec/javascripts,app/assets}/**/*_spec.{js,js.coffee,coffee}"</code>
+</dd>
 
-**default:** `"spec_helper"`
+<dt> helper </dt><dd>
+  Each suite can load a different spec helper, which can in turn require additional files. This file is loaded before your specs are loaded, and can be used as a manifest.<br/><br/>
 
-#### `javascripts`
+  <b>default:</b> <code>"spec_helper"</code>
+</dd>
 
-These are the core Teabag javascripts. It's strongly encouraged to include only the base files here. You can require other support libraries in your spec helper, which allows you to change them without having to restart the server.
+<dt> javascripts </dt><dd>
+  These are the core Teabag javascripts. It's strongly encouraged to include only the base files here. You can require other support libraries in your spec helper, which allows you to change them without having to restart the server.<br/><br/>
 
-Available: teabag-jasmine, teabag-mocha, teabag-qunit
+  <b>Note:</b> To use the CoffeeScript source files use <code>"teabag/jasmine"</code> etc.<br/><br/>
 
-**Note:** To use the CoffeeScript source files use `"teabag/jasmine"` etc.
+  <b>available:</b> teabag-jasmine, teabag-mocha, teabag-qunit<br/>
+  <b>default:</b> <code>["teabag-jasmine"]</code>
+</dd>
 
-**default:** `["teabag-jasmine"]`
+<dt> stylesheets </dt><dd>
+  If you want to change how Teabag looks, or include your own stylesheets you can do that here. The default is the stylesheet for the HTML reporter.<br/><br/>
 
-#### `stylesheets`
+  <b>default:</b> <code>["teabag"]</code>
+</dd>
 
-If you want to change how Teabag looks, or include your own stylesheets you can do that here. The default is the stylesheet for the HTML reporter.
-
-**default:** `["teabag"]`
+</dl>
 
 
 ## Configuration
 
 The best way to read about the configuration options is to generate the initializer and env, but we've included the info here as well.
 
-**Note:** `Teabag.setup` may not be available in all environments. The generator provides a check wrapped around Teabag.setup.
-
-#### `mount_at`
+**Note:** `Teabag.setup` may not be available in all environments. The generator wraps it within a check.
 
-This determines where the Teabag routes will be mounted. Changing this to "/jasmine" would allow you to browse to http://localhost:3000/jasmine to run your specs.
+<dl>
 
-**default:** `"/teabag"`
+<dt> mount_at </dt><dd>
+  This determines where the Teabag routes will be mounted. Changing this to "/jasmine" would allow you to browse to http://localhost:3000/jasmine to run your specs.<br/><br/>
 
-#### `root`
+  <b>default:</b> <code>"/teabag"</code>
+</dd>
 
-This defaults to Rails.root if left nil. If you're testing an engine using a dummy application it can be useful to set this to your engines root.. E.g. `Teabag::Engine.root`
+<dt> root </dt><dd>
+  This defaults to Rails.root if left nil. If you're testing an engine using a dummy application it can be useful to set this to your engines root.. E.g. <code>Teabag::Engine.root</code><br/><br/>
 
-**default:** `nil`
+  <b>default:</b> <code>nil</code>
+</dd>
 
-#### `asset_paths`
+<dt> asset_paths </dt><dd>
+  These paths are appended to the Rails assets paths (relative to config.root), and by default is an array that you can replace or add to.<br/><br/>
 
-These paths are appended to the Rails assets paths (relative to config.root), and by default is an array that you can replace or add to.
+  <b>default:</b> <code>["spec/javascripts", "spec/javascripts/stylesheets", "test/javascripts", "test/javascripts/stylesheets"]</code>
+</dd>
 
-**default:** `["spec/javascripts", "spec/javascripts/stylesheets", "test/javascripts", "test/javascripts/stylesheets"]`
+<dt> fixture_path </dt><dd>
+  Fixtures are rendered through a standard controller. This means you can use things like HAML or RABL/JBuilder, etc. to generate fixtures within this path.<br/><br/>
 
-#### `fixture_path`
+  <b>default:</b> <code>"spec/javascripts/fixtures"</code>
+</dd>
 
-Fixtures are rendered through a standard controller. This means you can use things like HAML or RABL/JBuilder, etc. to generate fixtures within this path.
+</dl>
 
-**default:** `"spec/javascripts/fixtures"`
-
-### Console Runner Specific
+### Console Runner Specific (Teabag Env)
 
 These configuration directives are applicable only when running via the rake task or command line interface and should be set within the teabag_env.rb file. You can get this file by running the generator.
 
-#### `driver`
+<dl>
+
+<dt> driver </dt><dd>
+  Allows you to specify which driver to use when running headlessly. Supports <a href="http://phantomjs.org">PhantomJS</a> and <a href="http://seleniumhq.org/docs/03_webdriver.jsp">Selenium Webdriver</a>.<br/><br/>
 
-Allows you to specify which driver you want to run your specs with -- Supports [PhantomJS](http://phantomjs.org/) and [Selenium Webdriver](http://seleniumhq.org/docs/03_webdriver.jsp). Check this wiki article for information about [Using Selenium WebDriver](https://github.com/modeset/teabag/wiki/Using-Selenium-WebDriver), and this one about [Using PhantomJS](https://github.com/modeset/teabag/wiki/Using-PhantomJS).
+  Check this wiki article for information about <a href="https://github.com/modeset/teabag/wiki/Using-Selenium-WebDriver">Using Selenium WebDriver</a>, and this one about <a href="https://github.com/modeset/teabag/wiki/Using-PhantomJS">Using PhantomJS</a>.<br/><br/>
 
-Available: phantomjs, selenium
+  <b>available:</b> phantomjs, selenium<br/>
+  <b>default:</b> <code>"phantomjs"</code>
 
-- CLI: -d, --driver DRIVER
-- ENV: DRIVER=selenium
+  <ul>
+    <li>CLI: -d, --driver DRIVER</li>
+    <li>ENV: DRIVER=selenium</li>
+  </ul>
+</dd>
 
-**default:** `"phantomjs"`
 
-#### `server_timeout`
+<dt> server_timeout </dt><dd>
+  Timeout for starting the server in seconds. If your server is slow to start you may have to bump this, or you may want to lower this if you know it shouldn't take long to start.<br/><br/>
 
-Timeout for starting the server in seconds. If your server is slow to start you may have to bump this, or you may want to lower this if you know it shouldn't take long to start.
+  <b>default:</b> <code>20</code>
 
-- CLI: --server-timeout SECONDS
-- ENV: SERVER_TIMEOUT=10
+  <ul>
+    <li>CLI: --server-timeout SECONDS</li>
+    <li>ENV: SERVER_TIMEOUT=10</li>
+  </ul>
+</dd>
 
-**default:** `20`
 
-#### `fail_fast`
+<dt> server_port </dt><dd>
+  By default Teabag will locate an open port when starting the server, but if you want to run on a specific port you can do so by providing one.<br/><br/>
 
-If you have several suites it can be useful to make Teabag fail directly after any suite contains failures, but in environments like CI this may not be desirable.
+  <b>default:</b> <code>nil</code>
 
-- CLI: --[no-]fail-fast
-- ENV: FAIL_FAST=false
+  <ul>
+    <li>CLI: --server-port PORT</li>
+    <li>ENV: SERVER_PORT=31337</li>
+  </ul>
+</dd>
 
-**default:** `true`
 
-#### `formatters`
+<dt> fail_fast </dt><dd>
+  If you have several suites it can be useful to make Teabag fail directly after any suite contains failures, but in environments like CI this may not be desirable.<br/><br/>
 
-You can specify the formatters that Teabag will use when outputting the results.
+  <b>default:</b> <code>true</code>
 
-Supported formatters: dot, tap_y, swayze_or_oprah
+  <ul>
+    <li>CLI: --[no-]fail-fast</li>
+    <li>ENV: FAIL_FAST=false</li>
+  </ul>
+</dd>
 
-- CLI: -f, --format FORMATTERS
-- ENV: FORMATTERS=dot,swayze_or_oprah
+<dt> formatters </dt><dd>
+  You can specify the formatters that Teabag will use when outputting the results.<br/><br/>
 
-**default:** `"dot"`
+  <b>available:</b> dot, tap_y, swayze_or_oprah<br/>
+  <b>default:</b> <code>"dot"</code>
 
-#### `suppress_log`
+  <ul>
+    <li>CLI: -f, --format FORMATTERS</li>
+    <li>ENV: FORMATTERS=dot,swayze_or_oprah</li>
+  </ul>
+</dd>
 
-Teabag pipes all console[log/debug/error] calls to STDOUT. This is useful to catch places where you've forgotten to remove them, but in verbose applications this may not be desirable.
+<dt> suppress_log </dt><dd>
+  Teabag pipes all console[log/debug/error] calls to STDOUT. This is useful to catch places where you've forgotten to remove them, but in verbose applications this may not be desirable.<br/><br/>
 
-- CLI: -q, --[no-]suppress-log
-- ENV: SUPPRESS_LOG=true
+  <b>default:</b> <code>false</code>
 
-**default:** `false`
+  <ul>
+    <li>CLI: -q, --[no-]suppress-log</li>
+    <li>ENV: SUPPRESS_LOG=true</li>
+  </ul>
+</dd>
 
-#### `color`
+<dt> color </dt><dd>
+  Specify if you want color output by default.<br/><br/>
 
-Specify if you want color output by default.
+  <b>default:</b> <code>true</code>
 
-- CLI: --[no-]color
-- ENV: COLOR=false
+  <ul>
+    <li>CLI: --[no-]color</li>
+    <li>ENV: COLOR=false</li>
+  </ul>
+</dd>
 
-**default:** `true`
+</dl>
 
 
 ## Test Frameworks

data/app/assets/javascripts/teabag/base/reporters/html.coffee

@@ -38,8 +38,9 @@ class Teabag.Reporters.HTML extends Teabag.Reporters.BaseView
 
   buildLayout: ->
     el = @createEl("div")
-    document.body.appendChild(el)
+    el.id = "teabag-interface"
     el.innerHTML = Teabag.Reporters.HTML.template
+    document.body.appendChild(el)
 
 
   buildSuiteSelect: ->

data/app/assets/javascripts/teabag/base/reporters/html/template.coffee

@@ -1,41 +1,39 @@
 Teabag.Reporters.HTML.template = """
-<div id="teabag-interface">
-  <div class="teabag-clearfix">
-    <div id="teabag-title">
-      <h1>Teabag</h1>
-      <ul>
-        <li>version: <b id="teabag-version"></b></li>
-        <li id="teabag-env-info"></li>
-      </ul>
-    </div>
-    <div id="teabag-progress"></div>
-    <ul id="teabag-stats">
-      <li>passes: <b id="teabag-stats-passes">0</b></li>
-      <li>failures: <b id="teabag-stats-failures">0</b></li>
-      <li>skipped: <b id="teabag-stats-skipped">0</b></li>
-      <li>duration: <b id="teabag-stats-duration">&infin;</b></li>
+<div class="teabag-clearfix">
+  <div id="teabag-title">
+    <h1>Teabag</h1>
+    <ul>
+      <li>version: <b id="teabag-version"></b></li>
+      <li id="teabag-env-info"></li>
     </ul>
   </div>
+  <div id="teabag-progress"></div>
+  <ul id="teabag-stats">
+    <li>passes: <b id="teabag-stats-passes">0</b></li>
+    <li>failures: <b id="teabag-stats-failures">0</b></li>
+    <li>skipped: <b id="teabag-stats-skipped">0</b></li>
+    <li>duration: <b id="teabag-stats-duration">&infin;</b></li>
+  </ul>
+</div>
 
-  <div id="teabag-controls" class="teabag-clearfix">
-    <div id="teabag-toggles">
-      <button id="teabag-use-catch" title="Toggle using try/catch wrappers when possible">Try/Catch</button>
-      <button id="teabag-build-full-report" title="Toggle building the full report">Full Report</button>
-      <button id="teabag-display-progress" title="Toggle displaying progress as tests run">Progress</button>
-    </div>
-    <div id="teabag-suites"></div>
+<div id="teabag-controls" class="teabag-clearfix">
+  <div id="teabag-toggles">
+    <button id="teabag-use-catch" title="Toggle using try/catch wrappers when possible">Try/Catch</button>
+    <button id="teabag-build-full-report" title="Toggle building the full report">Full Report</button>
+    <button id="teabag-display-progress" title="Toggle displaying progress as tests run">Progress</button>
   </div>
+  <div id="teabag-suites"></div>
+</div>
 
-  <hr/>
+<hr/>
 
-  <div id="teabag-filter">
-    <h1>Filtering</h1>
-    <ul id="teabag-filter-list"></ul>
-  </div>
+<div id="teabag-filter">
+  <h1>Filtering</h1>
+  <ul id="teabag-filter-list"></ul>
+</div>
 
-  <div id="teabag-report">
-    <ol id="teabag-report-failures"></ol>
-    <ol id="teabag-report-all"></ol>
-  </div>
+<div id="teabag-report">
+  <ol id="teabag-report-failures"></ol>
+  <ol id="teabag-report-all"></ol>
 </div>
 """

data/lib/generators/teabag/install/templates/env.rb

@@ -15,10 +15,10 @@ require File.expand_path("../../config/environment", __FILE__)
 Teabag.setup do |config|
   # Driver
   #config.driver         = "phantomjs" # available: phantomjs, selenium
-  #config.phantomjs_bin  = nil
 
   # Behaviors
   #config.server_timeout = 20 # timeout for starting the server
+  #config.server_port    = nil # defaults to any open port unless specified
   #config.fail_fast      = true # abort after the first failing suite
 
   # Output

data/lib/teabag/command_line.rb

@@ -40,6 +40,10 @@ module Teabag
           @options[:server_timeout] = seconds
         end
 
+        parser.on("--server-port PORT", "Sets the server to use a specific port.") do |port|
+          @options[:server_port] = port
+        end
+
         parser.on("--[no-]fail-fast", "Abort after the first failing suite.") do |o|
           @options[:fail_fast] = o
         end

data/lib/teabag/configuration.rb

@@ -13,10 +13,10 @@ module Teabag
     @@suites         = {"default" => proc{}}
 
     # console runner specific
-    cattr_accessor :driver, :phantomjs_bin, :server_timeout, :fail_fast, :formatters, :suppress_log, :color
+    cattr_accessor :driver, :server_timeout, :server_port, :fail_fast, :formatters, :suppress_log, :color
     @@driver         = "phantomjs"
-    @@phantomjs_bin  = nil
     @@server_timeout = 20
+    @@server_port    = nil
     @@fail_fast      = true
     @@formatters     = "dot"
     @@suppress_log   = false
@@ -63,7 +63,7 @@ module Teabag
       next unless ENV[directive].present?
       @@configuration.send("#{directive.downcase}=", ENV[directive] == "true")
     end
-    %w(DRIVER FORMATTERS SERVER_TIMEOUT PHANTOMJS_BIN).each do |directive|
+    %w(DRIVER FORMATTERS SERVER_TIMEOUT SERVER_PORT).each do |directive|
       next unless ENV[directive].present?
       @@configuration.send("#{directive.downcase}=", ENV[directive])
     end

data/lib/teabag/console.rb

@@ -33,7 +33,10 @@ module Teabag
     end
 
     def run_specs(suite)
-      driver.run_specs(suite, url(suite))
+      url = url(suite)
+      url += url.include?("?") ? "&" : "?"
+      url += "reporter=Console"
+      driver.run_specs(suite, url)
     end
 
     protected

data/lib/teabag/drivers/phantomjs_driver.rb

@@ -1,14 +1,16 @@
 require "phantomjs"
 require "teabag/runner"
+require 'teabag/utility'
 
 module Teabag
   module Drivers
     class PhantomjsDriver < BaseDriver
+      include Teabag::Utility
 
       def run_specs(suite, url)
         runner = Teabag::Runner.new(suite)
 
-        Phantomjs.instance_variable_set(:@executable, Teabag.configuration.phantomjs_bin)
+        Phantomjs.instance_variable_set(:@executable, executable)
         Phantomjs.run(script, url) do |line|
           runner.process(line)
         end
@@ -18,6 +20,10 @@ module Teabag
 
       protected
 
+      def executable
+        @executable ||= which('phantomjs')
+      end
+
       def script
         File.expand_path("../phantomjs/runner.coffee", __FILE__)
       end