guard-jasmine 0.9.14 → 1.0.0

data/README.md

@@ -7,6 +7,36 @@ Tested on MRI Ruby 1.8.7, 1.9.2, 1.9.3, REE and the latest versions of JRuby and
 If you have any questions please join us on our [Google group](http://groups.google.com/group/guard-dev) or on `#guard`
 (irc.freenode.net).
 
+## Contents
+
+* [Highlights](#highlights)
+* [Installation](#installation)
+  * [Guard and Guard::Jasmine](#guard-guard-jasmine)
+  * [PhantomJS](#phantomjs)
+* [Rails 3.1 setup](#rails31)
+  * [How it works](#rails31-works)
+  * [Jasminerice](#rails31-jasminerice)
+* [Rails 2 & Rails 3 setup](#rails23)
+  * [How it works](#rails23-works)
+  * [Jasmine Gem](#rails23-jasmine-gem)
+* [Usage](#usage)
+  * [Guardfile](#guardfile)
+* [Options](#options)
+  * [Server options](#server-options)
+    * [Use a custom server](#server-options-custom)
+  * [Spec runner options](#spec-runner-options)
+  * [Specdoc options](#specdoc-options)
+    * [Console logs](#console-logs)
+  * [System notifications options](#system-notifications-options)
+* [Mapping file changes to the spec filter](#file-mapping)
+* [Guard::Jasmine outside of Guard](#outside-guard)
+  * [Thor command line utility](#thor)
+  * [Rake task integration](#rake)
+  * [Travis CI integration](#travis-ci)
+* [How to file an issue](#issues)
+* [Development information](#development-information)
+
+<a name="highlights" />
 ## Highlights
 
 * Continuous testing based on file modifications by [Guard][], manifold configuration by writing rules with RegExp and
@@ -22,8 +52,10 @@ various web standards: DOM handling, CSS selector, JSON, Canvas, and SVG.
 
 * Runs on Mac OS X, Linux and Windows.
 
-## Install
+<a name="installation" />
+## Installation
 
+<a name="guard-guard-jasmine" />
 ### Guard and Guard::Jasmine
 
 The simplest way to install Guard is to use [Bundler](http://gembundler.com/).
@@ -43,6 +75,7 @@ Add the default Guard::Jasmine template to your `Guardfile` by running:
 $ guard init jasmine
 ```
 
+<a name="phantomjs" />
 ### PhantomJS
 
 You need the PhantomJS browser installed on your system. You can download binaries for Mac OS X and Windows from
@@ -65,6 +98,7 @@ $ sudo apt-get install phantomjs
 You can also build it from source for several other operating systems, please consult the
 [PhantomJS build instructions][].
 
+<a name="rails31" />
 ## Rails 3.1 setup
 
 With Rails 3.1 you can write your Jasmine specs in addition to JavaScript with CoffeeScript, fully integrated into the
@@ -73,6 +107,7 @@ to fake the server response. Check out the excellent [Sinon.JS][] documentation
 
 Guard::Jasmine will start a Rails Rack server to run your specs.
 
+<a name="rails31-works" />
 ### How it works
 
 ![Guard Jasmine](https://github.com/netzpirat/guard-jasmine/raw/master/resources/guard-jasmine-rails31.jpg)
@@ -88,6 +123,7 @@ Guard::Jasmine will start a Rails Rack server to run your specs.
 9. The PhantomJS script collects the Jasmine runner results and returns a JSON report.
 10. Guard::Jasmine reports the results to the console and system notifications.
 
+<a name="rails31-jasminerice" />
 ### Jasminerice
 
 Please read the detailed installation and configuration instructions at [Jasminerice][].
@@ -120,6 +156,7 @@ It also creates an empty `spec/javascripts/spec.css` file as it is always reques
 
 Now you can access `/jasmine` url when you start rails server normally.
 
+<a name="rails23" />
 ## Rails 2 & Rails 3 setup
 
 With Rails 2 or Rails 3 you can use [the Jasmine Gem][] to configure your Jasmine specs and server the Jasmine
@@ -128,6 +165,7 @@ response. Check out the excellent [Sinon.JS][] documentation to learn more about
 
 Guard::Jasmine will start a Jasmine Gem Rack server to run your specs.
 
+<a name="rails23-works" />
 ### How it works
 
 ![Guard Jasmine](https://github.com/netzpirat/guard-jasmine/raw/master/resources/guard-jasmine-rails23.jpg)
@@ -141,6 +179,7 @@ Guard::Jasmine will start a Jasmine Gem Rack server to run your specs.
 7. The PhantomJS script collects the Jasmine runner results and returns a JSON report.
 8. Guard::Jasmine reports the results to the console and system notifications.
 
+<a name="rails23-jasmine-gem" />
 ### Jasmine Gem
 
 Please read the detailed installation and configuration instructions at [the Jasmine Gem][].
@@ -179,10 +218,12 @@ guard 'coffeescript', :input => 'app/coffeescripts',  :output => 'public/javascr
 guard 'coffeescript', :input => 'spec/coffeescripts', :output => 'spec/javascripts'
 ```
 
+<a name="usage" />
 ## Usage
 
 Please read the [Guard usage documentation](https://github.com/guard/guard#readme).
 
+<a name="guardfile" />
 ## Guardfile
 
 Guard::Jasmine can be adapted to all kind of projects. Please read the
@@ -196,6 +237,7 @@ guard 'jasmine' do
 end
 ```
 
+<a name="options" />
 ## Options
 
 There are many options that can customize Guard::Jasmine to your needs. Options are simply supplied as hash when
@@ -207,6 +249,7 @@ guard 'jasmine', :all_on_start => false, :specdoc => :always do
 end
 ```
 
+<a name="server-options" />
 ### Server options
 
 The server options configures the server environment that is needed to run Guard::Jasmine:
@@ -244,6 +287,7 @@ The reason why the Server environment is set to `development` by default is that
 the asset pipeline doesn't concatenate the JavaScripts and you'll see the line number in the real file,
 instead of a ridiculous high line number in a single, very large JavaScript.
 
+<a name="server-options-custom" />
 #### Use a custom server
 
 If you supply an unknown server name as the `:server` option, then Guard::Jasmine will execute
@@ -252,6 +296,7 @@ a `rake` task with the given server name as task in a child process. For example
 you have to make sure the server starts on the port that you can get from the `JASMINE_PORT`
 environment variable.
 
+<a name="spec-runner-options" />
 ### Spec runner options
 
 The spec runner options configures the behavior driven development (or BDD) cycle:
@@ -285,6 +330,7 @@ In general you want to leave the `:clean` flag on, which ensures that only Jasmi
 `_spec.coffee` and `_spec.js.coffee` inside your project are passed to the runner. If you have a custom project
 structure or spec naming convention, you can set `:clean` to false to skip that file filter.
 
+<a name="specdoc-options" />
 ### Specdoc options
 
 Guard::Jasmine can generate an RSpec like specdoc in the console after running the specs and you can set when it will
@@ -310,26 +356,35 @@ set to `:never`, there is no output at all, instead just a summary of the spec r
 
 When `:focus` is enabled, only the failing specs are shown in the specdoc when at least one spec is failing.
 
-The `:console` options adds captured console logs from the spec runner and adds them to the specdoc. Please note
-that PhantomJS only support capturing of `console.log`, so the other log functions like `debug`, `warn`, `info` and
-`error` are missing. Please vote on [Issue 232](http://code.google.com/p/phantomjs/issues/detail?id=232) if you like
-to see support for more console methods coming to PhantomJS.
+<a name="console-logs" />
+#### Console logs
 
-Another restriction on console logging is that currently only the first log parameter is passed. So instead of writing
+The `:console` options adds captured console logs from the spec runner and adds them to the specdoc. Guard:Jasmine
+contains its own minimalistic console implementation. The following console methods are supported:
 
-```javascript
-console.log('Debug of %o with %s', object, string)
-```
+* `console.log`
+* `console.info`
+* `console.warn`
+* `console.error`
+* `console.debug`
 
-your should write
+The difference for each of this log methods is simply a prefix that is added to the log statement. The log also
+supports the common format placeholders:
 
-```javascript
-console.log('Debug of ' + object.toString() + ' width ' + string)
-```
+* `%s`
+* `%i`, `%d`
+* `%f`
+* `%o`
+
+You can further customize the log output by implement on of these methods:
+
+* `toString()` - must return a string that describes the object
+* `toJSON()` - must return an object that is used instead of the actual object.
 
-You can also give your vote on [Issue 36](http://code.google.com/p/phantomjs/issues/detail?id=36) to see support for
-multiple console arguments.
+In addition the console can log jQuery collections and outputs the HTML representation of the element by using the
+jQuery `html()` method.
 
+<a name="system-notifications-options" />
 ### System notifications options
 
 These options affects what system notifications (growl, libnotify or notifu) are shown after a spec run:
@@ -345,6 +400,7 @@ These options affects what system notifications (growl, libnotify or notifu) are
                                               # default: 3
 ```
 
+<a name="file-mapping" />
 ## Mapping file changes to the spec filter
 
 Jasmine doesn't know anything about your test files, it only knows the name of your specs that you specify in the
@@ -359,8 +415,10 @@ So if you want to have a precise spec detection, you should:
 To get a feeling how your naming strategy works, play with the web based Jasmine runner and modify the `spec` query
 parameter.
 
+<a name="outside-guard" />
 ## Guard::Jasmine outside of Guard
 
+<a name="thor" />
 ### Thor command line utility
 
 Guard::Jasmine includes a little command line utility to run your specs once and output the specdoc to the console.
@@ -405,6 +463,7 @@ By default all specs are run, but you can supply multiple paths to your specs to
 $ guard-jasmine spec/javascripts/a_spec.js.coffee spec/javascripts/another_spec.js.coffee
 ```
 
+<a name="rake" />
 ### Rake task integration
 
 Guard::Jasmine provides a Rake task wrapper around the Thor command line utility. Simply create a JasmineTask within
@@ -427,6 +486,7 @@ end
 Guard::JasmineTask.new(:jasmine_no_server, '-s none')
 ```
 
+<a name="travis-ci" />
 ### Travis CI integration
 
 With the given `guard-jasmine` script you're able to configure [Travis CI](http://travis-ci.org/) to run Guard::Jasmine.
@@ -466,7 +526,8 @@ I recommend to check out these other brilliant Jasmine runners:
 * [Jezebel][] a Node.js REPL and continuous test runner for [Jessie][], a Node runner for Jasmine, but has no full
 featured browser environment.
 
-## Issues
+<a name="issues" />
+## How to file an issue
 
 You can report issues and feature requests to [GitHub Issues](https://github.com/netzpirat/guard-jasmine/issues). Try to figure out
 where the issue belongs to: Is it an issue with Guard itself or with Guard::Jasmine? Please don't
@@ -475,12 +536,14 @@ ask question in the issue tracker, instead join us in our [Google group](http://
 
 When you file an issue, please try to follow to these simple rules if applicable:
 
+* Make sure you have study the README carefully.
 * Make sure you run Guard with `bundle exec` first.
 * Add debug information to the issue by running Guard with the `--verbose` option.
 * Add your `Guardfile` and `Gemfile` to the issue.
 * Make sure that the issue is reproducible with your description.
 
-## Development
+<a name="development-information" />
+## Development information
 
 - Documentation hosted at [RubyDoc](http://rubydoc.info/github/guard/guard-jasmine/master/frames).
 - Source hosted at [GitHub](https://github.com/netzpirat/guard-jasmine).
@@ -513,6 +576,14 @@ The only argument that the script takes is the URL to the Jasmine runner, which
 ```bash
 $ guard-jasmine-debug http://127.0.0.1:3000/Jasmine?spec=YourSpec
 ```
+
+## Author
+
+Developed by Michael Kessler, sponsored by [mksoft.ch](https://mksoft.ch).
+
+If you like Guard::Jasmine, you can watch the repository at [GitHub](https://github.com/netzpirat/guard-jasmine) and
+follow [@netzpirat](https://twitter.com/#!/netzpirat) on Twitter for project updates.
+
 ## Contributors
 
 See the the GitHub list of [contributors](https://github.com/netzpirat/haml_coffee_assets/contributors).
@@ -574,7 +645,7 @@ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 [guard-jasmine-headless-webkit]: https://github.com/johnbintz/guard-jasmine-headless-webkit
 [jasmine-headless-webkit]: https://github.com/johnbintz/jasmine-headless-webkit/
 [Evergreen]: https://github.com/jnicklas/evergreen
-[PhantomJS script]: https://github.com/netzpirat/guard-jasmine/blob/master/lib/guard/jasmine/phantomjs/run-jasmine.coffee
+[PhantomJS script]: https://github.com/netzpirat/guard-jasmine/blob/master/lib/guard/jasmine/phantomjs/guard-jasmine.coffee
 [Guard::CoffeeScript]: https://github.com/guard/guard-coffeescript
 [Sinon.JS]: http://sinonjs.org
 [guard-jasmine-node]: https://github.com/guard/guard-jasmine-node

data/bin/guard-jasmine-debug

@@ -1,3 +1,3 @@
 #!/usr/bin/env ruby
-script = File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib', 'guard', 'jasmine', 'phantomjs', 'run-jasmine.coffee'))
+script = File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib', 'guard', 'jasmine', 'phantomjs', 'guard-jasmine.coffee'))
 puts `phantomjs #{ script } #{ ARGV[0] } #{ ARGV[1] }`

data/lib/guard/jasmine/phantomjs/guard-jasmine.coffee

@@ -0,0 +1,115 @@
+# This file is the script that runs within PhantomJS, requests the Jasmine specs
+# and waits until they are ready.
+
+# Set default values
+url = phantom.args[0] || 'http://127.0.0.1:3000/jasmine'
+timeout = parseInt(phantom.args[1] || 5000)
+
+# Create the web page.
+#
+page = require('webpage').create()
+
+# Used to collect log messages for later assignment to the spec
+#
+currentSpecId = -1
+logs = {}
+
+# Add logs to the given suite
+#
+# @param suite [Object} the suite result
+#
+page.addLogs = (suite) ->
+  for s in suite.suites
+    arguments.callee(s) if s
+
+  for spec in suite.specs
+    id = Number(spec['id'])
+    spec['logs'] = logs[id] if logs[id] && logs[id].length isnt 0
+    delete spec['id']
+
+  delete suite['id']
+  delete suite['parent']
+
+# Capture console.log output to add it to
+# the result when specs have finished.
+#
+page.onConsoleMessage = (msg, line, source) ->
+  if /^RUNNER_RESULT: ([\s\S]*)$/.test(msg)
+    result = JSON.parse(RegExp.$1)
+
+    for suite in result.suites
+      page.addLogs(suite)
+
+    console.log JSON.stringify(result, undefined, 2)
+    page.evaluate -> window.resultReceived = true
+
+  else if /^SPEC_START: (\d+)$/.test(msg)
+    currentSpecId = Number(RegExp.$1)
+    logs[currentSpecId] = []
+
+  else
+    logs[currentSpecId].push(msg) if currentSpecId isnt -1
+
+# Initialize the page before the JavaScript is run.
+#
+page.onInitialized = ->
+  page.injectJs 'lib/console.js'
+  page.injectJs 'lib/reporter.js'
+
+  page.evaluate ->
+    # Attach the console reporter when the document is ready.
+    window.onload = ->
+      window.resultReceived = false
+      jasmine.getEnv().addReporter(new ConsoleReporter())
+
+# Open web page and run the Jasmine test runner
+#
+page.open url, (status) ->
+  # Avoid that a failed iframe load breaks the runner, see https://github.com/netzpirat/guard-jasmine/pull/19
+  page.onLoadFinished = ->
+
+  if status isnt 'success'
+    console.log JSON.stringify({ error: "Unable to access Jasmine specs at #{ url }" })
+    phantom.exit()
+  else
+    done = -> phantom.exit()
+    waitFor specsReady, done, timeout
+
+# Test if the specs have finished.
+#
+specsReady = ->
+  page.evaluate -> window.resultReceived
+
+# Wait until the test condition is true or a timeout occurs.
+#
+# @param [Function] test the test that returns true if condition is met
+# @param [Function] ready the action when the condition is fulfilled
+# @param [Number] timeout the max amount of time to wait in milliseconds
+#
+waitFor = (test, ready, timeout = 5000) ->
+    start = new Date().getTime()
+    condition = false
+
+    wait = ->
+      if (new Date().getTime() - start < timeout) and not condition
+        condition = test()
+      else
+        if not condition
+          text = page.evaluate -> document.getElementsByTagName('body')[0]?.innerText
+
+          if text
+            error = """
+                    Timeout waiting for the Jasmine test results!
+
+                    #{ text }
+                    """
+            console.log JSON.stringify({ error: error })
+          else
+            console.log JSON.stringify({ error: 'Timeout waiting for the Jasmine test results!' })
+
+          phantom.exit(1)
+        else
+          ready()
+          clearInterval interval
+
+    interval = setInterval wait, 250

data/lib/guard/jasmine/phantomjs/lib/console.js

@@ -0,0 +1,168 @@
+(function() {
+  var Console,
+    __slice = Array.prototype.slice;
+
+  Console = (function() {
+
+    function Console(console) {
+      var log;
+      log = console.log;
+      console.log = function() {
+        var args;
+        args = 1 <= arguments.length ? __slice.call(arguments, 0) : [];
+        return log.call(console, Console.format.apply(Console, args));
+      };
+      console.info = function() {
+        var args;
+        args = 1 <= arguments.length ? __slice.call(arguments, 0) : [];
+        return log.call(console, "INFO: " + (Console.format.apply(Console, args)));
+      };
+      console.warn = function() {
+        var args;
+        args = 1 <= arguments.length ? __slice.call(arguments, 0) : [];
+        return log.call(console, "WARN: " + (Console.format.apply(Console, args)));
+      };
+      console.error = function() {
+        var args;
+        args = 1 <= arguments.length ? __slice.call(arguments, 0) : [];
+        return log.call(console, "ERROR: " + (Console.format.apply(Console, args)));
+      };
+      console.debug = function() {
+        var args;
+        args = 1 <= arguments.length ? __slice.call(arguments, 0) : [];
+        return log.call(console, "DEBUG: " + (Console.format.apply(Console, args)));
+      };
+    }
+
+    Console.MAX_OBJECT_DEPTH = 2;
+
+    Console.format = function() {
+      var arg, args, result, _i, _len,
+        _this = this;
+      args = 1 <= arguments.length ? __slice.call(arguments, 0) : [];
+      result = [];
+      if (typeof args[0] === 'string' && /%[sdifo]/gi.test(args[0])) {
+        arg = args.shift();
+        result.push(arg.replace(/%[sdifo]/gi, function(str) {
+          return Console.inspect(args.shift(), str);
+        }));
+      }
+      for (_i = 0, _len = args.length; _i < _len; _i++) {
+        arg = args[_i];
+        result.push(Console.inspect(arg));
+      }
+      return result.join(' ');
+    };
+
+    Console.inspect = function(object, type) {
+      var match, result;
+      switch (type) {
+        case '%s':
+          result = String(object);
+          if (match = /'(.*)'/.exec(result)) result = match[1];
+          break;
+        case '%d':
+        case '%i':
+          result = parseInt(object);
+          break;
+        case '%f':
+          result = parseFloat(object);
+          break;
+        default:
+          type = Object.prototype.toString.call(object).slice(8, -1);
+          if (type === 'Object' && object.toJSON) {
+            result = Console.pp(object.toJSON());
+          } else if (type === 'Object' && object.toString && object.toString() !== '[object Object]') {
+            result = Console.pp(object.toString());
+            if (match = /'(.*)'/.exec(result)) result = match[1];
+          } else if (type === 'String') {
+            result = String(object);
+            if (match = /'(.*)'/.exec(result)) result = match[1];
+          } else {
+            result = Console.pp(object);
+          }
+      }
+      return result;
+    };
+
+    Console.pp = function(object, depth) {
+      var key, result, type, value, _i, _len;
+      if (depth == null) depth = 0;
+      type = Object.prototype.toString.call(object).slice(8, -1);
+      result = '';
+      switch (type) {
+        case 'Undefined':
+        case 'Null':
+          result += type.toLowerCase();
+          break;
+        case 'Boolean':
+        case 'Number':
+        case 'Date':
+          result += object.toString();
+          break;
+        case 'String':
+          result += "'" + (object.toString()) + "'";
+          break;
+        case 'Array':
+          if (object.length > 0) {
+            result += '[';
+            for (_i = 0, _len = object.length; _i < _len; _i++) {
+              value = object[_i];
+              if (depth < Console.MAX_OBJECT_DEPTH || Object.prototype.toString.call(value).slice(8, -1) !== 'Object') {
+                result += "" + (Console.pp(value, depth + 1)) + ", ";
+              } else {
+                result += "[Object], ";
+              }
+            }
+            result = result.slice(0, -2);
+            result += ']';
+          } else {
+            result += '[]';
+          }
+          break;
+        case 'Object':
+          if (object.jquery) {
+            if (object.length > 0) {
+              result += '[';
+              object.each(function() {
+                return result += jQuery(this).html();
+              });
+              result += ']';
+            } else {
+              result += '[]';
+            }
+          } else if (Object.keys(object).length > 0) {
+            result += '{ ';
+            for (key in object) {
+              value = object[key];
+              if (depth < Console.MAX_OBJECT_DEPTH || Object.prototype.toString.call(value).slice(8, -1) !== 'Object') {
+                if (object.hasOwnProperty(key)) {
+                  result += "" + key + ": " + (Console.pp(value, depth + 1)) + ", ";
+                }
+              } else {
+                result += "" + key + ": [Object], ";
+              }
+            }
+            result = result.slice(0, -2);
+            result += ' }';
+          } else {
+            result += '{}';
+          }
+          break;
+        case 'Function':
+          result += '[Function]';
+      }
+      return result;
+    };
+
+    return Console;
+
+  })();
+
+  if (typeof module !== 'undefined' && module.exports) {
+    if (module) module.exports = Console;
+  } else {
+    if (window) new Console(window.console);
+  }
+
+}).call(this);