README.md in poltergeist-1.0.3 vs README.md in poltergeist-1.1.0
- old
+ new
@@ -1,15 +1,18 @@
# Poltergeist - A PhantomJS driver for Capybara #
-Version: 1.0.3
-
[](http://travis-ci.org/jonleighton/poltergeist)
Poltergeist is a driver for [Capybara](https://github.com/jnicklas/capybara). It allows you to
run your Capybara tests on a headless [WebKit](http://webkit.org) browser,
provided by [PhantomJS](http://www.phantomjs.org/).
+**If you're viewing this at https://github.com/jonleighton/poltergeist,
+you're reading the documentation for the master branch.
+[View documentation for the latest release
+(1.1.0).](https://github.com/jonleighton/poltergeist/tree/v1.1.0)**
+
## Installation ##
Add `poltergeist` to your Gemfile, and in your test setup add:
``` ruby
@@ -22,48 +25,48 @@
consequences for transactional tests. [See the Capybara README for more
detail](https://github.com/jnicklas/capybara/blob/master/README.md#transactions-and-database-setup).
## Installing PhantomJS ##
-You need at least PhantomJS 1.7.0. There are *no other external
+You need at least PhantomJS 1.8.1. There are *no other external
dependencies* (you don't need Qt, or a running X server, etc.)
### Mac ###
* *Homebrew*: `brew install phantomjs`
-* *Manual install*: [Download this](http://code.google.com/p/phantomjs/downloads/detail?name=phantomjs-1.7.0-macosx.zip&can=2&q=)
+* *MacPorts*: `sudo port install phantomjs`
+* *Manual install*: [Download this](http://code.google.com/p/phantomjs/downloads/detail?name=phantomjs-1.8.1-macosx.zip&can=2&q=)
### Linux ###
* Download the [32
-bit](http://code.google.com/p/phantomjs/downloads/detail?name=phantomjs-1.7.0-linux-i686.tar.bz2&can=2&q=)
+bit](http://code.google.com/p/phantomjs/downloads/detail?name=phantomjs-1.8.1-linux-i686.tar.bz2&can=2&q=)
or [64
-bit](http://code.google.com/p/phantomjs/downloads/detail?name=phantomjs-1.7.0-linux-x86_64.tar.bz2&can=2&q=)
+bit](http://code.google.com/p/phantomjs/downloads/detail?name=phantomjs-1.8.1-linux-x86_64.tar.bz2&can=2&q=)
binary.
* Extract the tarball and copy `bin/phantomjs` into your `PATH`
### 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.7.0-source.zip&can=2&q=)
+* Download [the source tarball](http://code.google.com/p/phantomjs/downloads/detail?name=phantomjs-1.8.1-source.zip&can=2&q=)
* Extract and cd in
* `./build.sh`
(See also the [PhantomJS building
guide](http://phantomjs.org/build.html).)
## Compatibility ##
-Supported: MRI 1.8.7, MRI 1.9.2, MRI 1.9.3, JRuby 1.8, JRuby 1.9,
-Rubinius 1.8 on UNIX platforms.
+Poltergeist runs on MRI 1.9, JRuby 1.9 and Rubinius 1.9.
-Not supported: Rubinius 1.9, Windows.
+Ruby 1.8 is no longer supported. The last release to support Ruby 1.8
+was 1.0.2, so you should use that if you still need Ruby 1.8 support.
-Contributions are welcome in order to move 'unsupported'
-items into the 'supported' list.
+Poltergeist does not currently support the Windows operating system.
## Running on a CI ##
There are no special steps to take. You don't need Xvfb or any running X
server at all.
@@ -106,10 +109,15 @@
### Resizing the window ###
Sometimes the window size is important to how things are rendered. Poltergeist sets the window
size to 1024x768 by default, but you can set this yourself with `page.driver.resize(width, height)`.
+### Clicking precise coordinates ###
+
+Sometimes its desirable to click a very specific area of the screen. You can accomplish this with
+`page.driver.click(x, y)`, where x and y are the screen coordinates.
+
### Remote debugging (experimental) ###
If you use the `:inspector => true` option (see below), remote debugging
will be enabled.
@@ -165,21 +173,26 @@
```
`options` is a hash of options. The following options are supported:
* `:phantomjs` (String) - A custom path to the phantomjs executable
-* `:debug` (Boolean) - When true, debug output is logged to `STDERR`
+* `:debug` (Boolean) - When true, debug output is logged to `STDERR`.
+ Some debug info from the PhantomJS portion of Poltergeist is also
+ output, but this goes to `STDOUT` due to technical limitations.
* `:logger` (Object responding to `puts`) - When present, debug output is written to this object
+* `:phantomjs_logger` (`IO` object) - Where the `STDOUT` from PhantomJS is written to. This is
+ where you `console.log` statements will show up. Default: `STDOUT`
* `:timeout` (Numeric) - The number of seconds we'll wait for a response
- when communicating with PhantomJS. `nil` means wait forever. Default
- is 30.
+ when communicating with PhantomJS. 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)
+* `:phantomjs_options` (Array) - Additional [command line options](https://github.com/ariya/phantomjs/wiki/API-Reference)
to be passed to PhantomJS, e.g. `['--load-images=no', '--ignore-ssl-errors=yes']`
+* `:extensions` (Array) - An array of JS files to be preloaded into
+ the phantomjs browser. Useful for faking unsupported APIs.
* `:port` (Fixnum) - The port which should be used to communicate
with the PhantomJS process. Default: 44678.
## Troubleshooting ##
@@ -284,14 +297,53 @@
* The Poltergeist and PhantomJS version numbers used
* The operating system name and version used
## Changes ##
-### 1.0.3 ###
+### 1.1.0 ###
+#### Features ####
+
+* Add support for custom phantomjs loggers via `:phantomjs_logger` option.
+ (Gabe Bell)
+* Add `page.driver.click(x, y)` to click precise coordinates.
+ (Micah Geisel)
+* Add Capybara 2.0 support. Capybara 1.1 and Ruby 1.8 are *no
+ longer supported*. (Mauro Asprea) [Issue #163]
+* Add `node.base.double_click` to double click the node.
+ (Andy Shen)
+* The `:debug` option now causes the PhantomJS portion of Poltergeist
+ to output some additional debug info, which may be useful in
+ figuring out timeout errors.
+
#### Bug fixes ####
-* Tied to faye-websocket 0.4, as 0.5 introduces incompatibilities.
+* Fix timing issue when using `within_frame` that could cause errors.
+ [Issue #183, #211] (@errm, @motemen)
+* Fix bug with `within_frame` not properly switching the context back
+ after the block has executed. [Issue #242]
+* Fix calculation of click position when clicking within a frame.
+ [Issue #222, #225]
+* Fix error raising when calling `expires` if not set on cookie.
+ [Issue #203] (@arnvald)
+* Fix the `:js_errors` option. Previously errors were not being
+ reported, but would still cause commands to fail. [Issue #229]
+* Fix incorrect time zone handling when setting cookie expiry time
+ [Issue #228]
+* Send SIGKILL to PhantomJS if it doesn't exit within 2 seconds
+ [Issue #196]
+* Provide a more informative message for the `ObsoleteNode` error.
+ [Issue #192]
+* Fix `ObsoleteNode` error when using `attach_file` with the `jQuery
+ File Upload` plugin. [Issue #115]
+* Add the ability to extend the phantomjs environment via browser
+ options. e.g.
+ `Capybara::Poltergeist::Driver.new( app, :extensions => ['file.js', 'another.js'])`
+ (@JonRowe)
+* Ensure that a `String` is passed over-the-wire to PhantomJS for
+ file input paths, allowing `attach_file` to be called with arbitry
+ objects such as a Pathname. (@mjtko) [Issue #215]
+* Cookies can now be set before the first request. [Issue #193]
### 1.0.2 ###
#### Bug fixes ####