Repository files navigation

Ghost Driver is a pure JavaScript implementation of theWebDriver Wire ProtocolforPhantomJS.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 trackedby this Repository.

• CurrentGhostDriver stable version:seereleases
• PhantomJS-integrated version is"1.2.0" (detro@2af7099a9) :contained in PhantomJS"2.1.1"
• CurrentPhantomJSDriver Java bindings stable version: seeMaven

For more info, please take a look at thechangelog.

The project was created and is lead byIvan De Marino.

IRC channel:#phantomjs-ghostdriver.

• Download latest stable PhantomJS fromhere
• Selenium version">= 3.1.0"

THAT'S IT!! Because of latest stable GhostDriver being embedded in PhantomJS,you shouldn't need anything else to get started.

1. Launch the grid server, which listens on 4444 by default:java -jar /path/to/selenium-server-standalone-<SELENIUM VERSION>.jar -role hub
2. Register with the hub:phantomjs --webdriver=8080 --webdriver-selenium-grid-hub=http://127.0.0.1:4444
3. Now you can use your normal webdriver client withhttp://127.0.0.1:4444 and just requestbrowserName: phantomjs

This project provides WebDriver bindings for Java under the namePhantomJSDriver.Here is the JavaDoc.

Bindings for other languages (C#, Python, Ruby, ...) are developed and maintainedunder the same name within theSelenium project itself.

For versions >= 2.0.0, add the following to yourpom.xml:

<repositories>  <repository>      <id>jitpack.io</id>      <url>https://jitpack.io</url>  </repository></repositories>

<dependency>    <groupId>com.github.detro</groupId>    <artifactId>ghostdriver</artifactId>    <version>2.1.0</version></dependency>

Just add the following to yourbuild.gradle:

allprojects {  repositories {    maven { url'https://jitpack.io' }  }}

dependencies {...    testCompile'com.github.detro:ghostdriver:2.1.0'...}

Launching PhantomJS in Remote WebDriver mode it's simple:

$ phantomjs --webdriver=PORT

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

• GhostDriver extra Capabilities
  • phantomjs.page.settings.SETTING = VALUE - Configurepage.settingson PhantomJS internal page objects (windows in WebDriver context)(seereference)
  • phantomjs.page.customHeaders.HEADER = VALUE - Add extra HTTP Headerswhen loading a URL(seereference)
  • phantomjs.page.whitelist - an array of regex expressions of urls to accept. eg. ['my-awesome-website.com']
  • phantomjs.page.blacklist - array of regex expressions of urls to ignore. The blacklist overrides the whitelist. eg. ['google.com', 'github.com']
  • unhandledPromptBehavior - set todismiss to automatically dismissall user prompts or set toaccept to automatically accept all user prompts
  • loggingPrefs - ghostdriver has two logsbrowser andhar. The logsdefault to"OFF". follow theDesiredCapabilitiesdocumentation to enable the logs.
• PhantomJSDriverJava-binding Capabilities
  • phantomjs.binary.path - Specify path to PhantomJS executable to use
  • phantomjs.ghostdriver.path - Specify path to GhostDrivermain/src.jsscript to use; allows to use a different version of GhostDriver then the oneembed in PhantomJS
  • phantomjs.cli.args - Specify command line arguments to pass to thePhantomJS executable
  • phantomjs.ghostdriver.cli.args - Specify command line argument to pass toGhostDriver (works only in tandem withphantomjs.ghostdriver.path)

GhostDriver pushed the evolution of PhantomJS from the start. All the features required by PhantomJS to fit GhostDriver were designed to still feel "consistent" and "at home" with PhantomJS alone.

To drive that effort, I worked on aPhantomJS fork, and thenpushed changes to PhantomJS master once agreed with the rest of the team on the changes.

If you are planning to contribute, that is the PhantomJS you should use.

Here I show how to clone this repo and kick start the (Java) tests. You needJava SDKto run them. ghostdriver requires Java 1.8.

1. git clone https://github.com/detro/ghostdriver.git
2. Configurephantomjs_exec_path insideghostdriver/test/config.ini to point at the build of PhantomJS you just did
3. cd ghostdriver/test/java; ./gradlew test

1. phantomjs --webdriver=PORT
2. Configuredriver insideghostdriver/test/config.ini to point at the URLhttp://localhost:PORT
3. cd ghostdriver/test/java; ./gradlew test

Here follows the output of thetree -hd -L 3 command, trimmed of files and "build directories":

.├── [ 102]  binding│   └── [ 510]  java│       ├── [ 204]  build│       ├── [ 136]  gradle│       ├── [ 884]  jars<--- JARs containing Binding, related Source and related JavaDoc│       └── [ 102]  src<--- Java Binding Source├── [ 442]  src<--- GhostDriver JavaScript coresource│   ├── [ 306]  request_handlers<--- JavaScript"classes/functions" that handle HTTP Requests│   └── [ 204]  third_party<--- Third party/utility code│       └── [2.0K]  webdriver-atoms<--- WebDriver Atoms, automatically imported from the Selenium project├── [ 204]test│   ├── [ 476]  java<--- Java Tests│   │   ├── [ 136]  gradle│   │   ├── [ 136]  out│   │   └── [ 102]  src│   ├── [ 238]  python<--- Python Tests│   │   └── [ 102]  utils│   └── [ 340]  testcase-issue_240└── [ 238]  tools<--- Tools (import/export)    └── [ 136]  atoms_build_dir20 directories

Being GhostDriver a WebDriver implementation, it embeds the standard/default WebDriver Atoms to operate inside openwebpages. In the specific, the Atoms cover scenarios where the "native" PhantomJSrequire('webpage') don't stretch.

Documentation about how those work can be foundhereandhere.

How are those Atoms making their way into GhostDriver? If you look inside the/tools directory you can find a bashscript:/tools/import_atoms.sh. That script accepts the path to a Selenium local repo, runs theCrazyFunBuild to produce the compressed/minified Atoms,grabs those and copies them over to the/src/third_party/webdriver-atoms directory.

The Atoms original source lives inside the Selenium repo in the subtree of/javascript. To understand how the buildworks, you need to spend a bit of time reading aboutCrazyFunBuild: worth your time if you want to contribute toGhostDriver (or any WebDriver, as a matter of fact).

One thing it's important to mention, is that CrazyFunBuild relies on the content ofbuild.desc file to understandwhat and how to build it. Those files define what exactly is built and what it depends on. In the case of the Atoms,the word "build" means "run Google Closure Compiler over a set of files and compress functions into Atoms".The definition of the Atoms that GhostDriver uses lives at/tools/atoms_build_dir/build.desc.

Let's take this small portion of ourbuild.desc:

js_library(name = "deps",  srcs = "*.js",  deps = ["//javascript/atoms:deps",          "//javascript/webdriver/atoms:deps"])js_fragment(name = "get_element_from_cache",  module = "bot.inject.cache",  function = "bot.inject.cache.getElement",  deps = [ "//javascript/atoms:deps" ])js_library(name = "build_atoms",  deps = [    ...    "//javascript/webdriver/atoms:execute_script",    ...  ]

The first part (js_library(name = "deps"...) declares what are the dependency of thisbuild.desc: with that CrazyFunBuild knowswhat to build before fulfilling our build.

The second part (js_fragment(...) defines an Atom: theget_element_from_cache is going to be the name ofan Atom to build; it can be found in the modulebot.inject.cache and is realised by the function namedbot.inject.cache.getElement.

The third part (js_library(name = "build_atoms"...) is a list of the Atoms (either defined by something like the secondpart or in one of the files we declared as dependency) that we want to build.

If you reached this stage in understanding the Atoms, you are ready to go further by yourself.

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

• Issue reporting requires a reproducible example, otherwise will most probably beclosed without 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
• IHATE CoffeeScript: assume I'm going to laugh off any "contribution" that contains suchaberrational crap!
• Open Source is NOT a democracy (and I mean it!)

GhostDriver is distributed underBSD License.

Seehere.