Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 299 lines (209 sloc) 11.112 kb
76fe32d @jonleighton omg
jonleighton authored
1 # Poltergeist - A PhantomJS driver for Capybara #
2
7d74282 @jonleighton bump version
jonleighton authored
3 Version: 0.5.0
76fe32d @jonleighton omg
jonleighton authored
4
7a71cc0 @jonleighton Add travis status image
jonleighton authored
5 [![Build Status](https://secure.travis-ci.org/jonleighton/poltergeist.png)](http://travis-ci.org/jonleighton/poltergeist)
2fc221b @laserlemon Add Gemnasium dependency status to README
laserlemon authored
6 [![Dependency Status](https://gemnasium.com/jonleighton/poltergeist.png)](https://gemnasium.com/jonleighton/poltergeist)
7a71cc0 @jonleighton Add travis status image
jonleighton authored
7
76fe32d @jonleighton omg
jonleighton authored
8 Poltergeist is a driver for [Capybara](https://github.com/jnicklas/capybara). It allows you to
9 run your Capybara tests on a headless [WebKit](http://webkit.org) browser,
10 provided by [PhantomJS](http://www.phantomjs.org/).
11
12 ## Installation ##
13
82d0fd0 @pjg Grammar fix in README
pjg authored
14 Add `poltergeist` to your Gemfile, and in your test setup add:
76fe32d @jonleighton omg
jonleighton authored
15
29291fc @jonleighton Update README
jonleighton authored
16 ``` ruby
17 require 'capybara/poltergeist'
18 Capybara.javascript_driver = :poltergeist
19 ```
20
21 ## Important note about Rack versions < 1.3.0 ##
22
23 Prior to version 1.3.0, the Rack handlers for Mongrel and Thin wrap your
24 app in the `Rack::Chunked` middleware so that it uses
25 `Transfer-Encoding: chunked`
26 ([commit](https://github.com/rack/rack/commit/50cdd0bf000a9ffb3eb3760fda2ff3e1ad18f3a7)).
27 This has been observed to cause problems,
28 probably due to race conditions in Qt's HTTP handling code, so you are
29 recommended to avoid this by specifying your own server setup for
30 Capybara:
31
32 ``` ruby
33 Capybara.server do |app, port|
34 require 'rack/handler/thin'
35 Thin::Logging.silent = true
36 Thin::Server.new('0.0.0.0', port, app).start
37 end
38 ```
39
40 If you're using Rails 3.0, this affects you. If you're using Rails 3.1+,
41 this doesn't affect you.
76fe32d @jonleighton omg
jonleighton authored
42
cf37abe @jonleighton Update the README
jonleighton authored
43 ## Installing PhantomJS ##
44
45 You need PhantomJS 1.4.1+, built against Qt 4.8, on your system.
46
ee1f46c @jonleighton Update the install / CI instructions
jonleighton authored
47 ### Pre-built binaries ##
48
49 There are [pre-built
50 binaries](http://code.google.com/p/phantomjs/downloads/list) of
51 PhantomJS for Linux, Mac and Windows. This is the easiest and best way
a4fa4bb @jonleighton Tweak README
jonleighton authored
52 to install it. The binaries including a patched version of Qt 4.8 so you
53 don't need to install that separately.
ee1f46c @jonleighton Update the install / CI instructions
jonleighton authored
54
55 Note that if you have a 'dynamic' package, it's important to maintain
56 the relationship between `bin/phantomjs` and `lib/`. This is because the
57 `bin/phantomjs` binary looks in `../lib/` for its library files. So the
a4fa4bb @jonleighton Tweak README
jonleighton authored
58 best thing to do is to link (rather than copy) it into your `PATH`:
cf37abe @jonleighton Update the README
jonleighton authored
59
29291fc @jonleighton Update README
jonleighton authored
60 ln -s /path/to/phantomjs/bin/phantomjs /usr/local/bin/phantomjs
cf37abe @jonleighton Update the README
jonleighton authored
61
ee1f46c @jonleighton Update the install / CI instructions
jonleighton authored
62 ### Compiling PhantomJS ###
cf37abe @jonleighton Update the README
jonleighton authored
63
ee1f46c @jonleighton Update the install / CI instructions
jonleighton authored
64 If you're having trouble with a pre-built binary package, you can
65 compile PhantomJS yourself. PhantomJS must be built against Qt 4.8, and
a4fa4bb @jonleighton Tweak README
jonleighton authored
66 some patches must be applied, so note that you cannot build it against
ee1f46c @jonleighton Update the install / CI instructions
jonleighton authored
67 your system install of Qt.
cf37abe @jonleighton Update the README
jonleighton authored
68
ee1f46c @jonleighton Update the install / CI instructions
jonleighton authored
69 [Download the tarball](http://code.google.com/p/phantomjs/downloads/detail?name=phantomjs-1.4.1-source.tar.gz&can=2&q=)
70 and run either `deploy/build-linux.sh --qt-4.8` or `cd deploy; ./build-mac.sh`.
71 The script will
72 download Qt, apply some patches, build it, and then build PhantomJS
73 against the patched build of Qt. It takes quite a while, around 30
74 minutes on a modern computer with two hyperthreaded cores. Afterwards,
75 you should copy (or link) the `bin/phantomjs` binary into your `PATH`.
76
a606a27 @jonleighton tweak readme [ci skip]
jonleighton authored
77 ## Compatibility ##
78
79 Supported: MRI 1.8.7, MRI 1.9.2, MRI 1.9.3, JRuby 1.8, JRuby 1.9.
80
81 Not supported:
82
83 * Rubinius (due to some unknown socket related issues)
84 * Windows
85
86 Anyone else welcome to contribute in order to move an 'unsupported'
87 items into the 'supported' list.
88
ee1f46c @jonleighton Update the install / CI instructions
jonleighton authored
89 ## Running on a CI ##
90
29291fc @jonleighton Update README
jonleighton authored
91 Currently PhantomJS is not yet 'truly headless' (but that's planned for the future),
92 so to run it on a continuous integration
ee1f46c @jonleighton Update the install / CI instructions
jonleighton authored
93 server you will need to install [Xvfb](http://en.wikipedia.org/wiki/Xvfb).
cf37abe @jonleighton Update the README
jonleighton authored
94
ee1f46c @jonleighton Update the install / CI instructions
jonleighton authored
95 ### On any generic server ###
cf37abe @jonleighton Update the README
jonleighton authored
96
ee1f46c @jonleighton Update the install / CI instructions
jonleighton authored
97 Install PhantomJS and invoke your tests with `xvfb-run`, (e.g. `xvfb-run
98 rake`).
cf37abe @jonleighton Update the README
jonleighton authored
99
ee1f46c @jonleighton Update the install / CI instructions
jonleighton authored
100 ### Using [Travis CI](http://travis-ci.org/) ###
cf37abe @jonleighton Update the README
jonleighton authored
101
ee1f46c @jonleighton Update the install / CI instructions
jonleighton authored
102 Travis CI has PhantomJS installed already! So all you need to do is add
103 the following to your `.travis.yml`:
cf37abe @jonleighton Update the README
jonleighton authored
104
ee1f46c @jonleighton Update the install / CI instructions
jonleighton authored
105 ``` yaml
106 before_script:
107 - "export DISPLAY=:99.0"
108 - "sh -e /etc/init.d/xvfb start"
109 ```
cf37abe @jonleighton Update the README
jonleighton authored
110
76fe32d @jonleighton omg
jonleighton authored
111 ## What's supported? ##
112
113 Poltergeist supports basically everything that is supported by the stock Selenium driver,
114 including Javascript, drag-and-drop, etc.
115
b18225d @jonleighton Add a resize command to allow users to resize the browser window
jonleighton authored
116 There are some additional features:
117
118 ### Taking screenshots ###
119
120 You can grab screenshots of the page at any point by calling
76fe32d @jonleighton omg
jonleighton authored
121 `page.driver.render('/path/to/file.png')` (this works the same way as the PhantomJS
122 render feature, so you can specify other extensions like `.pdf`, `.gif`, etc.)
123
fb497cb @jonleighton Add support for choosing between rendering the whole page or just part o...
jonleighton authored
124 By default, only the viewport will be rendered (the part of the page that is in view). To render
125 the entire page, use `page.driver.render('/path/to/file.png', :full => true)`.
126
b18225d @jonleighton Add a resize command to allow users to resize the browser window
jonleighton authored
127 ### Resizing the window ###
128
129 Sometimes the window size is important to how things are rendered. Poltergeist sets the window
130 size to 1024x768 by default, but you can set this yourself with `page.driver.resize(width, height)`.
131
76fe32d @jonleighton omg
jonleighton authored
132 ## Customization ##
133
134 You can customize the way that Capybara sets up Poltegeist via the following code in your
135 test setup:
136
29291fc @jonleighton Update README
jonleighton authored
137 ``` ruby
138 Capybara.register_driver :poltergeist do |app|
139 Capybara::Poltergeist::Driver.new(app, options)
140 end
141 ```
76fe32d @jonleighton omg
jonleighton authored
142
143 `options` is a hash of options. The following options are supported:
144
29291fc @jonleighton Update README
jonleighton authored
145 * `:phantomjs` (String) - A custom path to the phantomjs executable
146 * `:debug` (Boolean) - When true, debug output is logged to `STDERR`
147 * `:logger` (Object responding to `puts`) - When present, debug output is written to this object
148 * `:timeout` (Numeric) - The number of seconds we'll wait for a response
34af795 @jonleighton Stop using EventMachine for WebSocket server.
jonleighton authored
149 when communicating with PhantomJS. `nil` means wait forever. Default
9f4192e @jonleighton Increase default timeout to 30
jonleighton authored
150 is 30.
76fe32d @jonleighton omg
jonleighton authored
151
152 ## Bugs ##
153
154 Please file bug reports on Github and include example code to reproduce the problem wherever
cf37abe @jonleighton Update the README
jonleighton authored
155 possible. (Tests are even better.) Please also provide the output with
156 `:debug` turned on, and screenshots if you think it's relevant.
76fe32d @jonleighton omg
jonleighton authored
157
29291fc @jonleighton Update README
jonleighton authored
158 ## Differences from [capybara-webkit](https://github.com/thoughtbot/capybara-webkit) ##
76fe32d @jonleighton omg
jonleighton authored
159
29291fc @jonleighton Update README
jonleighton authored
160 Poltergeist is similar to capybara-webkit, but here are the key
161 differences:
76fe32d @jonleighton omg
jonleighton authored
162
29291fc @jonleighton Update README
jonleighton authored
163 * It's more hackable. Poltergeist is written in Ruby + CoffeeScript.
164 We only have to worry about C++ when dealing with issues in
165 PhantomJS itself. In contrast, the majority of capybara-webkit is
166 written in C++.
76fe32d @jonleighton omg
jonleighton authored
167
29291fc @jonleighton Update README
jonleighton authored
168 * We're able to tap into the PhantomJS community. When PhantomJS
169 improves, Poltergeist improves. User's don't have to install Qt
170 because self-contained PhantomJS binary packages are available.
cf37abe @jonleighton Update the README
jonleighton authored
171
172 ## Hacking ##
173
174 Contributions are very welcome and I will happily give commit access to
175 anyone who does a few good pull requests.
176
177 To get setup, run `bundle install`. You can run the full test suite with
178 `rspec spec/` or `rake`.
179
180 While PhantomJS is capable of compiling and running CoffeeScript code
181 directly, I prefer to compile the code myself and distribute that (it
182 makes debugging easier). Running `rake autocompile` will watch the
183 `.coffee` files for changes, and compile them into
184 `lib/capybara/client/compiled`.
185
8ab5c03 @jonleighton Fix #8
jonleighton authored
186 ## Changes ##
187
7d74282 @jonleighton bump version
jonleighton authored
188 ### 0.5.0 ###
f55e0ab @jonleighton update README
jonleighton authored
189
190 #### Features ####
191
192 * Detect if clicking an element will fail. If the click will actually
193 hit another element (because that element is in front of the one we
194 want to click), the user will now see an exception explaining what
195 happened and which element would actually be targeted by the click. This
196 should aid debugging. [Issue #25]
197
198 * Click elements at their middle position rather than the top-left.
199 This is presumed to be more likely to succeed because the top-left
200 may be obscured by overlapping elements, negative margins, etc. [Issue #26]
201
202 * Add experimental support for using the remote WebKit web inspector.
203 This will only work with PhantomJS 1.5, which is not yet released,
204 so it won't be officially supported by Poltergeist until 1.5 is
205 released. [Issue #31]
206
9f84f31 @jonleighton Add Driver#quit. Closes #24.
jonleighton authored
207 * Add `page.driver.quit` method. If you spawn additional Capybara
208 sessions, you might want to use this to reap the child phantomjs
209 process. [Issue #24]
210
0b9d286 @jonleighton Propagate Javascript errors on the page to Ruby. Fixes #27.
jonleighton authored
211 * Errors produced by Javascript on the page will now generate an
212 exception within Ruby. [Issue #27]
213
05b319b @jonleighton Update README about JRuby support. Closes #20. [ci skip]
jonleighton authored
214 * JRuby support. [Issue #20]
215
f55e0ab @jonleighton update README
jonleighton authored
216 #### Bug fixes ####
217
218 * Fix bug where we could end up interacting with an obsolete element. [Issue #30]
219
806a204 @jonleighton Raise a better error when phantomjs returns a non-zero exit status. Fixe...
jonleighton authored
220 * Raise an suitable error if PhantomJS returns a non-zero exit status.
221 Previously a version error would be raised, indicating that the
222 PhantomJS version was too old when in fact it did not start at all. [Issue #23]
223
edf3bae @jonleighton Add test for :timeout option to driver setting the server's timeout. Clo...
jonleighton authored
224 * Ensure the `:timeout` option is actually used. [Issue #36]
225
a67f814 @jonleighton Node references must include the page id as well. Fixes #39.
jonleighton authored
226 * Nodes need to know which page they are associated with. Before this,
227 if Javascript caused a new page to load, existing node references
228 would be wrong, but wouldn't raise an ObsoleteNode error. [Issue #39]
229
3edd4e9 @jonleighton add to changelog
jonleighton authored
230 * In some circumstances, we could end up missing an inline element
231 when attempting to click it. This is due to the use of
232 `getBoundingClientRect()`. We're now using `getClientRects()` to
233 address this.
234
fc88a85 @jonleighton Bump version
jonleighton authored
235 ### 0.4.0 ###
48c3b97 @jonleighton Fix element position calculation. Fixes #15.
jonleighton authored
236
237 * Element click position is now calculated using the native
238 `getBoundingClientRect()` method, which will be faster and less
239 buggy.
240
1938eac @jonleighton Handle window.prompt()
jonleighton authored
241 * Handle `window.confirm()`. Always returns true, which is the same
242 as capybara-webkit. [Issue #10]
243
244 * Handle `window.prompt()`. Returns the default value, if present, or
245 null.
0ebd617 @jonleighton Handle window.confirm. Fixes #10.
jonleighton authored
246
4f1691a @jonleighton formatting
jonleighton authored
247 * Fix bug with page Javascript page loading causing problems. [Issue #19]
8b5541d @jonleighton Fix #19. (Page load synchronisation problem.)
jonleighton authored
248
48c3b97 @jonleighton Fix element position calculation. Fixes #15.
jonleighton authored
249 ### 0.3.0 ###
8ab5c03 @jonleighton Fix #8
jonleighton authored
250
a4fa4bb @jonleighton Tweak README
jonleighton authored
251 * There was a bad bug to do with clicking elements in a page where the
252 page is smaller than the window. The incorrect position would be
253 calculated, and so the click would happen in the wrong place. This is
254 fixed. [Issue #8]
8ab5c03 @jonleighton Fix #8
jonleighton authored
255
a4fa4bb @jonleighton Tweak README
jonleighton authored
256 * Poltergeist didn't work in conjunction with the Thin web server,
257 because that server uses Event Machine, and Poltergeist was assuming
258 that it was the only thing in the process using EventMachine.
34af795 @jonleighton Stop using EventMachine for WebSocket server.
jonleighton authored
259
a4fa4bb @jonleighton Tweak README
jonleighton authored
260 To solve this, EventMachine usage has been completely removed, which
261 has the welcome side-effect of being more efficient because we
262 no longer have the overhead of running a mostly-idle event loop.
34af795 @jonleighton Stop using EventMachine for WebSocket server.
jonleighton authored
263
a4fa4bb @jonleighton Tweak README
jonleighton authored
264 [Issue #6]
34af795 @jonleighton Stop using EventMachine for WebSocket server.
jonleighton authored
265
a4fa4bb @jonleighton Tweak README
jonleighton authored
266 * Added the `:timeout` option to configure the timeout when talking to
267 PhantomJS.
34af795 @jonleighton Stop using EventMachine for WebSocket server.
jonleighton authored
268
48c3b97 @jonleighton Fix element position calculation. Fixes #15.
jonleighton authored
269 ### 0.2.0 ###
8ab5c03 @jonleighton Fix #8
jonleighton authored
270
a4fa4bb @jonleighton Tweak README
jonleighton authored
271 * First version considered 'ready', hopefully fewer problems.
8ab5c03 @jonleighton Fix #8
jonleighton authored
272
48c3b97 @jonleighton Fix element position calculation. Fixes #15.
jonleighton authored
273 ### 0.1.0 ###
8ab5c03 @jonleighton Fix #8
jonleighton authored
274
a4fa4bb @jonleighton Tweak README
jonleighton authored
275 * First version, various problems.
8ab5c03 @jonleighton Fix #8
jonleighton authored
276
76fe32d @jonleighton omg
jonleighton authored
277 ## License ##
278
279 Copyright (c) 2011 Jonathan Leighton
280
281 Permission is hereby granted, free of charge, to any person obtaining
282 a copy of this software and associated documentation files (the
283 "Software"), to deal in the Software without restriction, including
284 without limitation the rights to use, copy, modify, merge, publish,
285 distribute, sublicense, and/or sell copies of the Software, and to
286 permit persons to whom the Software is furnished to do so, subject to
287 the following conditions:
288
289 The above copyright notice and this permission notice shall be
290 included in all copies or substantial portions of the Software.
291
292 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
293 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
294 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
295 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
296 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
297 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
298 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.