Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 420 lines (316 sloc) 16.994 kB
76fe32d @jonleighton omg
jonleighton authored
1 # Poltergeist - A PhantomJS driver for Capybara #
2
bb1a8f4 @knappe Update README.md
knappe authored
3 [![Build Status](https://secure.travis-ci.org/teampoltergeist/poltergeist.png)](http://travis-ci.org/teampoltergeist/poltergeist)
7a71cc0 @jonleighton Add travis status image
jonleighton authored
4
76fe32d @jonleighton omg
jonleighton authored
5 Poltergeist is a driver for [Capybara](https://github.com/jnicklas/capybara). It allows you to
6 run your Capybara tests on a headless [WebKit](http://webkit.org) browser,
2995a1f @redbar0n Fix broken link to PhantomJS
redbar0n authored
7 provided by [PhantomJS](http://phantomjs.org/).
76fe32d @jonleighton omg
jonleighton authored
8
1eeae20 @tjschuck Update links to new repo URL
tjschuck authored
9 **If you're viewing this at https://github.com/teampoltergeist/poltergeist,
0e86acb @jonleighton Add link to latest release docs in README
jonleighton authored
10 you're reading the documentation for the master branch.
11 [View documentation for the latest release
c61b7ae @route Bump up [ci skip]
route authored
12 (1.6.0).](https://github.com/teampoltergeist/poltergeist/tree/v1.6.0)**
0e86acb @jonleighton Add link to latest release docs in README
jonleighton authored
13
efc6a2d @jonleighton Add 'getting help' section to README
jonleighton authored
14 ## Getting help ##
15
16 Questions should be posted [on Stack
17 Overflow, using the 'poltergeist' tag](http://stackoverflow.com/questions/tagged/poltergeist).
18
19 Bug reports should be posted [on
1eeae20 @tjschuck Update links to new repo URL
tjschuck authored
20 GitHub](https://github.com/teampoltergeist/poltergeist/issues) (and be sure
efc6a2d @jonleighton Add 'getting help' section to README
jonleighton authored
21 to read the bug reporting guidance below).
22
76fe32d @jonleighton omg
jonleighton authored
23 ## Installation ##
24
82d0fd0 @pjg Grammar fix in README
pjg authored
25 Add `poltergeist` to your Gemfile, and in your test setup add:
76fe32d @jonleighton omg
jonleighton authored
26
29291fc @jonleighton Update README
jonleighton authored
27 ``` ruby
28 require 'capybara/poltergeist'
29 Capybara.javascript_driver = :poltergeist
30 ```
31
77a789e @jonleighton Add note about transactional tests. Closes #78.
jonleighton authored
32 If you were previously using the `:rack_test` driver, be aware that
33 your app will now run in a separate thread and this can have
34 consequences for transactional tests. [See the Capybara README for more
35 detail](https://github.com/jnicklas/capybara/blob/master/README.md#transactions-and-database-setup).
36
cf37abe @jonleighton Update the README
jonleighton authored
37 ## Installing PhantomJS ##
38
09edc91 @brutuscat Add Capybara 2 compatibility
brutuscat authored
39 You need at least PhantomJS 1.8.1. There are *no other external
c2b48bb @jonleighton Fix version requirement [ci skip]
jonleighton authored
40 dependencies* (you don't need Qt, or a running X server, etc.)
b3367b4 @jonleighton Add note about PhantomJS 1.6
jonleighton authored
41
96b7af3 @jonleighton update readme
jonleighton authored
42 ### Mac ###
ee1f46c @jonleighton Update the install / CI instructions
jonleighton authored
43
f26f903 @jonleighton bump to 0.7.0
jonleighton authored
44 * *Homebrew*: `brew install phantomjs`
9e7b29a @sahilm Document installation of phantomjs via MacPorts.
sahilm authored
45 * *MacPorts*: `sudo port install phantomjs`
3b7e70e @obfuscoder Update PhantomJS links to version 1.9.8
obfuscoder authored
46 * *Manual install*: [Download this](https://bitbucket.org/ariya/phantomjs/downloads/phantomjs-1.9.8-macosx.zip)
ee1f46c @jonleighton Update the install / CI instructions
jonleighton authored
47
96b7af3 @jonleighton update readme
jonleighton authored
48 ### Linux ###
cf37abe @jonleighton Update the README
jonleighton authored
49
3b7e70e @obfuscoder Update PhantomJS links to version 1.9.8
obfuscoder authored
50 * Download the [32 bit](https://bitbucket.org/ariya/phantomjs/downloads/phantomjs-1.9.8-linux-i686.tar.bz2)
51 or [64 bit](https://bitbucket.org/ariya/phantomjs/downloads/phantomjs-1.9.8-linux-x86_64.tar.bz2)
96b7af3 @jonleighton update readme
jonleighton authored
52 binary.
1738970 @jonleighton Troubleshooting guide. Closes #167. [ci skip]
jonleighton authored
53 * Extract the tarball and copy `bin/phantomjs` into your `PATH`
cf37abe @jonleighton Update the README
jonleighton authored
54
7b44965 Windows support
Aaron Tull authored
55 ### Windows ###
3b7e70e @obfuscoder Update PhantomJS links to version 1.9.8
obfuscoder authored
56 * Download the [precompiled binary](https://bitbucket.org/ariya/phantomjs/downloads/phantomjs-1.9.8-windows.zip)
00f7b2a @route Update the other links on PhantomJS builds [ci skip]
route authored
57 for Windows
7b44965 Windows support
Aaron Tull authored
58
96b7af3 @jonleighton update readme
jonleighton authored
59 ### Manual compilation ###
cf37abe @jonleighton Update the README
jonleighton authored
60
96b7af3 @jonleighton update readme
jonleighton authored
61 Do this as a last resort if the binaries don't work for you. It will
62 take quite a long time as it has to build WebKit.
63
3b7e70e @obfuscoder Update PhantomJS links to version 1.9.8
obfuscoder authored
64 * Download [the source tarball](https://bitbucket.org/ariya/phantomjs/downloads/phantomjs-1.9.8-source.zip)
96b7af3 @jonleighton update readme
jonleighton authored
65 * Extract and cd in
66 * `./build.sh`
ee1f46c @jonleighton Update the install / CI instructions
jonleighton authored
67
1738970 @jonleighton Troubleshooting guide. Closes #167. [ci skip]
jonleighton authored
68 (See also the [PhantomJS building
69 guide](http://phantomjs.org/build.html).)
a606a27 @jonleighton tweak readme [ci skip]
jonleighton authored
70
1738970 @jonleighton Troubleshooting guide. Closes #167. [ci skip]
jonleighton authored
71 ## Compatibility ##
a606a27 @jonleighton tweak readme [ci skip]
jonleighton authored
72
7b44965 Windows support
Aaron Tull authored
73 Poltergeist runs on MRI 1.9, JRuby 1.9 and Rubinius 1.9. Poltergeist
74 and PhantomJS are currently supported on Mac OS X, Linux, and Windows
75 platforms.
a606a27 @jonleighton tweak readme [ci skip]
jonleighton authored
76
e61a8e7 @jonleighton We're ruby 1.9 only now
jonleighton authored
77 Ruby 1.8 is no longer supported. The last release to support Ruby 1.8
78 was 1.0.2, so you should use that if you still need Ruby 1.8 support.
a606a27 @jonleighton tweak readme [ci skip]
jonleighton authored
79
ee1f46c @jonleighton Update the install / CI instructions
jonleighton authored
80 ## Running on a CI ##
81
96b7af3 @jonleighton update readme
jonleighton authored
82 There are no special steps to take. You don't need Xvfb or any running X
83 server at all.
cf37abe @jonleighton Update the README
jonleighton authored
84
b3fdd48 @justincampbell Remove .travis.yml instructions
justincampbell authored
85 [Travis CI](https://travis-ci.org/) has PhantomJS pre-installed.
1738970 @jonleighton Troubleshooting guide. Closes #167. [ci skip]
jonleighton authored
86
5d89eb7 @jonleighton some readme tweaks [ci skip]
jonleighton authored
87 Depending on your tests, one thing that you may need is some fonts. If
88 you're getting errors on a CI that don't occur during development then
89 try taking some screenshots - it may well be missing fonts throwing
90 things off kilter. Your distro will have various font packages available
91 to install.
cf37abe @jonleighton Update the README
jonleighton authored
92
76fe32d @jonleighton omg
jonleighton authored
93 ## What's supported? ##
94
2e0332f @jonleighton readme tweaks
jonleighton authored
95 Poltergeist supports all the mandatory features for a Capybara driver,
96 and the following optional features:
97
98 * `page.evaluate_script` and `page.execute_script`
99 * `page.within_frame`
100 * `page.status_code`
101 * `page.response_headers`
7c6da3f @tricknotes `save_screenshot` is public API in Capybara
tricknotes authored
102 * `page.save_screenshot`
fc7cc73 @route Fix #263 HTTP Basic Authentication
route authored
103 * `page.driver.render_base64(format, options)`
104 * `page.driver.scroll_to(left, top)`
105 * `page.driver.basic_authorize(user, password)`
852b78a @route #202 Add send_keys basic implementation
route authored
106 * `element.native.send_keys(*keys)`
2d23867 @route Add window support
route authored
107 * window API
2e0332f @jonleighton readme tweaks
jonleighton authored
108 * cookie handling
109 * drag-and-drop
76fe32d @jonleighton omg
jonleighton authored
110
b18225d @jonleighton Add a resize command to allow users to resize the browser window
jonleighton authored
111 There are some additional features:
112
7c6da3f @tricknotes `save_screenshot` is public API in Capybara
tricknotes authored
113 ### Taking screenshots with some extensions ###
b18225d @jonleighton Add a resize command to allow users to resize the browser window
jonleighton authored
114
115 You can grab screenshots of the page at any point by calling
7c6da3f @tricknotes `save_screenshot` is public API in Capybara
tricknotes authored
116 `save_screenshot('/path/to/file.png')` (this works the same way as the PhantomJS
76fe32d @jonleighton omg
jonleighton authored
117 render feature, so you can specify other extensions like `.pdf`, `.gif`, etc.)
24e154a @route Add missed change log and readme entries [ci skip]
route authored
118 Just in case you render pdf it's might be worth to set `driver.paper_size=` with
119 settings provided by PhantomJS in [here](https://github.com/ariya/phantomjs/wiki/API-Reference-WebPage#wiki-webpage-paperSize)
76fe32d @jonleighton omg
jonleighton authored
120
24e154a @route Add missed change log and readme entries [ci skip]
route authored
121 By default, only the viewport will be rendered (the part of the page that is in
122 view). To render the entire page, use `save_screenshot('/path/to/file.png',
123 :full => true)`.
fb497cb @jonleighton Add support for choosing between rendering the whole page or just par…
jonleighton authored
124
6de3542 @route Mention `scroll_to` and additional option for `render` in README [ci …
route authored
125 You also have an ability to render selected element. Pass option `selector` with
126 any valid element selector to make a screenshot bounded by that element
127 `save_screenshot('/path/to/file.png', :selector => '#id')`.
128
5a05b67 @jimjh Add support for phantom's #renderBase64.
jimjh authored
129 If you need for some reasons base64 encoded screenshot you can simply call
130 `render_base64` that will return you encoded image. Additional options are the
131 same as for `save_screenshot` except the first argument which is format (:png by
132 default, acceptable :png, :gif, :jpeg).
133
4712368 @botandrose Support clicking precise coordinates.
botandrose authored
134 ### Clicking precise coordinates ###
135
136 Sometimes its desirable to click a very specific area of the screen. You can accomplish this with
137 `page.driver.click(x, y)`, where x and y are the screen coordinates.
138
96b7af3 @jonleighton update readme
jonleighton authored
139 ### Remote debugging (experimental) ###
140
141 If you use the `:inspector => true` option (see below), remote debugging
142 will be enabled.
143
144 When this option is enabled, you can insert `page.driver.debug` into
145 your tests to pause the test and launch a browser which gives you the
146 WebKit inspector to view your test run with.
147
e84da5e Fix typo
Miguel authored
148 You can register this debugger driver with a different name and set it
149 as the current javascript driver. By example, in your helper file:
1204034 @cibernox Clarify how to enable the debug mode in the readme
cibernox authored
150
151 ```ruby
152 Capybara.register_driver :poltergeist_debug do |app|
153 Capybara::Poltergeist::Driver.new(app, :inspector => true)
154 end
155
156 # Capybara.javascript_driver = :poltergeist
157 Capybara.javascript_driver = :poltergeist_debug
158 ```
159
5d89eb7 @jonleighton some readme tweaks [ci skip]
jonleighton authored
160 [Read more
161 here](http://jonathanleighton.com/articles/2012/poltergeist-0-6-0/)
162
5e65732 @route Fix #187 ability to read and append request headers
route authored
163 ### Manipulating request headers ###
eb484d4 @jonleighton Tweak the HTTP header documentation
jonleighton authored
164
5e65732 @route Fix #187 ability to read and append request headers
route authored
165 You can manipulate HTTP request headers with these methods:
eb484d4 @jonleighton Tweak the HTTP header documentation
jonleighton authored
166
167 ``` ruby
5e65732 @route Fix #187 ability to read and append request headers
route authored
168 page.driver.headers # => {}
c664c60 @jonleighton Implement cookie manipulation. Closes #12.
jonleighton authored
169 page.driver.headers = { "User-Agent" => "Poltergeist" }
5e65732 @route Fix #187 ability to read and append request headers
route authored
170 page.driver.add_headers("Referer" => "https://example.com")
171 page.driver.headers # => { "User-Agent" => "Poltergeist", "Referer" => "https://example.com" }
eb484d4 @jonleighton Tweak the HTTP header documentation
jonleighton authored
172 ```
911384a @jonleighton add doc for network traffic feature
jonleighton authored
173
5e65732 @route Fix #187 ability to read and append request headers
route authored
174 Notice that `headers=` will overwrite already set headers. You should use
ab5f757 @route Fix #337 ability to set headers only on the initial request
route authored
175 `add_headers` if you want to add a few more. These headers will apply to all
5e65732 @route Fix #187 ability to read and append request headers
route authored
176 subsequent HTTP requests (including requests for assets, AJAX, etc). They will
ab5f757 @route Fix #337 ability to set headers only on the initial request
route authored
177 be automatically cleared at the end of the test. You have ability to set headers
178 only for the initial request:
179
180 ``` ruby
181 page.driver.headers = { "User-Agent" => "Poltergeist" }
182 page.driver.add_header("Referer", "http://example.com", permanent: false)
183 page.driver.headers # => { "User-Agent" => "Poltergeist", "Referer" => "http://example.com" }
184 visit(login_path)
185 page.driver.headers # => { "User-Agent" => "Poltergeist" }
186 ```
187
188 This way your temporary headers will be sent only for the initial request, all
189 subsequent request will only contain your permanent headers.
eb484d4 @jonleighton Tweak the HTTP header documentation
jonleighton authored
190
911384a @jonleighton add doc for network traffic feature
jonleighton authored
191 ### Inspecting network traffic ###
192
193 You can inspect the network traffic (i.e. what resources have been
194 loaded) on the current page by calling `page.driver.network_traffic`.
195 This returns an array of request objects. A request object has a
196 `response_parts` method containing data about the response chunks.
ff0a744 @vickvu Add clear_network_traffic command
vickvu authored
197 Please note that network traffic is not cleared when you visit new page.
198 You can manually clear the network traffic by calling `page.driver.clear_network_traffic`
199 or `page.driver.reset`
911384a @jonleighton add doc for network traffic feature
jonleighton authored
200
c664c60 @jonleighton Implement cookie manipulation. Closes #12.
jonleighton authored
201 ### Manipulating cookies ###
202
203 The following methods are used to inspect and manipulate cookies:
204
205 * `page.driver.cookies` - a hash of cookies accessible to the current
206 page. The keys are cookie names. The values are `Cookie` objects, with
207 the following methods: `name`, `value`, `domain`, `path`, `secure?`,
208 `httponly?`, `expires`.
209 * `page.driver.set_cookie(name, value, options = {})` - set a cookie.
210 The options hash can take the following keys: `:domain`, `:path`,
211 `:secure`, `:httponly`, `:expires`. `:expires` should be a `Time`
212 object.
213 * `page.driver.remove_cookie(name)` - remove a cookie
54f30e8 @unmanbearpig Added clear_cookies to the readme
unmanbearpig authored
214 * `page.driver.clear_cookies` - clear all cookies
c664c60 @jonleighton Implement cookie manipulation. Closes #12.
jonleighton authored
215
852b78a @route #202 Add send_keys basic implementation
route authored
216 ### Sending keys ###
217
218 There's an ability to send arbitrary keys to the element:
219
220 ``` ruby
221 element = find('input#id')
222 element.native.send_key('String')
223 ```
224
225 or even more complicated:
226
227 ``` ruby
228 element.native.send_keys('H', 'elo', :Left, 'l') # => 'Hello'
229 element.native.send_key(:Enter) # triggers Enter key
230 ```
231 Since it's implemented natively in PhantomJS this will exactly imitate user
232 behavior.
233 See more about [sendEvent](http://phantomjs.org/api/webpage/method/send-event.html) and
234 [PhantomJS keys](https://github.com/ariya/phantomjs/commit/cab2635e66d74b7e665c44400b8b20a8f225153a)
4e2b6a0 @juanger New feature. window_handles returns the list of open windows names
juanger authored
235
76fe32d @jonleighton omg
jonleighton authored
236 ## Customization ##
237
293f61b @bbasata Update README.md
bbasata authored
238 You can customize the way that Capybara sets up Poltergeist via the following code in your
76fe32d @jonleighton omg
jonleighton authored
239 test setup:
240
29291fc @jonleighton Update README
jonleighton authored
241 ``` ruby
242 Capybara.register_driver :poltergeist do |app|
243 Capybara::Poltergeist::Driver.new(app, options)
244 end
245 ```
76fe32d @jonleighton omg
jonleighton authored
246
247 `options` is a hash of options. The following options are supported:
248
29291fc @jonleighton Update README
jonleighton authored
249 * `:phantomjs` (String) - A custom path to the phantomjs executable
b34c9cf @jonleighton Add extra debug info
jonleighton authored
250 * `:debug` (Boolean) - When true, debug output is logged to `STDERR`.
251 Some debug info from the PhantomJS portion of Poltergeist is also
252 output, but this goes to `STDOUT` due to technical limitations.
29291fc @jonleighton Update README
jonleighton authored
253 * `:logger` (Object responding to `puts`) - When present, debug output is written to this object
ceaecc2 @jonleighton readme tweaking
jonleighton authored
254 * `:phantomjs_logger` (`IO` object) - Where the `STDOUT` from PhantomJS is written to. This is
8a21c22 @route Fix typo
route authored
255 where your `console.log` statements will show up. Default: `STDOUT`
29291fc @jonleighton Update README
jonleighton authored
256 * `:timeout` (Numeric) - The number of seconds we'll wait for a response
49d1dbc @jonleighton :timeout cannot be set to nil
jonleighton authored
257 when communicating with PhantomJS. Default is 30.
96b7af3 @jonleighton update readme
jonleighton authored
258 * `:inspector` (Boolean, String) - See 'Remote Debugging', above.
7d6cde7 @rentalcustard Rename raise_errors -> js_errors
rentalcustard authored
259 * `:js_errors` (Boolean) - When false, Javascript errors do not get re-raised in Ruby.
0db1eb9 @rentalcustard Allow passing desired browser size as an option
rentalcustard authored
260 * `:window_size` (Array) - The dimensions of the browser window in which to test, expressed
261 as a 2-element array, e.g. [1024, 768]. Default: [1024, 768]
6de5f13 @ngauthier Fix command line options link
ngauthier authored
262 * `:phantomjs_options` (Array) - Additional [command line options](http://phantomjs.org/api/command-line.html)
97b1aca @jonleighton Make command line options less prominent in readme. It's not a headli…
jonleighton authored
263 to be passed to PhantomJS, e.g. `['--load-images=no', '--ignore-ssl-errors=yes']`
db2bc04 @JonRowe Allow the extension of the PhantomJS driver with custom JS includes:
JonRowe authored
264 * `:extensions` (Array) - An array of JS files to be preloaded into
265 the phantomjs browser. Useful for faking unsupported APIs.
78ce1cc @jonleighton Make the port used deterministic
jonleighton authored
266 * `:port` (Fixnum) - The port which should be used to communicate
f936825 @thedelchop Update README
thedelchop authored
267 with the PhantomJS process. Defaults to a random open port.
76fe32d @jonleighton omg
jonleighton authored
268
de1e49f @acconrad Update README to include URL blacklisting [ci skip]
acconrad authored
269 ### URL Blacklisting ###
270
548eb4d @espen no need to specify "latest version" here
espen authored
271 Poltergeist supports URL blacklisting which allows you
de1e49f @acconrad Update README to include URL blacklisting [ci skip]
acconrad authored
272 to prevent scripts from running on designated domains. If you are experiencing
273 slower run times, consider creating a URL blacklist of domains that are not
274 essential to your testing environment, such as ad networks or analytics.
275
276 ```ruby
277 page.driver.browser.url_blacklist = ['http://www.example.com']
278 ```
279
280 Make sure you set it before each running test, because this setting's cleaned
281 up when capybara does reset.
282
1738970 @jonleighton Troubleshooting guide. Closes #167. [ci skip]
jonleighton authored
283 ## Troubleshooting ##
284
285 Unfortunately, the nature of full-stack testing is that things can and
286 do go wrong from time to time. This section aims to highlight a number
287 of common problems and provide ideas about how you can work around them.
288
289 ### DeadClient errors ###
290
291 Sometimes PhantomJS crashes during a test. There are basically two kinds
292 of crashes: those that can be reproduced every time, and those that
293 occur sporadically and are not easily reproduced.
294
295 If your crash happens every time, you should read the [PhantomJS crash
296 reporting
57b733d @route Add fresh links to README [ci skip]
route authored
297 guide](http://phantomjs.org/crash-reporting.html) and file
1738970 @jonleighton Troubleshooting guide. Closes #167. [ci skip]
jonleighton authored
298 a bug against PhantomJS. Feel free to also file a bug against
299 Poltergeist in case there are workarounds that can be implemented within
300 Poltergeist. Also, if lots of Poltergeist users are experiencing the
952baf7 @jonleighton readme copy-edits [ci skip]
jonleighton authored
301 same crash then fixing it will move up the priority list.
1738970 @jonleighton Troubleshooting guide. Closes #167. [ci skip]
jonleighton authored
302
303 If your crash is sporadic, there is less that can be done. Often these
304 issues are very complicated and difficult to track down. It may be that
305 the crash has already been fixed in a newer version of WebKit that will
306 eventually find its way into PhantomJS. It's still worth reporting your
952baf7 @jonleighton readme copy-edits [ci skip]
jonleighton authored
307 bug against PhantomJS, but it's probably not worth filing a bug against
1738970 @jonleighton Troubleshooting guide. Closes #167. [ci skip]
jonleighton authored
308 Poltergeist as there's not much we can do.
309
952baf7 @jonleighton readme copy-edits [ci skip]
jonleighton authored
310 If you experience sporadic crashes a lot, it may be worth configuring
1738970 @jonleighton Troubleshooting guide. Closes #167. [ci skip]
jonleighton authored
311 your CI to automatically re-run failing tests before reporting a failed
312 build.
313
6c52e69 @jonleighton Implement #hover
jonleighton authored
314 ### MouseEventFailed errors ###
1738970 @jonleighton Troubleshooting guide. Closes #167. [ci skip]
jonleighton authored
315
316 When Poltergeist clicks on an element, rather than generating a DOM
317 click event, it actually generates a "proper" click. This is much closer
318 to what happens when a real user clicks on the page - but it means that
319 Poltergeist must scroll the page to where the element is, and work out
952baf7 @jonleighton readme copy-edits [ci skip]
jonleighton authored
320 the correct co-ordinates to click. If the element is covered up by
1738970 @jonleighton Troubleshooting guide. Closes #167. [ci skip]
jonleighton authored
321 another element, the click will fail (this is a good thing - because
322 your user won't be able to click a covered up element either).
323
324 Sometimes there can be issues with this behavior. If you have problems,
325 it's worth taking screenshots of the page and trying to work out what's
326 going on. If your click is failing, but you're not getting a
6c52e69 @jonleighton Implement #hover
jonleighton authored
327 `MouseEventFailed` error, then you can turn on the `:debug` option and look
1738970 @jonleighton Troubleshooting guide. Closes #167. [ci skip]
jonleighton authored
328 in the output to see what co-ordinates Poltergeist is using for the
329 click. You can then cross-reference this with a screenshot to see if
330 something is obviously wrong.
331
952baf7 @jonleighton readme copy-edits [ci skip]
jonleighton authored
332 If you can't figure out what's going on and just want to work around the
333 problem so you can get on with life, consider using a DOM click
334 event. For example, if this code is failing:
1738970 @jonleighton Troubleshooting guide. Closes #167. [ci skip]
jonleighton authored
335
336 ``` ruby
337 click_button "Save"
338 ```
76fe32d @jonleighton omg
jonleighton authored
339
1738970 @jonleighton Troubleshooting guide. Closes #167. [ci skip]
jonleighton authored
340 Then try:
76fe32d @jonleighton omg
jonleighton authored
341
1738970 @jonleighton Troubleshooting guide. Closes #167. [ci skip]
jonleighton authored
342 ``` ruby
343 find_button("Save").trigger('click')
344 ```
cf37abe @jonleighton Update the README
jonleighton authored
345
1738970 @jonleighton Troubleshooting guide. Closes #167. [ci skip]
jonleighton authored
346 ### Timing problems ###
347
348 Sometimes tests pass and fail sporadically. This is often because there
349 is some problem synchronising events properly. It's often
350 straightforward to verify this by adding `sleep` statements into your
351 test to allow sufficient time for the page to settle.
352
353 If you have these types of problems, read through the [Capybara
952baf7 @jonleighton readme copy-edits [ci skip]
jonleighton authored
354 documentation on asynchronous
1738970 @jonleighton Troubleshooting guide. Closes #167. [ci skip]
jonleighton authored
355 Javascript](https://github.com/jnicklas/capybara#asynchronous-javascript-ajax-and-friends)
356 which explains the tools that Capybara provides for dealing with this.
357
98e2483 @route Add memory leakage section to README
route authored
358 ### Memory leak ###
359
360 If you run a few capybara sessions manually please make sure you've called
361 `session.driver.quit` when you don't need session anymore. Forgetting about this
362 causes memory leakage and your system's resources can be exhausted earlier than
363 you may expect.
364
1738970 @jonleighton Troubleshooting guide. Closes #167. [ci skip]
jonleighton authored
365 ### General troubleshooting hints ###
366
367 * Configure Poltergeist with `:debug` turned on so you can see its
368 communication with PhantomJS.
369 * Take screenshots to figure out what the state of your page is when the
370 problem occurs.
ed7e723 @jonleighton mention web inspector [ci skip]
jonleighton authored
371 * Use the remote web inspector in case it provides any useful insight
1738970 @jonleighton Troubleshooting guide. Closes #167. [ci skip]
jonleighton authored
372 * Consider downloading the Poltergeist source and using `console.log`
373 debugging to figure out what's going on inside PhantomJS. (This will
374 require an understanding of the Poltergeist source code and PhantomJS,
375 so it's only for the committed!)
376
377 ### Filing a bug ###
378
379 If you can provide specific steps to reproduce your problem, or have
380 specific information that might help other help you track down the
381 problem, then please file a bug on Github.
382
952baf7 @jonleighton readme copy-edits [ci skip]
jonleighton authored
383 Include as much information as possible. For example:
1738970 @jonleighton Troubleshooting guide. Closes #167. [ci skip]
jonleighton authored
384
385 * Specific steps to reproduce where possible (failing tests are even
386 better)
952baf7 @jonleighton readme copy-edits [ci skip]
jonleighton authored
387 * The output obtained from running Poltergeist with `:debug` turned on
388 * Screenshots
389 * Stack traces if there are any Ruby on Javascript exceptions generated
390 * The Poltergeist and PhantomJS version numbers used
391 * The operating system name and version used
1738970 @jonleighton Troubleshooting guide. Closes #167. [ci skip]
jonleighton authored
392
8ab5c03 @jonleighton Fix #8
jonleighton authored
393 ## Changes ##
394
1c28164 @route Move CHANGES section into separate file [ci skip]
route authored
395 Version history and a list of next-release features and fixes can be found in
396 the [changelog](CHANGELOG.md).
8ab5c03 @jonleighton Fix #8
jonleighton authored
397
76fe32d @jonleighton omg
jonleighton authored
398 ## License ##
399
6babcfb @parndt We made it to 2015!
parndt authored
400 Copyright (c) 2011-2015 Jonathan Leighton
76fe32d @jonleighton omg
jonleighton authored
401
402 Permission is hereby granted, free of charge, to any person obtaining
403 a copy of this software and associated documentation files (the
404 "Software"), to deal in the Software without restriction, including
405 without limitation the rights to use, copy, modify, merge, publish,
406 distribute, sublicense, and/or sell copies of the Software, and to
407 permit persons to whom the Software is furnished to do so, subject to
408 the following conditions:
409
410 The above copyright notice and this permission notice shall be
411 included in all copies or substantial portions of the Software.
412
413 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
414 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
415 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
416 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
417 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
418 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
419 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.