<commit_before># Poltergeist - A PhantomJS driver for Capybara #

Version: 0.5.0

[![Build Status](https://secure.travis-ci.org/jonleighton/poltergeist.png)](http://travis-ci.org/jonleighton/poltergeist)
[![Dependency Status](https://gemnasium.com/jonleighton/poltergeist.png)](https://gemnasium.com/jonleighton/poltergeist)

Poltergeist is a driver for [Capybara](https://github.com/jnicklas/capybara). It allows you to
run your Capybara tests on a headless [WebKit](http://webkit.org) browser,
provided by [PhantomJS](http://www.phantomjs.org/).

## Installation ##

Add `poltergeist` to your Gemfile, and in your test setup add:

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

## Important note about Rack versions < 1.3.0 ##

Prior to version 1.3.0, the Rack handlers for Mongrel and Thin wrap your
app in the `Rack::Chunked` middleware so that it uses
`Transfer-Encoding: chunked`
([commit](https://github.com/rack/rack/commit/50cdd0bf000a9ffb3eb3760fda2ff3e1ad18f3a7)).
This has been observed to cause problems,
probably due to race conditions in Qt's HTTP handling code, so you are
recommended to avoid this by specifying your own server setup for
Capybara:

``` ruby
Capybara.server do |app, port|
  require 'rack/handler/thin'
  Thin::Logging.silent = true
  Thin::Server.new('0.0.0.0', port, app).start
end
```

If you're using Rails 3.0, this affects you. If you're using Rails 3.1+,
this doesn't affect you.

## Installing PhantomJS ##

You need PhantomJS 1.4.1+, built against Qt 4.8, on your system.

### Pre-built binaries ##

There are [pre-built
binaries](http://code.google.com/p/phantomjs/downloads/list) of
PhantomJS for Linux, Mac and Windows. This is the easiest and best way
to install it. The binaries including a patched version of Qt 4.8 so you
don't need to install that separately.

Note that if you have a 'dynamic' package, it's important to maintain
the relationship between `bin/phantomjs` and `lib/`. This is because the
`bin/phantomjs` binary looks in `../lib/` for its library files. So the
best thing to do is to link (rather than copy) it into your `PATH`:

    ln -s /path/to/phantomjs/bin/phantomjs /usr/local/bin/phantomjs

### Compiling PhantomJS ###

If you're having trouble with a pre-built binary package, you can
compile PhantomJS yourself. PhantomJS must be built against Qt 4.8, and
some patches must be applied, so note that you cannot build it against
your system install of Qt.

[Download the tarball](http://code.google.com/p/phantomjs/downloads/detail?name=phantomjs-1.4.1-source.tar.gz&can=2&q=)
and run either `deploy/build-linux.sh --qt-4.8` or `cd deploy; ./build-mac.sh`.
The script will
download Qt, apply some patches, build it, and then build PhantomJS
against the patched build of Qt. It takes quite a while, around 30
minutes on a modern computer with two hyperthreaded cores. Afterwards,
you should copy (or link) the `bin/phantomjs` binary into your `PATH`.

## Compatibility ##

Supported: MRI 1.8.7, MRI 1.9.2, MRI 1.9.3, JRuby 1.8, JRuby 1.9.

Not supported:

* Rubinius (due to some unknown socket related issues)
* Windows

Anyone else welcome to contribute in order to move an 'unsupported'
items into the 'supported' list.

## Running on a CI ##

Currently PhantomJS is not yet 'truly headless' (but that's planned for the future),
so to run it on a continuous integration
server you will need to install [Xvfb](http://en.wikipedia.org/wiki/Xvfb).

### On any generic server ###

Install PhantomJS and invoke your tests with `xvfb-run`, (e.g. `xvfb-run
rake`).

### Using [Travis CI](http://travis-ci.org/) ###

Travis CI has PhantomJS installed already! So all you need to do is add
the following to your `.travis.yml`:

``` yaml
before_script:
  - "export DISPLAY=:99.0"
  - "sh -e /etc/init.d/xvfb start"
```

## What's supported? ##

Poltergeist supports basically everything that is supported by the stock Selenium driver,
including Javascript, drag-and-drop, etc.

There are some additional features:
<commit_msg>tweak readme [ci skip]<commit_after># Poltergeist - A PhantomJS driver for Capybara #

Version: 0.5.0

[![Build Status](https://secure.travis-ci.org/jonleighton/poltergeist.png)](http://travis-ci.org/jonleighton/poltergeist)
[![Dependency Status](https://gemnasium.com/jonleighton/poltergeist.png)](https://gemnasium.com/jonleighton/poltergeist)

Poltergeist is a driver for [Capybara](https://github.com/jnicklas/capybara). It allows you to
run your Capybara tests on a headless [WebKit](http://webkit.org) browser,
provided by [PhantomJS](http://www.phantomjs.org/).

## Installation ##

Add `poltergeist` to your Gemfile, and in your test setup add:

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

## Important note about Rack versions < 1.3.0 ##

Prior to version 1.3.0, the Rack handlers for Mongrel and Thin wrap your
app in the `Rack::Chunked` middleware so that it uses
`Transfer-Encoding: chunked`
([commit](https://github.com/rack/rack/commit/50cdd0bf000a9ffb3eb3760fda2ff3e1ad18f3a7)).
This has been observed to cause problems,
probably due to race conditions in Qt's HTTP handling code, so you are
recommended to avoid this by specifying your own server setup for
Capybara:

``` ruby
Capybara.server do |app, port|
  require 'rack/handler/thin'
  Thin::Logging.silent = true
  Thin::Server.new('0.0.0.0', port, app).start
end
```

If you're using Rails 3.0, this affects you. If you're using Rails 3.1+,
this doesn't affect you.

## Installing PhantomJS ##

You need PhantomJS 1.4.1+, built against Qt 4.8, on your system.

### Pre-built binaries ##

There are [pre-built
binaries](http://code.google.com/p/phantomjs/downloads/list) of
PhantomJS for Linux, Mac and Windows. This is the easiest and best way
to install it. The binaries including a patched version of Qt 4.8 so you
don't need to install that separately.

Note that if you have a 'dynamic' package, it's important to maintain
the relationship between `bin/phantomjs` and `lib/`. This is because the
`bin/phantomjs` binary looks in `../lib/` for its library files. So the
best thing to do is to link (rather than copy) it into your `PATH`:

    ln -s /path/to/phantomjs/bin/phantomjs /usr/local/bin/phantomjs

### Compiling PhantomJS ###

If you're having trouble with a pre-built binary package, you can
compile PhantomJS yourself. PhantomJS must be built against Qt 4.8, and
some patches must be applied, so note that you cannot build it against
your system install of Qt.

[Download the tarball](http://code.google.com/p/phantomjs/downloads/detail?name=phantomjs-1.4.1-source.tar.gz&can=2&q=)
and run either `deploy/build-linux.sh --qt-4.8` or `cd deploy; ./build-mac.sh`.
The script will
download Qt, apply some patches, build it, and then build PhantomJS
against the patched build of Qt. It takes quite a while, around 30
minutes on a modern computer with two hyperthreaded cores. Afterwards,
you should copy (or link) the `bin/phantomjs` binary into your `PATH`.

## Compatibility ##

Supported: MRI 1.8.7, MRI 1.9.2, MRI 1.9.3, JRuby 1.8, JRuby 1.9.

Not supported:

* Rubinius (due to some unknown socket related issues)
* Windows

Contributions are welcome in order to move 'unsupported'
items into the 'supported' list.

## Running on a CI ##

Currently PhantomJS is not yet 'truly headless' (but that's planned for the future),
so to run it on a continuous integration
server you will need to install [Xvfb](http://en.wikipedia.org/wiki/Xvfb).

### On any generic server ###

Install PhantomJS and invoke your tests with `xvfb-run`, (e.g. `xvfb-run
rake`).

### Using [Travis CI](http://travis-ci.org/) ###

Travis CI has PhantomJS installed already! So all you need to do is add
the following to your `.travis.yml`:

``` yaml
before_script:
  - "export DISPLAY=:99.0"
  - "sh -e /etc/init.d/xvfb start"
```

## What's supported? ##

Poltergeist supports basically everything that is supported by the stock Selenium driver,
including Javascript, drag-and-drop, etc.

There are some additional features:

{'fraction_non_alphanumeric': 0.11265508684863523, 'fraction_numerical': 0.017121588089330026, 'mean_word_length': 4.334877564526804, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 3, 'https://': 10, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 8, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6825092', 'n_tokens_mistral': 2809, 'n_tokens_neox': 2612, 'n_words': 982}