jasmine-headless-webkit/index.md

689 lines
30 KiB
Markdown
Raw Normal View History

2011-05-03 21:25:58 +00:00
---
2011-05-16 20:55:09 +00:00
title: jasmine-headless-webkit -- The fastest way to run your Jasmine specs!
2011-05-17 11:48:42 +00:00
layout: default
2011-05-03 21:25:58 +00:00
---
2011-05-17 11:48:42 +00:00
# Jasmine Headless WebKit
2011-05-16 20:55:09 +00:00
## Run your Jasmine specs at sonic boom speed!
2011-05-03 20:28:23 +00:00
2011-05-17 11:48:42 +00:00
<img src="images/f5.png" alt="Colored Output" />
2011-05-16 20:55:09 +00:00
[Jasmine](http://pivotal.github.com/jasmine/) is great. I love it. But running Jasmine when you need to test code that will run
in a browser environment can be problematic and slow:
2011-05-17 11:48:42 +00:00
* The [Jasmine gem](https://github.com/pivotal/jasmine-gem)'s server makes getting up and testing very fast, but F5-ing your browser for each test run is distracting.
* Jasmine CI uses Selenium, which speeds up the process a bit, but you're still rendering pixels in a browser, albeit with the option of rendering those pixels in a lot of different browsers at once.
* Node.js, EnvJS, and Rhino solutions for running Jasmine are great for anything that will never run in a real browser. I'm a big believer of running code destined for a browser in a browser itself, not a simulator.
2011-09-03 21:22:10 +00:00
* [Evergreen](https://github.com/jnicklas/evergreen) makes Jasmine testing in a Rails app as easy as pie, but not everyone writes for Rails.
2011-05-16 20:55:09 +00:00
2011-09-03 21:22:10 +00:00
But there's a solution for fast, accurate browser-based testing. with a focus on continuous testing,
using one of the most popular browser cores, and that dovetails perfectly into the Jasmine gem's already established protocols.
2011-05-16 20:55:09 +00:00
## Enter `jasmine-headless-webkit`
2011-06-17 01:30:17 +00:00
`jasmine-headless-webkit` uses the [QtWebKit widget](http://trac.webkit.org/wiki/QtWebKit) to run your specs without needing to render a pixel. It's nearly
2011-05-17 11:48:42 +00:00
as fast as running in a JavaScript engine like Node.js, and, since it's a real browser environment, all the modules
2011-09-03 21:22:10 +00:00
you would normally use, like jQuery and Backbone.js, work without any modifications. If you write your tests correctly,
2011-05-16 20:55:09 +00:00
they'll even work when running in the Jasmine gem's server with no changes to your code.
`jasmine-headless-webkit` also streamlines your workflow in other ways:
2011-09-03 21:22:10 +00:00
* It integrates with [Guard](https://github.com/guard/guard) for a continuous testing setup when using [`guard-jasmine-headless-webkit`](https://github.com/guard/guard-jasmine-headless-webkit).
2011-11-19 18:01:25 +00:00
* It integrates with [Sprockets](https://github.com/sstephenson/sprockets) to handle code requires & preprocessing and JavaScript templates.
2011-11-23 15:18:54 +00:00
* It compiles [CoffeeScript](http://jashkenas.github.com/coffee-script/), both for your tests and for your application logic.
2011-05-16 20:55:09 +00:00
* It can be configured like RSpec, and its output is very similar to RSpec's output, so you don't need to learn too much new stuff to use and integrate it.
2011-09-12 13:10:34 +00:00
* It provides cleaner debugging and backtrace output than a lot of other console-based test tools provide.
2011-09-03 21:22:10 +00:00
* It's *fast*.
## Is this for me?
That depends on what you need:
* If you're new to JavaScript testing, drop in [Pivotal's Jasmine gem](https://github.com/pivotal/jasmine-gem) and point your browser at http://localhost:8888/.
* If you're used to how the Jasmine gem works and want to move to a faster solution geared toward continuous testing, you're in the right place!
* If you want an even simpler config and access to all of your Rails routes and resources for a quasi-intergration testing setup, use [Evergreen](https://github.com/jnicklas/evergreen).
You even get your choice of browser drivers for free (as opposed to just Selenium or WebKit) as well as headless testing!
* If you want true integration testing, where you test the whole application stack, use Cucumber and/or Capybara.
* If you're not using Rails and still want to unit test, the Jasmine gem or `jasmine-headless-webkit` is what you want.
'round here, we focus on unit testing and mocking external interfaces. No using your app's views or routes, no hitting the app server to
2011-11-23 15:18:54 +00:00
get resources, just mocking and stubbing the JavaScript code all by itself.
2011-05-16 20:55:09 +00:00
2011-05-17 11:48:42 +00:00
## How do I use this wonderful toy?
2011-05-16 20:55:09 +00:00
You can use it standalone:
gem install jasmine-headless-webkit
Or you can use it with Bundler:
gem 'jasmine-headless-webkit'
However you install it, you'll get a `jasmine-headless-webkit` executable. You'll also need to set up your project
to use the Jasmine gem:
gem install jasmine
jasmine init
2011-09-03 21:22:10 +00:00
Once you're good enough, you can make the `spec/javascripts/support/jasmine.yml` file yourself and skip the Pivotal Jasmine gem entirely.
It's what the cool kids do.
2011-05-17 11:48:42 +00:00
### What do I need to get it working?
Installation requires Qt 4.7. `jasmine-headless-webkit` has been tested in the following environments:
2011-05-17 11:48:42 +00:00
2011-09-03 21:22:10 +00:00
* Mac OS X 10.6 and 10.7, with MacPorts Qt, Homebrew Qt and Nokia Qt.mpkg
2011-09-12 13:10:34 +00:00
* Kubuntu 110.04, 10.10 and 10.04
* Ubuntu 11.04 and 9.10
2011-06-22 16:47:51 +00:00
* Arch Linux
2011-05-17 11:48:42 +00:00
2011-09-03 21:22:10 +00:00
If it works in yours, [leave me a message on GitHub](https://github.com/johnbintz) or
2011-05-17 11:48:42 +00:00
[fork this site](https://github.com/johnbintz/jasmine-headless-webkit/tree/gh-pages) and add your setup.
## Qt 4.7.X
2011-09-12 13:10:34 +00:00
The gem is compiled using `qt4-qmake` and you will need Qt 4.7.x or greater.
2011-07-19 13:16:32 +00:00
The version you have installed should be detected correctly, and the appropriate message for installing Qt should
be given if it's wrong. If it's not, please file a new issue!
### Manually checking the Qt version
2011-09-12 13:10:34 +00:00
Test that `qt4-qmake` it is installed and verify your version.
qmake --version
If you have the Qt 4.7.x or greater, you are ready to install jasmine-headless-webkit.
QMake version 2.01a
Using Qt version 4.7.2 in /usr/lib
2011-09-12 13:10:34 +00:00
If you receive a different message, you can install `qt4-qmake` using one of the following commands as root:
### Ubuntu 11.04
2011-08-29 14:02:27 +00:00
{% highlight bash %}
sudo apt-get install libqt4-dev
sudo apt-get install qt4-qmake
2011-09-12 13:10:34 +00:00
sudo update-alternatives --config qmake # and select Qt 4's qmake
2011-08-29 14:02:27 +00:00
{% endhighlight %}
2011-08-29 14:04:15 +00:00
### Ubuntu 9.10
Running `sudo apt-get install libqt4-dev` and `sudo apt-get install qt4-qmake` will install qt4,
but it installs **version 4.5.2**, which will not be able to compile
**jasmine-headless-webkit**, as it requires Qt 4.7.X or greater.
You will need to compile qt4-qmake from source
[Qt version 4.7.0](http://get.qt.nokia.com/qt/source/qt-everywhere-opensource-src-4.7.0.tar.gz).
There are excellent [directions](http://doc.qt.nokia.com/latest/install-x11.html) on how to compile
2011-09-12 13:10:34 +00:00
the source code. You will need to ensure Qt is exported to your `$PATH` before using qmake, as the source code will
install to `/usr/local/Trolltech/`.
2011-08-29 14:04:15 +00:00
2011-08-29 14:03:04 +00:00
### Mac OS X 10.6 & 10.7
2011-08-29 13:59:46 +00:00
#### MacPorts
2011-08-29 14:02:27 +00:00
{% highlight bash %}
sudo port install qt4-mac
2011-08-29 14:02:27 +00:00
{% endhighlight %}
2011-08-29 13:59:46 +00:00
#### Homebrew
2011-08-29 14:02:27 +00:00
{% highlight bash %}
2011-08-29 13:59:46 +00:00
brew install qt
2011-08-29 14:02:27 +00:00
{% endhighlight %}
2011-08-29 13:59:46 +00:00
__(you may need to use `--build-from-source` on Lion)__
### My OS isn't on here!
[`capybara-webkit`](https://github.com/thoughtbot/capybara-webkit) has the best instructions for installing Qt on various other
systems that may not be covered here.
2011-05-17 11:48:42 +00:00
### How does it work?
`jasmine-headless-webkit` generates a static HTML file that includes the Jasmine JavaScript library from the Jasmine
gem, your application and spec files, and any helpers you may need. The runner then creates a WebKit widget that
loads the HTML file, runs the tests, and grabs the results of the test to show back to you. Awesome!
2011-05-17 15:24:37 +00:00
`jasmine-headless-webkit` uses the same `jasmine.yml` file that the Jasmine gem uses to define where particular
2011-05-16 20:55:09 +00:00
files for the testing process are located:
{% highlight yaml %}
src_files:
2011-11-19 18:01:25 +00:00
- "**/*"
2011-05-16 20:55:09 +00:00
helpers:
2011-11-19 18:01:25 +00:00
- helpers/**/*
2011-05-16 20:55:09 +00:00
spec_files:
2011-11-19 18:01:25 +00:00
- "**/*_spec.*"
src_dir: app/assets/javascripts
2011-05-16 20:55:09 +00:00
spec_dir: spec/javascripts
{% endhighlight %}
2011-05-17 11:48:42 +00:00
It also brings in the same copy of the Jasmine library that the Jasmine gem includes, so if you're testing in both environments,
you're guaranteed to get the same results in your tests.
#### `*.coffee` in my `jasmine.yml` file?!
2011-05-16 20:55:09 +00:00
2011-05-17 11:48:42 +00:00
Yes, `jasmine-headless-webkit` will support `*.coffee` files in `jasmine.yml`, which the normal Jasmine server currently
2011-05-16 20:55:09 +00:00
does not support out of the box. Once there's official support, you'll be able to easily switch between `jasmine-headless-webkit`
2011-05-17 11:48:42 +00:00
and the Jasmine test server when you're using CoffeeScript. CoffeeScript files are compiled and injected into the generated HTML
files.
2011-05-17 14:53:54 +00:00
Never done Jasmine in CoffeeScript? It looks like this:
{% highlight coffeescript %}
describe 'Component', ->
describe 'StorylineNode', ->
model = null
beforeEach ->
model = new ComponentStorylineNode({id: 1})
it 'should not be new', ->
expect(model.isNew()).toEqual(false)
{% endhighlight %}
...and it turns into this...
{% highlight js %}
describe('Component', function() {
return describe('StorylineNode', function() {
var model;
model = null;
beforeEach(function() {
return model = new ComponentStorylineNode({
id: 1
});
});
return it('should not be new', function() {
return expect(model.isNew()).toEqual(false);
});
});
});
{% endhighlight %}
2011-06-08 13:39:47 +00:00
2011-05-17 11:48:42 +00:00
#### Server interaction
Since there's no Jasmine server running, there's no way to grab test files from the filesystem via Ajax.
If you need to test server interaction, do one of the following:
2011-06-08 13:39:47 +00:00
* Stub your server responses using [Sinon.JS](http://sinonjs.org/), the recommended way.
2011-05-17 11:48:42 +00:00
* Use [PhantomJS](http://www.phantomjs.org/) against a running copy of a Jasmine server, instead of this project.
2011-11-19 18:01:25 +00:00
#### Sprockets support
2011-10-24 15:18:39 +00:00
2011-11-23 15:18:54 +00:00
Nearly all of Sprockets is accessible to your test suite when using `jasmine-headless-webkit`.
It's easier to list the parts that aren't accessible:
2011-10-24 15:18:39 +00:00
2011-11-19 18:01:25 +00:00
* `*.erb` files are not processed at all (and are actually ignored) because it's assumed the contents of those files depend on an
2011-11-23 15:18:54 +00:00
outside source, like a Rails app. That integration puts testing those files squarely in the "integration testing" realm, so
it's not valid to support them in a unit testing tool.
2011-11-19 18:01:25 +00:00
* No CSS compilation happens, so no Sass or LESS.
2011-10-24 15:18:39 +00:00
2011-11-23 15:18:54 +00:00
If any gems have `vendor/assets/javascripts` in their list of files, such as `jquery-rails`, those are put in the asset
path along with the paths you define in `src_dir`:
{% highlight yaml %}
src_dir:
2011-12-01 23:11:46 +00:00
- app/assets/javascripts
- vendor/assets/javascripts
2011-11-23 15:18:54 +00:00
{% endhighlight %}
_Technically, `spec_dir` is in your asset path, too, but Jasmine's typical behavior of including `helpers` before `spec_dir` should
give you all the include power you need for defining specs._
2011-12-01 23:11:46 +00:00
If you want to keep `src_dir` as a string for backwards compatibility, you can add additional asset paths with, you guessed it, `asset_paths`:
{% highlight yaml %}
src_dir: app/assets/javascripts
asset_paths:
- vendor/assets/javascripts
{% endhighlight %}
`asset_paths` are added to the Sprockets asset paths after `src_dir`.
2011-11-24 15:54:51 +00:00
In order for Sprockets support to work as intended, you should define your `src_files` and `spec_files` as such:
2011-11-23 15:18:54 +00:00
{% highlight yaml %}
2011-11-24 15:54:51 +00:00
src_files:
2011-11-23 15:18:54 +00:00
- "**/*.*"
2011-11-24 15:54:51 +00:00
spec_files:
2011-11-23 15:18:54 +00:00
- "**/*[Ss]pec.*"
{% endhighlight %}
2011-11-23 15:20:57 +00:00
This will include everything that Sprockets understands in all your `src_dir` and `spec_dir` paths. At that point, use Sprockets `require`
2011-11-23 15:18:54 +00:00
statements to define the include order of your files. Using the `--list` option on the command line to list the load order of files, combined
with the `--runner-out` option to write HTML runner files to a place where the browser can easily get to them, is very helpful when moving to
a Sprockets-managed project.
JavaScript Templates are supported too, including [haml-sprockets](https://github.com/dharanasoft/haml-sprockets). Use them as you would any other
JavaScript file, and ensure the load order is right, and the necessary code in the JST namespace will be created. To use an alternative template, like [handlebars](http://handlebarsjs.com/) or [dust](http://akdubya.github.com/dustjs/), you can [register a custom template engine](#register-custom-template).
2011-11-23 15:18:54 +00:00
Since any gem with `vendor/assets/javascripts` is usable, that means Jasmine-specific gems are possible now. [jasmine-spec-extras](https://github.com/johnbintz/jasmine-spec-extras)
is the first such gem, which provides `jasmine-jquery`, `sinon`, and any other useful Jasmine helpers, vendored into the gem so you can easily include
them into your project without having to manually manage them yourself:
{% highlight coffeescript %}
#= require sinon
#= require backbone
describe "Spy thing", ->
it 'should fire a callback', ->
collection = new Backbone.Collection()
spy = sinon.spy()
collection.bind('reset', spy)
collection.reset()
{% endhighlight %}
2011-11-19 18:01:25 +00:00
If you have to use ERB to inject information into the JavaScript or CoffeeScript files in your project, I recommend that you move those
injections to a file that is included separately from the code, or include them in `application.*.erb` like this:
{% highlight coffeescript %}
# File: app/assets/javascripts/application.coffee.erb
#= require 'jquery'
#= require 'my_library'
MyLibrary.root_url = <%= api_root_path %>
2011-10-24 15:18:39 +00:00
{% endhighlight %}
2011-11-23 15:21:42 +00:00
Sprockets support is still pretty new, so as myself and others discover the best way to set up code that can be used in both places, those
2011-11-19 18:01:25 +00:00
practices will be outlined here.
2011-10-24 15:18:39 +00:00
2011-11-23 15:18:54 +00:00
#### Caching, caching, caching
`jasmine-headless-webkit` does two things that are CPU intensive (besides running tests): compiling CoffeeScript and analyzing
spec files to get line number information for nicer spec failure messages (_did I mention you get really nice spec failure
messages with `jasmine-headless-webkit`, too?_). These two operations are cached into the `.jhw-cache/` folder from where the
runner is executed. When this cache is combined with running tests continuously using Guard, runtime overhead is reduced to almost
nothing.
Of course, being a cache, it takes time to warm up. The first time you run `jasmine-headless-webkit` on a big project, it can take
several seconds to warm the cache. After that, enjoy an almost 20% speedup in runtime (tested on exactly one project's runtime,
YMMV).
2011-05-17 11:48:42 +00:00
#### What else works?
`alert()` and `confirm()` work, though the latter always returns `true`. You should be mocking calls to `confirm()`,
of course:
{% highlight js %}
spyOn(window, 'confirm').andReturn(false)
{% endhighlight %}
2011-09-08 18:33:36 +00:00
`console.log()` also works. It uses one of three methods for serializing what you've provided:
2011-05-17 11:48:42 +00:00
2011-09-08 18:33:36 +00:00
* If the object given responds to `toJSON`, `jasmine-headless-webkit` uses `JSON.stringify(object.toJSON())`.
* If the object is a jQuery object, it is serialized with `jQuery('<div>').append(object).html()`
and pretty-printed using the HTML beautifier from [JS Beautifier](https://github.com/einars/js-beautify).
* If none of these apply, it uses a hacked-up version of [jsDump](https://github.com/NV/jsDump) that ignores
Functions on objects and prevents cyclical references.
2011-05-16 20:55:09 +00:00
2011-09-08 18:33:36 +00:00
If you need a heavy-weight object printer, you also have `console.pp()`, which uses Jasmine's built-in pretty-printer if available, and falls back to `JSON.stringify()` if it's not.
2011-06-08 13:39:47 +00:00
2011-10-24 15:18:39 +00:00
You also get an additional method, `console.peek()`, which calls `console.log()` with the provided parameter, then passes the parameter back along so you
can continue to work with it. It's the equivalent of `.tap { |o| p o }` in Ruby.
2011-05-16 20:55:09 +00:00
## Running the runner
2011-05-17 11:48:42 +00:00
{% highlight bash %}
2011-09-03 21:22:10 +00:00
jasmine-headless-webkit [ -c / --colors ]
[ --no-colors ]
[ --no-full-run ]
[ --keep ]
[ -l / --list ]
[ --report <report file> ]
2011-10-24 15:18:39 +00:00
[ --runner-out <html file> ]
2011-05-17 11:48:42 +00:00
[ -j / --jasmine-config <path to jasmine.yml> ]
2011-11-28 19:16:12 +00:00
[ --seed <random seed> ]
2011-05-17 11:48:42 +00:00
<spec files to run>
{% endhighlight %}
The runner will return one of three exit codes:
* __0__ means your tests passed sucessfully.
* __1__ means you had a failure in your tests.
* __2__ means your tests passed, but you used `console.log()` somewhere.
### Setting default options
Much like RSpec, you can define the default options for each run of the runner. Place your global options into a
`~/.jasmine-headless-webkit` file and your per-project settings in a `.jasmine-headless-webkit` file at the root of
the project.
2011-05-16 20:55:09 +00:00
2011-09-03 21:22:10 +00:00
### Listng what files `jasmine-headless-webkit` will include
If your tests are not picking up a file you thought they should be, or they're being included in the wrong order,
run with the `-l` flag to get a list of the files that `jasmine-headless-webkit` will include in the generated HTML file.
2011-11-19 18:01:25 +00:00
*Very* handy for making sure your Sprockets requires are working correctly.
2011-09-03 21:22:10 +00:00
2011-05-16 20:55:09 +00:00
### Coloring the output
`jasmine-headless-webkit` will not color output by default. This makes it easier to integrate with CI servers. If you want
2011-05-17 11:48:42 +00:00
colored output, use the `-c` flag. With colored output, your tests will look like this:
<img class="large" src="images/colored-output.png" alt="Colored Output" />
If you have colors turned on globally, you can turn them off per-project or per-run with `--no-colors`.
### Preserving compiled output on errors
CoffeeScript logic errors can be hard to track down. Keep the generated HTML files with the `--keep` flag and you'll
get `specrunner.$$.html` files in your working directory.
### Writing out a machine-readable report
2011-09-03 21:22:10 +00:00
Use the `--report` option to create a detailed report file:
2011-09-03 21:22:10 +00:00
PASS||Statement||One||file.js:23
FAIL||Statement||Two||file.js:23
CONSOLE||Yes
ERROR||Uh oh||file.js:23
TOTAL||1||2||3||T
[`guard-jasmine-headless-webkit`](http://github.com/guard/guard-jasmine-headless-webkit/) uses this for the Growl notifications.
2011-09-03 21:22:10 +00:00
You can also use it in your own setups, to run specs remotely and stick the results into a CI system. You can use
`Jasmine::Headless::Report` to interpret the file and transform the output.
2011-05-17 11:48:42 +00:00
### Using a different `jasmine.yml` file
If for some reason you're not using the default path for a `jasmine.yml` file (which is `spec/javascripts/support/jasmine.yml`),
you can provide that path with `-j`.
2011-11-28 19:16:12 +00:00
### Randomizing the order of spec files
Spec files are shuffled into a random order before each run. This lets you find issues where spec files may depend on state
established in prior executed spec files -- a bad thing. After each run, you'll get the random seed used to randomize the files:
2011-11-28 19:16:50 +00:00
`Test ordering seed: --seed 1234`
2011-11-28 19:16:12 +00:00
2011-11-28 19:29:31 +00:00
If you're getting weird results related to the particular order of a run of specs, pass that same seed value back in
2011-11-28 19:16:12 +00:00
and get to work!
2011-05-17 11:48:42 +00:00
### Running only certain spec files
By default, if no files are passed into `jasmine-headless-webkit`, all possible spec files in the `spec_files` definition
will be run. You can limit the run to only certain files by passing those to `jasmine-headless-webkit`:
{% highlight bash %}
jasmine-headless-webkit spec/javascripts/models/node_viewer.coffee
{% endhighlight %}
2011-06-10 15:19:50 +00:00
#### Filtered runs and full runs
Typically, targeted spec running is done by a tool like Guard, and the order of running goes like this:
* Run the filtered spec
* If it fails, stop processing and alert the user
* If it succeeds, run all specs and alert on success or failure
Having your test running tool re-run `jasmine-headless-webkit` is fast, but there's still the cost of instantiating QtWebKit and Ruby
with each run. Versions of `jasmine-headless-webkit` 0.3.0 and greater will do this for you, keeping the widget in memory and running
Jasmine tests on first the filtered suite, and then the complete suite. The results you'll get are for the last run that's executed, which
is typically what you want to know anyway. Newer versions of `guard-jasmine-headless-webkit` also support this behavior. This trims
valuable seconds off of testing with every run, saving you enough time every day to run to the coffee shop and get some delicious brew!
If you don't want this behavior, pass in `--no-full-run` and filtered runs will be the only thing that runs when you request one.
2011-10-24 15:18:39 +00:00
### Writing the HTML runner to another location
If you want to use the runner file in other places, use the `--runner-out` parameter with the name of the target file.
The HTML produced uses the Jasmine `HtmlReporter` if not loaded in `jasmine-headless-webkit`, so you should be able
to just open it in a browser and have it work.
If you always want the reporter written to a particular location, you can define that location in `jasmine.yml`:
{% highlight yaml %}
runner_output: "runner.html"
{% endhighlight %}
2011-06-16 17:05:17 +00:00
## Running the runner from a Ruby program
You can call the runner from Ruby:
{% highlight ruby %}
2011-09-03 21:22:10 +00:00
require 'jasmine-headless-webkit'
2011-06-17 01:30:17 +00:00
status_code = Jasmine::Headless::Runner.run(
:colors => false,
#=> true to get colors
:remove_html_file => true,
#=> false to keep specrunners on failure
:jasmine_config => 'spec/javascripts/support/jasmine.yml',
#=> run a different config
:report => false,
#=> filename if a report file should be written
:full_run => true,
#=> false to not run a full run after a targeted run
:files => ['file_one_spec.js', 'file_two_spec.coffee']
#=> files to use for a targeted run, [] to run all
)
2011-06-16 17:05:17 +00:00
{% endhighlight %}
2011-05-17 11:48:42 +00:00
## Automated testing during development
`jasmine-headless-webkit` works best when it's running all the time, re-running tests when you update the appropriate files.
If you use [Guard](https://github.com/guard/guard/), install [`guard-jasmine-headless-webkit`](http://github.com/guard/guard-jasmine-headless-webkit/)
2011-05-24 10:46:00 +00:00
and run `guard init jasmine-headless-webkit` to add the necessary bits to your `Guardfile` to test a Rails 3.1 (or a well-structured Rails 3.0) app.
2011-05-17 11:48:42 +00:00
2011-11-19 18:01:25 +00:00
### guard-rails-assets
2011-06-18 16:53:07 +00:00
2011-11-19 18:01:25 +00:00
With Sprockets support now in `jasmine-headless-webkit`, there's less of a need for most users for `guard-rails-assets`, unless you really need to get
at those ERB files in your project. [`guard-rails-assets`](http://github.com/dnagir/guard-rails-assets) is what you want to use in this case.
It will watch your app's code for changes and rebuild your pipelined JS code, ready to be tested with `jasmine-headless-webkit`:
2011-06-18 16:53:07 +00:00
{% highlight ruby %}
guard 'rails-assets' do
watch(%r{^app/assets/javascripts/(.*)\.(js|coffee)$})
end
guard 'jasmine-headless-webkit' do
watch(%r{^public/assets/.*\.js$})
watch(%r{^spec/javascripts/.*\.coffee$})
end
{% endhighlight %}
### Jammit for JS templates
2011-11-19 18:01:25 +00:00
If you're still using Jammit it shove your JS templates into one file, you can use a Guard for that, too! [`guard-jammit`](http://github.com/guard/guard-jammit)
2011-06-18 16:53:07 +00:00
provides Jammit watching support, but the current version (as of 2011-06-18) does not support some changes to Jammit's internals. Use [my fork](http://github.com/johnbintz/guard-jammit)
until that gets fixed.
{% highlight ruby %}
guard 'jammit' do
watch(%r{^app/views/.*\.jst$$})
end
guard 'jasmine-headless-webkit' do
watch(%r{^public/assets/.*\.js$})
watch(%r{^spec/javascripts/.*\.coffee$})
end
{% endhighlight %}
2011-05-17 11:48:42 +00:00
## Rake tasks
You can create a Rake task for your headless Jasmine specs:
{% highlight ruby %}
2011-09-03 21:22:10 +00:00
require 'jasmine-headless-webkit'
2011-05-17 11:48:42 +00:00
Jasmine::Headless::Task.new('jasmine:headless') do |t|
t.colors = true
t.keep_on_error = true
t.jasmine_config = 'this/is/the/path.yml'
end
{% endhighlight %}
2011-05-17 14:53:54 +00:00
If you've bundled `jasmine-headless-webkit` in with Rails, you'll also get a basic task for running your
Jasmine specs. Be sure to include the gem in the development group so you get with a normal call to `rake -T`:
{% highlight ruby %}
group :test, :development do
gem 'jasmine-headless-webkit'
end
{% endhighlight %}
<pre>
# rake -T
rake jasmine:headless # Run Jasmine specs headlessly
</pre>
This is the same as running `jasmine-headless-webkit -c`.
2011-09-12 13:10:34 +00:00
## Continuous integration & testing using Xvfb
Since most continuous integration servers do not have a display, you will need to use
2011-07-14 19:26:15 +00:00
Xvfb or virtual framebuffer Xserver for Version 11. If you elect not to use Xvfb, you will
need to have a browser and graphical display to run `jasmine-headless-webkit -c`.
Reference: [Xvfb Manpages](http://manpages.ubuntu.com/manpages/natty/man1/Xvfb.1.html)
### Install Xvfb
sudo apt-get install xvfb
2011-09-12 13:10:34 +00:00
### Resolve missing dependencies
2011-07-14 19:26:15 +00:00
To resolve missing dependencies, you will need to know what to install.
$ Xvfb :99 -ac
You will see a long list of warning messages:
[dix] Could not init font path element /usr/share/fonts/X11/misc,
removing from list!
[dix] Could not init font path element /usr/share/fonts/X11/cyrillic,
removing from list!
[dix] Could not init font path element
/usr/share/fonts/X11/100dpi/:unscaled, removing from list!
[dix] Could not init font path element
/usr/share/fonts/X11/75dpi/:unscaled, removing from list!
[dix] Could not init font path element
/usr/share/fonts/X11/Type1, removing from list!
[dix] Could not init font path element
/usr/share/fonts/X11/100dpi, removing from list!
[dix] Could not init font path element
/usr/share/fonts/X11/75dpi, removing from list!
sh: /usr/bin/xkbcomp: not found
(EE) Error compiling keymap (server-42)
(EE) XKB: Couldn't compile keymap
[config/dbus] couldn't take over org.x.config:
org.freedesktop.DBus.Error.AccessDenied
(Connection ":1.74" is not allowed to
own the service "org.x.config.display99"
due to security policies in the configuration file)
Installing the following packages would resolve the above warning messages. Your
missing packages may be different depending on the packages you have installed.
sudo apt-get install x11-xkb-utils
sudo apt-get install xfonts-100dpi xfonts-75dpi
sudo apt-get install xfonts-scalable xfonts-cyrillic
sudo apt-get install xserver-xorg-core
Once you have resolved these dependencies, you should see:
[dix] Could not init font path element /usr/share/fonts/X11/misc,
removing from list!
[dix] Could not init font path element /usr/share/fonts/X11/cyrillic,
removing from list!
[dix] Could not init font path element
/usr/share/fonts/X11/100dpi/:unscaled, removing from list!
[dix] Could not init font path element
/usr/share/fonts/X11/75dpi/:unscaled, removing from list!
[dix] Could not init font path element
/usr/share/fonts/X11/Type1, removing from list!
[dix] Could not init font path element
/usr/share/fonts/X11/100dpi, removing from list!
[dix] Could not init font path element
/usr/share/fonts/X11/75dpi, removing from list!
### Run with Xvfb
2011-09-12 13:10:34 +00:00
#### ...as a Rake task
2011-07-14 19:26:15 +00:00
xvfb-run rake jasmine:headless
2011-09-12 13:10:34 +00:00
# ...or...
2011-07-14 19:26:15 +00:00
xvfb-run jasmine-headless-webkit -c
Reference: [MARTIN DALE LYNESS](http://blog.martin-lyness.com/archives/installing-xvfb-on-ubuntu-9-10-karmic-koala)
2011-09-12 13:10:34 +00:00
#### ...seamlessly
First run Xvfb in the background:
Xvfb :0 -screen 0 1024x768x24 > /dev/null 2>&1 &
Then, set your `DISPLAY` to point at the Xvfb instance. Putting all this in your `.bash_profile` or equivalent startup
script makes this a lot easier:
xdpyinfo -display :0 &>/dev/null && export DISPLAY=:0
See [Paul Goscicki's post](http://paulgoscicki.com/archives/2011/09/run-guard-jasmine-headless-webkit-without-x-server/) for
more details on the setup. Thanks, Paul!
## RubyMine
RubyMine may throw an error when running rake spec, you will need to provide a
2011-07-14 19:26:15 +00:00
JavaScript runtime environment.
rake aborted!
Could not find a JavaScript runtime.
See https://github.com/sstephenson/execjs
for a list of available runtimes.
2011-09-12 13:18:52 +00:00
To resolve this problem, install and use the `therubyracer` gem, which is the embed V8 JavaScript interpreter into Ruby.
2011-09-12 13:10:34 +00:00
Additionally, you can set the `EXECJS_RUNTIME` environment variable to a [valid ExecJS runtime name](https://github.com/sstephenson/execjs/blob/master/lib/execjs/runtimes.rb#L55).
2011-07-14 19:26:15 +00:00
2011-09-12 13:10:34 +00:00
export EXECJS_RUNTIME=Node
<div id="register-custom-template"></div>
## Register Custom Javascript Template Engine
You may have a preference for a javascript template engine not currently supported by `jasmine-headless-webkit` out of the box. As an alternative, you can register a custom [tilt](https://github.com/rtomayko/tilt) template engine in your spec helper file to adapt your preferred template to the `jasmine-headless-webkit` runner. The one shown below was written to enable handlebars templates provided by the [handlebars_assets](https://github.com/leshill/handlebars_assets) gem.
# spec/javascripts/helpers/spec_helper.rb
require 'sprockets'
require 'handlebars_assets'
module MyExtension
class HandlebarsTemplate < HandlebarsAssets::TiltHandlebars
include Jasmine::Headless::FileChecker
def evaluate(*args)
if bad_format?(file)
alert_bad_format(file)
return ''
end
%{<script type="text/javascript">#{super}</script>}
end
end
end
Jasmine::Headless.register_engine '.hbs', MyExtension::HandlebarsTemplate
2011-05-17 11:48:42 +00:00
## I have a problem or helpful suggestion, good sir.
Here's what you can do:
* Leave a ticket on [the Issues tracker](https://github.com/johnbintz/jasmine-headless-webkit/issues).
* [Fork'n'fix the code](https://github.com/johnbintz/jasmine-headless-webkit). Feel free to add a bunch of tests, too. I cowboyed this project when starting it, and I'm slowly getting back to being a good boy.
* Ping me on [Twitter](http://twitter.com/johnbintz) or on [GitHub](https://github.com/johnbintz).
## Credits & License
* Copyright (c) 2011 John Bintz
* Original Qt WebKit runner Copyright (c) 2010 Sencha Inc.
* Jasmine JavaScript library Copyright (c) 2008-2011 Pivotal Labs
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.
2011-05-03 20:28:23 +00:00