Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 220 lines (152 sloc) 8.397 kb
76fe32d @jonleighton omg
jonleighton authored
1 # Poltergeist - A PhantomJS driver for Capybara #
2
497b401 @jonleighton Bump version
jonleighton authored
3 Version: 0.3.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)
6
76fe32d @jonleighton omg
jonleighton authored
7 Poltergeist is a driver for [Capybara](https://github.com/jnicklas/capybara). It allows you to
8 run your Capybara tests on a headless [WebKit](http://webkit.org) browser,
9 provided by [PhantomJS](http://www.phantomjs.org/).
10
11 ## Installation ##
12
13 Add `poltergeist` to your Gemfile, and add in your test setup add:
14
15 require 'capybara/poltergeist'
16 Capybara.javascript_driver = :poltergeist
17
cf37abe @jonleighton Update the README
jonleighton authored
18 ## Installing PhantomJS ##
19
20 You need PhantomJS 1.4.1+, built against Qt 4.8, on your system.
21
ee1f46c @jonleighton Update the install / CI instructions
jonleighton authored
22 ### Pre-built binaries ##
23
24 There are [pre-built
25 binaries](http://code.google.com/p/phantomjs/downloads/list) of
26 PhantomJS for Linux, Mac and Windows. This is the easiest and best way
a4fa4bb @jonleighton Tweak README
jonleighton authored
27 to install it. The binaries including a patched version of Qt 4.8 so you
28 don't need to install that separately.
ee1f46c @jonleighton Update the install / CI instructions
jonleighton authored
29
30 Note that if you have a 'dynamic' package, it's important to maintain
31 the relationship between `bin/phantomjs` and `lib/`. This is because the
32 `bin/phantomjs` binary looks in `../lib/` for its library files. So the
a4fa4bb @jonleighton Tweak README
jonleighton authored
33 best thing to do is to link (rather than copy) it into your `PATH`:
cf37abe @jonleighton Update the README
jonleighton authored
34
ee1f46c @jonleighton Update the install / CI instructions
jonleighton authored
35 ```
36 ln -s /path/to/phantomjs/bin/phantomjs /usr/local/bin/phantomjs
37 ```
cf37abe @jonleighton Update the README
jonleighton authored
38
ee1f46c @jonleighton Update the install / CI instructions
jonleighton authored
39 ### Compiling PhantomJS ###
cf37abe @jonleighton Update the README
jonleighton authored
40
ee1f46c @jonleighton Update the install / CI instructions
jonleighton authored
41 If you're having trouble with a pre-built binary package, you can
42 compile PhantomJS yourself. PhantomJS must be built against Qt 4.8, and
a4fa4bb @jonleighton Tweak README
jonleighton authored
43 some patches must be applied, so note that you cannot build it against
ee1f46c @jonleighton Update the install / CI instructions
jonleighton authored
44 your system install of Qt.
cf37abe @jonleighton Update the README
jonleighton authored
45
ee1f46c @jonleighton Update the install / CI instructions
jonleighton authored
46 [Download the tarball](http://code.google.com/p/phantomjs/downloads/detail?name=phantomjs-1.4.1-source.tar.gz&can=2&q=)
47 and run either `deploy/build-linux.sh --qt-4.8` or `cd deploy; ./build-mac.sh`.
48 The script will
49 download Qt, apply some patches, build it, and then build PhantomJS
50 against the patched build of Qt. It takes quite a while, around 30
51 minutes on a modern computer with two hyperthreaded cores. Afterwards,
52 you should copy (or link) the `bin/phantomjs` binary into your `PATH`.
53
54 ## Running on a CI ##
55
56 Currently PhantomJS is not 'truly headless', so to run it on a continuous integration
57 server you will need to install [Xvfb](http://en.wikipedia.org/wiki/Xvfb).
cf37abe @jonleighton Update the README
jonleighton authored
58
ee1f46c @jonleighton Update the install / CI instructions
jonleighton authored
59 ### On any generic server ###
cf37abe @jonleighton Update the README
jonleighton authored
60
ee1f46c @jonleighton Update the install / CI instructions
jonleighton authored
61 Install PhantomJS and invoke your tests with `xvfb-run`, (e.g. `xvfb-run
62 rake`).
cf37abe @jonleighton Update the README
jonleighton authored
63
ee1f46c @jonleighton Update the install / CI instructions
jonleighton authored
64 ### Using [Travis CI](http://travis-ci.org/) ###
cf37abe @jonleighton Update the README
jonleighton authored
65
ee1f46c @jonleighton Update the install / CI instructions
jonleighton authored
66 Travis CI has PhantomJS installed already! So all you need to do is add
67 the following to your `.travis.yml`:
cf37abe @jonleighton Update the README
jonleighton authored
68
ee1f46c @jonleighton Update the install / CI instructions
jonleighton authored
69 ``` yaml
70 before_script:
71 - "export DISPLAY=:99.0"
72 - "sh -e /etc/init.d/xvfb start"
73 ```
cf37abe @jonleighton Update the README
jonleighton authored
74
76fe32d @jonleighton omg
jonleighton authored
75 ## What's supported? ##
76
77 Poltergeist supports basically everything that is supported by the stock Selenium driver,
78 including Javascript, drag-and-drop, etc.
79
b18225d @jonleighton Add a resize command to allow users to resize the browser window
jonleighton authored
80 There are some additional features:
81
82 ### Taking screenshots ###
83
84 You can grab screenshots of the page at any point by calling
76fe32d @jonleighton omg
jonleighton authored
85 `page.driver.render('/path/to/file.png')` (this works the same way as the PhantomJS
86 render feature, so you can specify other extensions like `.pdf`, `.gif`, etc.)
87
fb497cb @jonleighton Add support for choosing between rendering the whole page or just par…
jonleighton authored
88 By default, only the viewport will be rendered (the part of the page that is in view). To render
89 the entire page, use `page.driver.render('/path/to/file.png', :full => true)`.
90
b18225d @jonleighton Add a resize command to allow users to resize the browser window
jonleighton authored
91 ### Resizing the window ###
92
93 Sometimes the window size is important to how things are rendered. Poltergeist sets the window
94 size to 1024x768 by default, but you can set this yourself with `page.driver.resize(width, height)`.
95
76fe32d @jonleighton omg
jonleighton authored
96 ## Customization ##
97
98 You can customize the way that Capybara sets up Poltegeist via the following code in your
99 test setup:
100
101 Capybara.register_driver :poltergeist do |app|
102 Capybara::Poltergeist::Driver.new(app, options)
103 end
104
105 `options` is a hash of options. The following options are supported:
106
107 * `:phantomjs` (String) - A custom path to the phantomjs executable
108 * `:debug` (Boolean) - When true, debug output is logged to `STDERR`
109 * `:logger` (Object responding to `puts`) - When present, debug output is written to this object
34af795 @jonleighton Stop using EventMachine for WebSocket server.
jonleighton authored
110 * `:timeout` (Numeric) - The number of seconds we'll wait for a response
111 when communicating with PhantomJS. `nil` means wait forever. Default
9f4192e @jonleighton Increase default timeout to 30
jonleighton authored
112 is 30.
76fe32d @jonleighton omg
jonleighton authored
113
114 ## Bugs ##
115
116 Please file bug reports on Github and include example code to reproduce the problem wherever
cf37abe @jonleighton Update the README
jonleighton authored
117 possible. (Tests are even better.) Please also provide the output with
118 `:debug` turned on, and screenshots if you think it's relevant.
76fe32d @jonleighton omg
jonleighton authored
119
120 ## Why not use [capybara-webkit](https://github.com/thoughtbot/capybara-webkit)? ##
121
122 If capybara-webkit works for you, then by all means carry on using it.
123
124 However, I have had some trouble with it, and Poltergeist basically started
125 as an experiment to see whether a PhantomJS driver was possible. (It turned out it
cf37abe @jonleighton Update the README
jonleighton authored
126 was, but only thanks to some new features since the 1.3 release.)
76fe32d @jonleighton omg
jonleighton authored
127
128 In the long term, I think having a PhantomJS driver makes sense, because that allows
129 PhantomJS to concentrate on being an awesome headless browser, while the capybara driver
130 (Poltergeist) is able to be the minimal amount of glue code necessary to drive the
131 browser.
132
cf37abe @jonleighton Update the README
jonleighton authored
133 I also find it more pleasant to hack in CoffeeScript than C++,
134 particularly as my C++ experience only goes as far as trying to make
135 PhantomJS/Qt/WebKit work with Poltergeist :)
136
137 ## Hacking ##
138
139 Contributions are very welcome and I will happily give commit access to
140 anyone who does a few good pull requests.
141
142 To get setup, run `bundle install`. You can run the full test suite with
143 `rspec spec/` or `rake`.
144
145 I previously set up the repository on [Travis CI](http://travis-ci.org/)
146 but unfortunately given they need a custom-built Qt+PhantomJS in order
147 to pass, it can't be used for now. When static Linux PhantomJS builds
148 are working this can be revisited.
149
150 While PhantomJS is capable of compiling and running CoffeeScript code
151 directly, I prefer to compile the code myself and distribute that (it
152 makes debugging easier). Running `rake autocompile` will watch the
153 `.coffee` files for changes, and compile them into
154 `lib/capybara/client/compiled`.
155
8ab5c03 @jonleighton Fix #8
jonleighton authored
156 ## Changes ##
157
48c3b97 @jonleighton Fix element position calculation. Fixes #15.
jonleighton authored
158 ### 0.4.0 (unreleased) #
159
160 * Element click position is now calculated using the native
161 `getBoundingClientRect()` method, which will be faster and less
162 buggy.
163
1938eac @jonleighton Handle window.prompt()
jonleighton authored
164 * Handle `window.confirm()`. Always returns true, which is the same
165 as capybara-webkit. [Issue #10]
166
167 * Handle `window.prompt()`. Returns the default value, if present, or
168 null.
0ebd617 @jonleighton Handle window.confirm. Fixes #10.
jonleighton authored
169
48c3b97 @jonleighton Fix element position calculation. Fixes #15.
jonleighton authored
170 ### 0.3.0 ###
8ab5c03 @jonleighton Fix #8
jonleighton authored
171
a4fa4bb @jonleighton Tweak README
jonleighton authored
172 * There was a bad bug to do with clicking elements in a page where the
173 page is smaller than the window. The incorrect position would be
174 calculated, and so the click would happen in the wrong place. This is
175 fixed. [Issue #8]
8ab5c03 @jonleighton Fix #8
jonleighton authored
176
a4fa4bb @jonleighton Tweak README
jonleighton authored
177 * Poltergeist didn't work in conjunction with the Thin web server,
178 because that server uses Event Machine, and Poltergeist was assuming
179 that it was the only thing in the process using EventMachine.
34af795 @jonleighton Stop using EventMachine for WebSocket server.
jonleighton authored
180
a4fa4bb @jonleighton Tweak README
jonleighton authored
181 To solve this, EventMachine usage has been completely removed, which
182 has the welcome side-effect of being more efficient because we
183 no longer have the overhead of running a mostly-idle event loop.
34af795 @jonleighton Stop using EventMachine for WebSocket server.
jonleighton authored
184
a4fa4bb @jonleighton Tweak README
jonleighton authored
185 [Issue #6]
34af795 @jonleighton Stop using EventMachine for WebSocket server.
jonleighton authored
186
a4fa4bb @jonleighton Tweak README
jonleighton authored
187 * Added the `:timeout` option to configure the timeout when talking to
188 PhantomJS.
34af795 @jonleighton Stop using EventMachine for WebSocket server.
jonleighton authored
189
48c3b97 @jonleighton Fix element position calculation. Fixes #15.
jonleighton authored
190 ### 0.2.0 ###
8ab5c03 @jonleighton Fix #8
jonleighton authored
191
a4fa4bb @jonleighton Tweak README
jonleighton authored
192 * First version considered 'ready', hopefully fewer problems.
8ab5c03 @jonleighton Fix #8
jonleighton authored
193
48c3b97 @jonleighton Fix element position calculation. Fixes #15.
jonleighton authored
194 ### 0.1.0 ###
8ab5c03 @jonleighton Fix #8
jonleighton authored
195
a4fa4bb @jonleighton Tweak README
jonleighton authored
196 * First version, various problems.
8ab5c03 @jonleighton Fix #8
jonleighton authored
197
76fe32d @jonleighton omg
jonleighton authored
198 ## License ##
199
200 Copyright (c) 2011 Jonathan Leighton
201
202 Permission is hereby granted, free of charge, to any person obtaining
203 a copy of this software and associated documentation files (the
204 "Software"), to deal in the Software without restriction, including
205 without limitation the rights to use, copy, modify, merge, publish,
206 distribute, sublicense, and/or sell copies of the Software, and to
207 permit persons to whom the Software is furnished to do so, subject to
208 the following conditions:
209
210 The above copyright notice and this permission notice shall be
211 included in all copies or substantial portions of the Software.
212
213 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
214 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
215 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
216 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
217 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
218 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
219 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.