Ghost Driver is an implementation of the Remote WebDriver Wire protocol, using PhantomJS as back-end
Switch branches/tags
Nothing to show
Pull request Compare This branch is 308 commits behind detro:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Ghost Driver

Ghost Driver is a pure JavaScript implementation of the WebDriver Wire Protocol for PhantomJS. It's a Remote WebDriver that uses PhantomJS as back-end.

GhostDriver is designed to be integral part of PhantomJS itself, but it's developed in isolation and progress is tracked by this Repository.

Current version is "1.0.0" (changelog).

The project was created and is lead by Ivan De Marino.


At the moment you need to compile a specific version of PhantomJS to run GhostDriver. This is because GhostDriver needed new features in PhantomJS to fulfill all the functionalities of the WebDriver "protocol". This is only temporary: next version of PhantomJS stable release will include GhostDriver built in.

Checkout and Compile Ivan De Marino's PhantomJS ghostdriver-dev branch:

  1. Prepare your machine for building PhantomJS as documented here, then...
  2. Add detro remote to local PhantomJS repo: git remote add detro
  3. Checkout the ghostdriver-dev branch: git fetch detro && git checkout -b detro-ghostdriver-dev remotes/detro/ghostdriver-dev
  4. Build: ./
  5. Go make some coffee (this might take a while...)
  6. phantomjs --webdriver=8080 to launch PhantomJS in Remote WebDriver mode

How to use it

Launching PhantomJS in Remote WebDriver mode it's simple:

$ phantomjs --webdriver=PORT

Once started, you can use any RemoteWebDriver implementation to send commands to it. I advice to take a look to the /test directory for examples.

Run the tests

Here I show how to clone this repo and kick start the (Java) tests. You need Java SDK to run them (I tested it with Java 7, but should work with Java 6 too).

  1. git clone
  2. Configure phantomjs_exec_path inside ghostdriver/test/config.ini to point at the build of PhantomJS you just did
  3. cd ghostdriver/test; ./gradlew test

Run GhostDriver yourself and launch tests against that instance

  1. phantomjs --webdriver=PORT
  2. Configure driver inside ghostdriver/test/config.ini to point at the URL http://localhost:PORT
  3. cd ghostdriver/test; ./gradlew test

Register GhostDriver with a Selenium Grid hub

  1. Launch the grid server, which listens on 4444 by default: java -jar /path/to/selenium-server-standalone-2.25.0.jar -role hub
  2. Register with the hub: phantomjs --webdriver=8080 --webdriver-selenium-grid-hub=
  3. Now you can use your normal webdriver client with and just request browserName: phantomjs

Project Directory Structure

Here follows the output of the tree command, trimmed of files and "build directories":

├── binding
│   └── java
│       ├── jars            <--- JARs containing Binding, related Source and related JavaDoc
│       └── src             <--- Java Binding Source
├── src                     <--- GhostDriver JavaScript core source
│   ├── request_handlers    <--- JavaScript "classes/functions" that handle HTTP Requests
│   └── third_party         <--- Third party/utility code
│       └── webdriver-atoms <--- WebDriver Atoms, automatically imported from the Selenium project
├── test
│   ├── java
│   │   └── src             <--- Java Tests
│   └── python              <--- Python Tests
└── tools                   <--- Tools (import/export)

Presentation and Slides (old)

In April 2012 I (Ivan De Marino) presented GhostDriver at the Selenium Conference: slides and video.

Contributions and/or Bug Report

You can contribute by testing GhostDriver, reporting bugs and issues, or submitting Pull Requests. Any help is welcome, but bear in mind the following base principles:

  • Issue reporting requires a reproducible example, otherwise will most probably be closed withouth warning
  • Squash your commits by theme: I prefer a clean, readable log
  • Maintain consistency with the code-style you are surrounded by
  • If you are going to make a big, substantial change, let's discuss it first
  • I HATE CoffeeScript: assume I'm going to laugh off any "contribution" that contains such aberrating crap!
  • Open Source is NOT a democracy (and I mean it!)


GhostDriver is distributed under BSD License.