Poltergeist - A PhantomJS driver for Capybara

Poltergeist is a driver for Capybara. It allows you to run your Capybara tests on a headless PhantomJS browser. If you would like to run your tests on headless Chrome there's another project Cuprite claims to be compatible with Poltergeist.

If you're viewing this at https://github.com/teampoltergeist/poltergeist, you're reading the documentation for the master branch. View documentation for the latest release (1.18.1).

Getting help

Questions should be posted on Stack Overflow, using the 'poltergeist' tag.

Bug reports should be posted on GitHub (and be sure to read the bug reporting guidance below).

Installation

Add this line to your Gemfile and run bundle install:

gem 'poltergeist'

In your test setup add:

require 'capybara/poltergeist'
Capybara.javascript_driver = :poltergeist

If you were previously using the :rack_test driver, be aware that your app will now run in a separate thread and this can have consequences for transactional tests. See the Capybara README for more detail.

Installing PhantomJS

You need at least PhantomJS 1.8.1. There are no other external dependencies (you don't need Qt, or a running X server, etc.)

Mac

• Homebrew: brew tap homebrew/cask && brew cask install phantomjs
• MacPorts: sudo port install phantomjs
• Manual install: Download this

Linux

• Download the 32 bit or 64 bit binary.
• Extract the tarball and copy bin/phantomjs into your PATH

DO NOT use phantomjs from the official Ubuntu repositories, since it doesn't work well with poltergeist. More information here.

Windows

• Download the precompiled binary for Windows

Manual compilation

Do this as a last resort if the binaries don't work for you. It will take quite a long time as it has to build WebKit.

• Download the source tarball
• Extract and cd in
• ./build.sh

(See also the PhantomJS building guide.)

Compatibility

Poltergeist runs on MRI 1.9+, JRuby 1.9+ and Rubinius 1.9+. Poltergeist and PhantomJS are currently supported on Mac OS X, Linux, and Windows platforms.

Ruby 1.8 is no longer supported. The last release to support Ruby 1.8 was 1.0.2, so you should use that if you still need Ruby 1.8 support.

PhantomJS does not support ES6 features at the time of writing this document. Setting js_errors to true can help determine if failing tests require Polyfills, although a bug in PhantomJS can cause silent failures if using ES6 features like let, const, etc.

Running on a CI

There are no special steps to take. You don't need Xvfb or any running X server at all.

Travis CI, CircleCI, Codeship and Semaphore have PhantomJS pre-installed.

Depending on your tests, one thing that you may need is some fonts. If you're getting errors on a CI that don't occur during development then try taking some screenshots - it may well be missing fonts throwing things off kilter. Your distro will have various font packages available to install.

What's supported?

Poltergeist supports all the mandatory features for a Capybara driver, and the following optional features:

• page.evaluate_script and page.execute_script
• page.within_frame
• page.status_code
• page.response_headers
• page.save_screenshot
• page.driver.render_base64(format, options)
• page.driver.scroll_to(left, top)
• page.driver.basic_authorize(user, password)
• element.send_keys(*keys)
• page.driver.set_proxy(ip, port, type, user, password)
• window API
• cookie handling
• drag-and-drop

There are some additional features:

Taking screenshots with some extensions

You can grab screenshots of the page at any point by calling save_screenshot('/path/to/file.png') (this works the same way as the PhantomJS render feature, so you can specify other extensions like .pdf, .gif, etc.) Just in case you render pdf it's might be worth to set driver.paper_size= with settings provided by PhantomJS in here

By default, only the viewport will be rendered (the part of the page that is in view). To render the entire page, use save_screenshot('/path/to/file.png', :full => true).

You also have an ability to render selected element. Pass option selector with any valid CSS element selector to make a screenshot bounded by that element save_screenshot('/path/to/file.png', :selector => '#id').

If you need for some reasons base64 encoded screenshot you can simply call render_base64 that will return you encoded image. Additional options are the same as for save_screenshot except the first argument which is format (:png by default, acceptable :png, :gif, :jpeg).

Clicking precise coordinates

Sometimes its desirable to click a very specific area of the screen. You can accomplish this with page.driver.click(x, y), where x and y are the screen coordinates.

Remote debugging (experimental)

If you use the :inspector => true option (see below), remote debugging will be enabled.

When this option is enabled, you can insert page.driver.debug into your tests to pause the test and launch a browser which gives you the WebKit inspector to view your test run with.

You can register this debugger driver with a different name and set it as the current javascript driver. By example, in your helper file:

Capybara.register_driver :poltergeist_debug do |app|
  Capybara::Poltergeist::Driver.new(app, :inspector => true)
end

# Capybara.javascript_driver = :poltergeist
Capybara.javascript_driver = :poltergeist_debug

Read more here

Manipulating request headers

You can manipulate HTTP request headers with these methods:

page.driver.headers # => {}
page.driver.headers = { "User-Agent" => "Poltergeist" }
page.driver.add_headers("Referer" => "https://example.com")
page.driver.headers # => { "User-Agent" => "Poltergeist", "Referer" => "https://example.com" }

Notice that headers= will overwrite already set headers. You should use add_headers if you want to add a few more. These headers will apply to all subsequent HTTP requests (including requests for assets, AJAX, etc). They will be automatically cleared at the end of the test. You have ability to set headers only for the initial request:

page.driver.headers = { "User-Agent" => "Poltergeist" }
page.driver.add_header("Referer", "http://example.com", permanent: false)
page.driver.headers # => { "User-Agent" => "Poltergeist", "Referer" => "http://example.com" }
visit(login_path)
page.driver.headers # => { "User-Agent" => "Poltergeist" }

This way your temporary headers will be sent only for the initial request, and related 30x redirects. All subsequent request will only contain your permanent headers. If the temporary headers should not be sent on related 30x redirects, specify permanent: :no_redirect.

Headers set with any of these methods will be set within all windows in the session, with the exception of temporary headers, which are only set within the current window.

Inspecting network traffic

You can inspect the network traffic (i.e. what resources have been loaded) on the current page by calling page.driver.network_traffic. This returns an array of request objects. A request object has a response_parts method containing data about the response chunks.

You can inspect requests that were blocked by a whitelist or blacklist by calling page.driver.network_traffic(:blocked). This returns an array of request objects. The response_parts portion of these requests will always be empty.

Please note that network traffic is not cleared when you visit new page. You can manually clear the network traffic by calling page.driver.clear_network_traffic or page.driver.reset

Manipulating cookies

The following methods are used to inspect and manipulate cookies:

• page.driver.cookies - a hash of cookies accessible to the current page. The keys are cookie names. The values are Cookie objects, with the following methods: name, value, domain, path, secure?, httponly?, samesite, expires.
• page.driver.set_cookie(name, value, options = {}) - set a cookie. The options hash can take the following keys: :domain, :path, :secure, :httponly, :samesite, :expires. :expires should be a Time object.
• page.driver.remove_cookie(name) - remove a cookie
• page.driver.clear_cookies - clear all cookies

Sending keys

There's an ability to send arbitrary keys to the element:

element = find('input#id')
element.send_keys('String')

or even more complicated:

element.send_keys('H', 'elo', :left, 'l') # => 'Hello'
element.send_keys(:enter) # triggers Enter key