README.md in poltergeist-0.3.0 vs README.md in poltergeist-0.4.0
- old
+ new
@@ -1,8 +1,8 @@
# Poltergeist - A PhantomJS driver for Capybara #
-Version: 0.3.0
+Version: 0.4.0
[](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,
@@ -10,13 +10,37 @@
## Installation ##
Add `poltergeist` to your Gemfile, and add in your test setup add:
- require 'capybara/poltergeist'
- Capybara.javascript_driver = :poltergeist
+``` ruby
+require 'capybara/poltergeist'
+Capybara.javascript_driver = :poltergeist
+```
+## Important note about Rack versions < 1.3.0 ##
+
+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.4.1+, built against Qt 4.8, on your system.
### Pre-built binaries ##
@@ -30,13 +54,11 @@
Note that if you have a 'dynamic' package, it's important to maintain
the relationship between `bin/phantomjs` and `lib/`. This is because the
`bin/phantomjs` binary looks in `../lib/` for its library files. So the
best thing to do is to link (rather than copy) it into your `PATH`:
-```
-ln -s /path/to/phantomjs/bin/phantomjs /usr/local/bin/phantomjs
-```
+ ln -s /path/to/phantomjs/bin/phantomjs /usr/local/bin/phantomjs
### Compiling PhantomJS ###
If you're having trouble with a pre-built binary package, you can
compile PhantomJS yourself. PhantomJS must be built against Qt 4.8, and
@@ -51,11 +73,12 @@
minutes on a modern computer with two hyperthreaded cores. Afterwards,
you should copy (or link) the `bin/phantomjs` binary into your `PATH`.
## Running on a CI ##
-Currently PhantomJS is not 'truly headless', so to run it on a continuous integration
+Currently PhantomJS is not yet 'truly headless' (but that's planned for the future),
+so to run it on a continuous integration
server you will need to install [Xvfb](http://en.wikipedia.org/wiki/Xvfb).
### On any generic server ###
Install PhantomJS and invoke your tests with `xvfb-run`, (e.g. `xvfb-run
@@ -96,69 +119,77 @@
## Customization ##
You can customize the way that Capybara sets up Poltegeist via the following code in your
test setup:
- Capybara.register_driver :poltergeist do |app|
- Capybara::Poltergeist::Driver.new(app, options)
- end
+``` ruby
+Capybara.register_driver :poltergeist do |app|
+ Capybara::Poltergeist::Driver.new(app, options)
+end
+```
`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`
- * `: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
+* `:phantomjs` (String) - A custom path to the phantomjs executable
+* `:debug` (Boolean) - When true, debug output is logged to `STDERR`
+* `: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.
## 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
`:debug` turned on, and screenshots if you think it's relevant.
-## Why not use [capybara-webkit](https://github.com/thoughtbot/capybara-webkit)? ##
+## Differences from [capybara-webkit](https://github.com/thoughtbot/capybara-webkit) ##
-If capybara-webkit works for you, then by all means carry on using it.
+Poltergeist is similar to capybara-webkit, but here are the key
+differences:
-However, I have had some trouble with it, and Poltergeist basically started
-as an experiment to see whether a PhantomJS driver was possible. (It turned out it
-was, but only thanks to some new features since the 1.3 release.)
+* It's more hackable. Poltergeist is written in Ruby + CoffeeScript.
+ We only have to worry about C++ when dealing with issues in
+ PhantomJS itself. In contrast, the majority of capybara-webkit is
+ written in C++.
-In the long term, I think having a PhantomJS driver makes sense, because that allows
-PhantomJS to concentrate on being an awesome headless browser, while the capybara driver
-(Poltergeist) is able to be the minimal amount of glue code necessary to drive the
-browser.
+* We're able to tap into the PhantomJS community. When PhantomJS
+ improves, Poltergeist improves. User's don't have to install Qt
+ because self-contained PhantomJS binary packages are available.
-I also find it more pleasant to hack in CoffeeScript than C++,
-particularly as my C++ experience only goes as far as trying to make
-PhantomJS/Qt/WebKit work with Poltergeist :)
-
## Hacking ##
Contributions are very welcome and I will happily give commit access to
anyone who does a few good pull requests.
To get setup, run `bundle install`. You can run the full test suite with
`rspec spec/` or `rake`.
-I previously set up the repository on [Travis CI](http://travis-ci.org/)
-but unfortunately given they need a custom-built Qt+PhantomJS in order
-to pass, it can't be used for now. When static Linux PhantomJS builds
-are working this can be revisited.
-
While PhantomJS is capable of compiling and running CoffeeScript code
directly, I prefer to compile the code myself and distribute that (it
makes debugging easier). Running `rake autocompile` will watch the
`.coffee` files for changes, and compile them into
`lib/capybara/client/compiled`.
## Changes ##
-### 0.3 ###
+### 0.4.0 ###
+* Element click position is now calculated using the native
+ `getBoundingClientRect()` method, which will be faster and less
+ buggy.
+
+* Handle `window.confirm()`. Always returns true, which is the same
+ as capybara-webkit. [Issue #10]
+
+* Handle `window.prompt()`. Returns the default value, if present, or
+ null.
+
+* Fix bug with page Javascript page loading causing problems. [Issue #19]
+
+### 0.3.0 ###
+
* There was a bad bug to do with clicking elements in a page where the
page is smaller than the window. The incorrect position would be
calculated, and so the click would happen in the wrong place. This is
fixed. [Issue #8]
@@ -173,14 +204,14 @@
[Issue #6]
* Added the `:timeout` option to configure the timeout when talking to
PhantomJS.
-### 0.2 ###
+### 0.2.0 ###
* First version considered 'ready', hopefully fewer problems.
-### 0.1 ###
+### 0.1.0 ###
* First version, various problems.
## License ##