README.md in poltergeist-1.1.2 vs README.md in poltergeist-1.2.0
- old
+ new
@@ -7,12 +7,21 @@
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.2).](https://github.com/jonleighton/poltergeist/tree/v1.1.2)**
+(1.2.0).](https://github.com/jonleighton/poltergeist/tree/v1.2.0)**
+## Getting help ##
+
+Questions should be posted [on Stack
+Overflow, using the 'poltergeist' tag](http://stackoverflow.com/questions/tagged/poltergeist).
+
+Bug reports should be posted [on
+GitHub](https://github.com/jonleighton/poltergeist/issues) (and be sure
+to read the bug reporting guidance below).
+
## Installation ##
Add `poltergeist` to your Gemfile, and in your test setup add:
``` ruby
@@ -43,10 +52,13 @@
or [64
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`
+### Windows ###
+* Download the [precompiled binary](http://phantomjs.org/download.html) for Windows
+
### 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.
@@ -57,17 +69,17 @@
(See also the [PhantomJS building
guide](http://phantomjs.org/build.html).)
## Compatibility ##
-Poltergeist runs on MRI 1.9, JRuby 1.9 and Rubinius 1.9.
+Poltergeist runs on MRI 1.9, JRuby 1.9 and Rubinius 1.9. Poltergeist
+and PhantomJS are currently supported on Mac OS X, Linux, and Windows
+platforms.
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.
-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.
@@ -90,23 +102,24 @@
* `page.evaluate_script` and `page.execute_script`
* `page.within_frame`
* `page.within_window`
* `page.status_code`
* `page.response_headers`
+* `page.save_screenshot`
* cookie handling
* drag-and-drop
There are some additional features:
-### Taking screenshots ###
+### Taking screenshots with some extensions ###
You can grab screenshots of the page at any point by calling
-`page.driver.render('/path/to/file.png')` (this works the same way as the PhantomJS
+`save_screenshot('/path/to/file.png')` (this works the same way as the PhantomJS
render feature, so you can specify other extensions like `.pdf`, `.gif`, etc.)
By default, only the viewport will be rendered (the part of the page that is in view). To render
-the entire page, use `page.driver.render('/path/to/file.png', :full => true)`.
+the entire page, use `save_screenshot('/path/to/file.png', :full => true)`.
### 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)`.
@@ -123,10 +136,22 @@
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.
+You can register this debugger driver with a different name and set it
+as the current javascript driver. By example, in your helper file:
+
+```ruby
+Capybara.register_driver :poltergeist_debug do |app|
+ Capybara::Poltergeist::Driver.new(app, :inspector => true)
+end
+
+# Capybara.javascript_driver = :poltergeist
+Capybara.javascript_driver = :poltergeist_debug
+```
+
[Read more
here](http://jonathanleighton.com/articles/2012/poltergeist-0-6-0/)
### Setting request headers ###
@@ -223,11 +248,11 @@
If you experience sporadic crashes a lot, it may be worth configuring
your CI to automatically re-run failing tests before reporting a failed
build.
-### ClickFailed errors ###
+### MouseEventFailed errors ###
When Poltergeist clicks on an element, rather than generating a DOM
click event, it actually generates a "proper" click. This is much closer
to what happens when a real user clicks on the page - but it means that
Poltergeist must scroll the page to where the element is, and work out
@@ -236,11 +261,11 @@
your user won't be able to click a covered up element either).
Sometimes there can be issues with this behavior. If you have problems,
it's worth taking screenshots of the page and trying to work out what's
going on. If your click is failing, but you're not getting a
-`ClickFailed` error, then you can turn on the `:debug` option and look
+`MouseEventFailed` error, then you can turn on the `:debug` option and look
in the output to see what co-ordinates Poltergeist is using for the
click. You can then cross-reference this with a screenshot to see if
something is obviously wrong.
If you can't figure out what's going on and just want to work around the
@@ -297,23 +322,27 @@
* The Poltergeist and PhantomJS version numbers used
* The operating system name and version used
## Changes ##
-### 1.1.2 ###
+### 1.2.0 ###
-#### Bug fixes #####
+#### Features ####
-* Tie to faye-websocket 0.4 as 0.5 introduces incompatibilities.
+* Support for Windows hosted Poltergeist (Aaron Tull).
+* Capybara 2.1 support
-### 1.1.1 ###
+#### Bug fixes ####
-#### Features ####
+* Reverted the "native" implementation for filling in form fields,
+ which was introduced in 1.0. This implementation caused various bugs
+ and in general doesn't seem to be worth the trouble at the moment.
+ It can be reconsidered in the future when PhantomJS has upgraded its
+ WebKit version. [Issue #176, #223]
+* Run phantomjs in a new process group so ^C doesn't trigger a
+ DeadClient error [Issue #252]
-* Changed Capybara dependency to `~> 2.0.1` because Poltergeist 1.1 is
- not compatible with Capybara 2.1.
-
### 1.1.0 ###
#### Features ####
* Add support for custom phantomjs loggers via `:phantomjs_logger` option.
@@ -325,10 +354,14 @@
* 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.
+* Add the ability to extend the phantomjs environment via browser
+ options. e.g.
+ `Capybara::Poltergeist::Driver.new( app, :extensions => ['file.js', 'another.js'])`
+ (Jon Rowe)
#### Bug fixes ####
* Fix timing issue when using `within_frame` that could cause errors.
[Issue #183, #211] (@errm, @motemen)
@@ -346,13 +379,9 @@
[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]