Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 240 lines (169 sloc) 8.886 kb
76fe32d @jonleighton omg
jonleighton authored
1 # Poltergeist - A PhantomJS driver for Capybara #
2
fc88a85 @jonleighton Bump version
jonleighton authored
3 Version: 0.4.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
14 Add `poltergeist` to your Gemfile, and add in your test setup add:
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
77 ## Running on a CI ##
78
29291fc @jonleighton Update README
jonleighton authored
79 Currently PhantomJS is not yet 'truly headless' (but that's planned for the future),
80 so to run it on a continuous integration
ee1f46c @jonleighton Update the install / CI instructions
jonleighton authored
81 server you will need to install [Xvfb](http://en.wikipedia.org/wiki/Xvfb).
cf37abe @jonleighton Update the README
jonleighton authored
82
ee1f46c @jonleighton Update the install / CI instructions
jonleighton authored
83 ### On any generic server ###
cf37abe @jonleighton Update the README
jonleighton authored
84
ee1f46c @jonleighton Update the install / CI instructions
jonleighton authored
85 Install PhantomJS and invoke your tests with `xvfb-run`, (e.g. `xvfb-run
86 rake`).
cf37abe @jonleighton Update the README
jonleighton authored
87
ee1f46c @jonleighton Update the install / CI instructions
jonleighton authored
88 ### Using [Travis CI](http://travis-ci.org/) ###
cf37abe @jonleighton Update the README
jonleighton authored
89
ee1f46c @jonleighton Update the install / CI instructions
jonleighton authored
90 Travis CI has PhantomJS installed already! So all you need to do is add
91 the following to your `.travis.yml`:
cf37abe @jonleighton Update the README
jonleighton authored
92
ee1f46c @jonleighton Update the install / CI instructions
jonleighton authored
93 ``` yaml
94 before_script:
95 - "export DISPLAY=:99.0"
96 - "sh -e /etc/init.d/xvfb start"
97 ```
cf37abe @jonleighton Update the README
jonleighton authored
98
76fe32d @jonleighton omg
jonleighton authored
99 ## What's supported? ##
100
101 Poltergeist supports basically everything that is supported by the stock Selenium driver,
102 including Javascript, drag-and-drop, etc.
103
b18225d @jonleighton Add a resize command to allow users to resize the browser window
jonleighton authored
104 There are some additional features:
105
106 ### Taking screenshots ###
107
108 You can grab screenshots of the page at any point by calling
76fe32d @jonleighton omg
jonleighton authored
109 `page.driver.render('/path/to/file.png')` (this works the same way as the PhantomJS
110 render feature, so you can specify other extensions like `.pdf`, `.gif`, etc.)
111
fb497cb @jonleighton Add support for choosing between rendering the whole page or just part o...
jonleighton authored
112 By default, only the viewport will be rendered (the part of the page that is in view). To render
113 the entire page, use `page.driver.render('/path/to/file.png', :full => true)`.
114
b18225d @jonleighton Add a resize command to allow users to resize the browser window
jonleighton authored
115 ### Resizing the window ###
116
117 Sometimes the window size is important to how things are rendered. Poltergeist sets the window
118 size to 1024x768 by default, but you can set this yourself with `page.driver.resize(width, height)`.
119
76fe32d @jonleighton omg
jonleighton authored
120 ## Customization ##
121
122 You can customize the way that Capybara sets up Poltegeist via the following code in your
123 test setup:
124
29291fc @jonleighton Update README
jonleighton authored
125 ``` ruby
126 Capybara.register_driver :poltergeist do |app|
127 Capybara::Poltergeist::Driver.new(app, options)
128 end
129 ```
76fe32d @jonleighton omg
jonleighton authored
130
131 `options` is a hash of options. The following options are supported:
132
29291fc @jonleighton Update README
jonleighton authored
133 * `:phantomjs` (String) - A custom path to the phantomjs executable
134 * `:debug` (Boolean) - When true, debug output is logged to `STDERR`
135 * `:logger` (Object responding to `puts`) - When present, debug output is written to this object
136 * `:timeout` (Numeric) - The number of seconds we'll wait for a response
34af795 @jonleighton Stop using EventMachine for WebSocket server.
jonleighton authored
137 when communicating with PhantomJS. `nil` means wait forever. Default
9f4192e @jonleighton Increase default timeout to 30
jonleighton authored
138 is 30.
76fe32d @jonleighton omg
jonleighton authored
139
140 ## Bugs ##
141
142 Please file bug reports on Github and include example code to reproduce the problem wherever
cf37abe @jonleighton Update the README
jonleighton authored
143 possible. (Tests are even better.) Please also provide the output with
144 `:debug` turned on, and screenshots if you think it's relevant.
76fe32d @jonleighton omg
jonleighton authored
145
29291fc @jonleighton Update README
jonleighton authored
146 ## Differences from [capybara-webkit](https://github.com/thoughtbot/capybara-webkit) ##
76fe32d @jonleighton omg
jonleighton authored
147
29291fc @jonleighton Update README
jonleighton authored
148 Poltergeist is similar to capybara-webkit, but here are the key
149 differences:
76fe32d @jonleighton omg
jonleighton authored
150
29291fc @jonleighton Update README
jonleighton authored
151 * It's more hackable. Poltergeist is written in Ruby + CoffeeScript.
152 We only have to worry about C++ when dealing with issues in
153 PhantomJS itself. In contrast, the majority of capybara-webkit is
154 written in C++.
76fe32d @jonleighton omg
jonleighton authored
155
29291fc @jonleighton Update README
jonleighton authored
156 * We're able to tap into the PhantomJS community. When PhantomJS
157 improves, Poltergeist improves. User's don't have to install Qt
158 because self-contained PhantomJS binary packages are available.
cf37abe @jonleighton Update the README
jonleighton authored
159
160 ## Hacking ##
161
162 Contributions are very welcome and I will happily give commit access to
163 anyone who does a few good pull requests.
164
165 To get setup, run `bundle install`. You can run the full test suite with
166 `rspec spec/` or `rake`.
167
168 While PhantomJS is capable of compiling and running CoffeeScript code
169 directly, I prefer to compile the code myself and distribute that (it
170 makes debugging easier). Running `rake autocompile` will watch the
171 `.coffee` files for changes, and compile them into
172 `lib/capybara/client/compiled`.
173
8ab5c03 @jonleighton Fix #8
jonleighton authored
174 ## Changes ##
175
fc88a85 @jonleighton Bump version
jonleighton authored
176 ### 0.4.0 ###
48c3b97 @jonleighton Fix element position calculation. Fixes #15.
jonleighton authored
177
178 * Element click position is now calculated using the native
179 `getBoundingClientRect()` method, which will be faster and less
180 buggy.
181
1938eac @jonleighton Handle window.prompt()
jonleighton authored
182 * Handle `window.confirm()`. Always returns true, which is the same
183 as capybara-webkit. [Issue #10]
184
185 * Handle `window.prompt()`. Returns the default value, if present, or
186 null.
0ebd617 @jonleighton Handle window.confirm. Fixes #10.
jonleighton authored
187
4f1691a @jonleighton formatting
jonleighton authored
188 * Fix bug with page Javascript page loading causing problems. [Issue #19]
8b5541d @jonleighton Fix #19. (Page load synchronisation problem.)
jonleighton authored
189
48c3b97 @jonleighton Fix element position calculation. Fixes #15.
jonleighton authored
190 ### 0.3.0 ###
8ab5c03 @jonleighton Fix #8
jonleighton authored
191
a4fa4bb @jonleighton Tweak README
jonleighton authored
192 * There was a bad bug to do with clicking elements in a page where the
193 page is smaller than the window. The incorrect position would be
194 calculated, and so the click would happen in the wrong place. This is
195 fixed. [Issue #8]
8ab5c03 @jonleighton Fix #8
jonleighton authored
196
a4fa4bb @jonleighton Tweak README
jonleighton authored
197 * Poltergeist didn't work in conjunction with the Thin web server,
198 because that server uses Event Machine, and Poltergeist was assuming
199 that it was the only thing in the process using EventMachine.
34af795 @jonleighton Stop using EventMachine for WebSocket server.
jonleighton authored
200
a4fa4bb @jonleighton Tweak README
jonleighton authored
201 To solve this, EventMachine usage has been completely removed, which
202 has the welcome side-effect of being more efficient because we
203 no longer have the overhead of running a mostly-idle event loop.
34af795 @jonleighton Stop using EventMachine for WebSocket server.
jonleighton authored
204
a4fa4bb @jonleighton Tweak README
jonleighton authored
205 [Issue #6]
34af795 @jonleighton Stop using EventMachine for WebSocket server.
jonleighton authored
206
a4fa4bb @jonleighton Tweak README
jonleighton authored
207 * Added the `:timeout` option to configure the timeout when talking to
208 PhantomJS.
34af795 @jonleighton Stop using EventMachine for WebSocket server.
jonleighton authored
209
48c3b97 @jonleighton Fix element position calculation. Fixes #15.
jonleighton authored
210 ### 0.2.0 ###
8ab5c03 @jonleighton Fix #8
jonleighton authored
211
a4fa4bb @jonleighton Tweak README
jonleighton authored
212 * First version considered 'ready', hopefully fewer problems.
8ab5c03 @jonleighton Fix #8
jonleighton authored
213
48c3b97 @jonleighton Fix element position calculation. Fixes #15.
jonleighton authored
214 ### 0.1.0 ###
8ab5c03 @jonleighton Fix #8
jonleighton authored
215
a4fa4bb @jonleighton Tweak README
jonleighton authored
216 * First version, various problems.
8ab5c03 @jonleighton Fix #8
jonleighton authored
217
76fe32d @jonleighton omg
jonleighton authored
218 ## License ##
219
220 Copyright (c) 2011 Jonathan Leighton
221
222 Permission is hereby granted, free of charge, to any person obtaining
223 a copy of this software and associated documentation files (the
224 "Software"), to deal in the Software without restriction, including
225 without limitation the rights to use, copy, modify, merge, publish,
226 distribute, sublicense, and/or sell copies of the Software, and to
227 permit persons to whom the Software is furnished to do so, subject to
228 the following conditions:
229
230 The above copyright notice and this permission notice shall be
231 included in all copies or substantial portions of the Software.
232
233 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
234 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
235 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
236 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
237 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
238 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
239 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.