README.md in poltergeist-0.6.0 vs README.md in poltergeist-0.7.0
- old
+ new
@@ -1,8 +1,8 @@
# Poltergeist - A PhantomJS driver for Capybara #
-Version: 0.6.0
+Version: 0.7.0
[](http://travis-ci.org/jonleighton/poltergeist)
[](https://gemnasium.com/jonleighton/poltergeist)
Poltergeist is a driver for [Capybara](https://github.com/jnicklas/capybara). It allows you to
@@ -16,88 +16,72 @@
``` ruby
require 'capybara/poltergeist'
Capybara.javascript_driver = :poltergeist
```
-## Important note about Rack versions < 1.3.0 ##
+If you were previously using the `:rack_test` driver, be aware that
+your app will now run in a separate thread and this can have
+consequences for transactional tests. [See the Capybara README for more
+detail](https://github.com/jnicklas/capybara/blob/master/README.md#transactions-and-database-setup).
-Prior to version 1.3.0, the Rack handlers for Mongrel and Thin wrap your
-app in the `Rack::Chunked` middleware so that it uses
-`Transfer-Encoding: chunked`
-([commit](https://github.com/rack/rack/commit/50cdd0bf000a9ffb3eb3760fda2ff3e1ad18f3a7)).
-This has been observed to cause problems,
-probably due to race conditions in Qt's HTTP handling code, so you are
-recommended to avoid this by specifying your own server setup for
-Capybara:
-
-``` ruby
-Capybara.server do |app, port|
- require 'rack/handler/thin'
- Thin::Logging.silent = true
- Thin::Server.new('0.0.0.0', port, app).start
-end
-```
-
-If you're using Rails 3.0, this affects you. If you're using Rails 3.1+,
-this doesn't affect you.
-
## Installing PhantomJS ##
-You need PhantomJS 1.5.0. There are no other dependencies (you don't
-need Qt, or Xvfb, etc.)
+You need at least PhantomJS 1.6.0, but 1.6.1 is recommended as there some issues with the former.
+There are *no other external dependencies* (you don't need Qt, or a running X
+server, etc.)
### Mac ###
-* *With homebrew*: `brew install phantomjs`
-* *Without homebrew*: [Download this](http://code.google.com/p/phantomjs/downloads/detail?name=phantomjs-1.5.0-macosx-static.zip&can=2&q=)
+* *Manual install*: [Download this](http://code.google.com/p/phantomjs/downloads/detail?name=phantomjs-1.6.1-macosx-static.zip&can=2&q=)
+* *Homebrew*: `brew install phantomjs`
### Linux ###
* Download the [32
-bit](http://code.google.com/p/phantomjs/downloads/detail?name=phantomjs-1.5.0-linux-x86-dynamic.tar.gz&can=2&q=)
+bit](http://code.google.com/p/phantomjs/downloads/detail?name=phantomjs-1.6.1-linux-i686-dynamic.tar.bz2&can=2&q=)
or [64
-bit](http://code.google.com/p/phantomjs/downloads/detail?name=phantomjs-1.5.0-linux-x86_64-dynamic.tar.gz&can=2&q=)
+bit](http://code.google.com/p/phantomjs/downloads/detail?name=phantomjs-1.6.1-linux-x86_64-dynamic.tar.bz2&can=2&q=)
binary.
-* Extract it: `sudo tar xvzf phantomjs-1.5.0-linux-*-dynamic.tar.gz -C /usr/local`
-* Link it: `sudo ln -s /usr/local/phantomjs/bin/phantomjs /usr/local/bin/phantomjs`
+* Extract it: `sudo tar xvjf phantomjs-1.6.1-linux-*-dynamic.tar.gz -C /usr/local`
+* Link it: `sudo ln -s /usr/local/phantomjs-1.6.1-linux*/bin/phantomjs /usr/local/bin/phantomjs`
(Note that you cannot copy the `/usr/local/phantomjs/bin/phantomjs`
binary elsewhere on its own as it dynamically links with other files in
`/usr/local/phantomjs/lib`.)
### Manual compilation ###
Do this as a last resort if the binaries don't work for you. It will
take quite a long time as it has to build WebKit.
-* Download [the source tarball](http://code.google.com/p/phantomjs/downloads/detail?name=phantomjs-1.5.0-source.tar.gz&can=2&q=)
+* Download [the source tarball](http://code.google.com/p/phantomjs/downloads/detail?name=phantomjs-1.6.1-source.zip&can=2&q=)
* Extract and cd in
* `./build.sh`
## Compatibility ##
Supported: MRI 1.8.7, MRI 1.9.2, MRI 1.9.3, JRuby 1.8, JRuby 1.9.
Not supported:
-* Rubinius (due to some unknown socket related issues)
+* Rubinius
* Windows
Contributions are welcome in order to move 'unsupported'
items into the 'supported' list.
## Running on a CI ##
There are no special steps to take. You don't need Xvfb or any running X
server at all.
-[Travis CI](http://travis-ci.org/) has PhantomJS 1.5.0 installed.
+Depending on your tests, one thing that you may need is some fonts. If
+you're getting errors on a CI that don't occur during development then
+try taking some screenshots - it may well be missing fonts throwing
+things off kilter. Your distro will have various font packages available
+to install.
-You may like to use their [chef
-cookbook](https://github.com/travis-ci/travis-cookbooks/tree/master/ci_environment/phantomjs)
-on your own servers.
-
## What's supported? ##
Poltergeist supports basically everything that is supported by the stock Selenium driver,
including Javascript, drag-and-drop, etc.
@@ -124,14 +108,33 @@
When this option is enabled, you can insert `page.driver.debug` into
your tests to pause the test and launch a browser which gives you the
WebKit inspector to view your test run with.
-(This feature is considered experimental - it needs more polish
-and [apparently will only work on
-Linux](http://code.google.com/p/phantomjs/issues/detail?id=430).)
+[Read more
+here](http://jonathanleighton.com/articles/2012/poltergeist-0-6-0/)
+### Setting request headers ###
+
+Additional HTTP request headers can be set like so:
+
+``` ruby
+page.driver.headers = {
+ "Cookie" => "foo=bar",
+ "Host" => "foo.com"
+}
+```
+
+They will be cleared between tests, so you do not have to do this manually.
+
+### Inspecting network traffic ###
+
+You can inspect the network traffic (i.e. what resources have been
+loaded) on the current page by calling `page.driver.network_traffic`.
+This returns an array of request objects. A request object has a
+`response_parts` method containing data about the response chunks.
+
## Customization ##
You can customize the way that Capybara sets up Poltegeist via the following code in your
test setup:
@@ -148,10 +151,15 @@
* `:logger` (Object responding to `puts`) - When present, debug output is written to this object
* `:timeout` (Numeric) - The number of seconds we'll wait for a response
when communicating with PhantomJS. `nil` means wait forever. Default
is 30.
* `:inspector` (Boolean, String) - See 'Remote Debugging', above.
+* `:js_errors` (Boolean) - When false, Javascript errors do not get re-raised in Ruby.
+* `:window_size` (Array) - The dimensions of the browser window in which to test, expressed
+ as a 2-element array, e.g. [1024, 768]. Default: [1024, 768]
+* `:phantomjs_options` (Array) - Additional [command line options](http://code.google.com/p/phantomjs/wiki/Interface#Command-line_Options)
+ to be passed to PhantomJS, e.g. `['--load-images=no', '--ignore-ssl-errors=yes']`
## Bugs ##
Please file bug reports on Github and include example code to reproduce the problem wherever
possible. (Tests are even better.) Please also provide the output with
@@ -170,9 +178,38 @@
makes debugging easier). Running `rake autocompile` will watch the
`.coffee` files for changes, and compile them into
`lib/capybara/client/compiled`.
## Changes ##
+
+### 0.7.0 ###
+
+#### Features ####
+
+* Added an option `:js_errors`, allowing poltergeist to continue
+ running after JS errors. (John Griffin & Tom Stuart) [Issue #62] [Issue #69]
+* Added an option `:window_size`, allowing users to specify
+ dimensions to which the browser window will be resized.
+ (Tom Stuart) [Issue #53]
+* Capybara 1.0 is no longer supported. Capybara ~> 1.1 is required.
+* Added ability to set arbitrary http request headers
+* Inspect network traffic on the page via
+ `page.driver.network_traffic` (Doug McInnes) [Issue #77]
+* Added an option `:phantomjs_options`, allowing users to specify
+ additional command-line options passed to phantomjs executable.
+ (wynst) [Issue #97]
+* Scroll element into viewport if needed on click (Gabriel Sobrinho)
+ [Issue #83]
+* Added status code support. (Dmitriy Nesteryuk and Jon Leighton) [Issue #37]
+
+#### Bug fixes ###
+
+* Fix issue with `ClickFailed` exception happening with a negative
+ co-ordinate (which should be impossible). (Jon Leighton, Gabriel
+ Sobrinho, Tom Stuart) [Issue #60]
+* Fix issue with `undefined method map for "[]":String`, which
+ happened when dealing with pages that include JS rewriting
+ Array.prototype.toJSON. (Tom Stuart) [Issue #63]
### 0.6.0 ###
#### Features ####