- Ghost Driver is the WebDriver implementation built into PhantomJS for headless browser testing
- Setup requires downloading PhantomJS, adding language bindings, and setting executable capabilities
- Headless execution runs faster than Firefox and requires no external display server
- Custom capabilities allow user-agent overrides, SSL ignoring, and CLI argument passing
- Issue reporting requires reproducible test code to ensure quick bug fixes
What is Ghost Driver? Core Concepts
Ghost Driver serves as the critical bridge between Selenium's WebDriver protocol and PhantomJS, a headless WebKit browser. When you write a test script using Selenium bindings, the Remote WebDriver component communicates through an HTTP/JSON REST protocol based on the W3C WebDriver specification. Ghost Driver receives these commands inside the PhantomJS process and translates them into browser actions.
Video Highlights:
- Explanation of Ghost Driver's dual identity as both a bundled library and a standalone script
- Detailed sequence diagram of what happens during driver instantiation
- Architecture overview showing how Selenium communicates with PhantomJS
- Comparison between PhantomJS and other headless solutions like HTMLUnit
Ghost Driver and PhantomJS Driver are often confused. Ghost Driver is the JavaScript implementation running inside PhantomJS. PhantomJS Driver refers to the language binding classes (like PhantomJSDriver in Java) used in your test scripts.
When you initialize a new PhantomJSDriver instance in your test, several complex operations execute beneath the surface. The driver service launches a separate PhantomJS process, which then loads the Ghost Driver script. The service polls the /status endpoint until PhantomJS responds with a success code. Only then does it create a new session by sending an HTTP POST request with your desired capabilities.
| Component | Role | Location |
|---|---|---|
| Selenium Bindings | Client-side test scripts | Your test project |
| Remote WebDriver | Translates commands to HTTP requests | Selenium library |
| Ghost Driver | Implements WebDriver protocol | Inside PhantomJS |
| PhantomJS | Headless WebKit execution engine | Separate process |
Ghost Driver Setup: Step-by-Step Configuration
Setting up Ghost Driver requires configuring both the PhantomJS executable and your Selenium language bindings. The process varies slightly depending on your programming language, but the core concepts remain identical across Java, Python, Ruby, and .NET.
Download PhantomJS
Download the appropriate PhantomJS build for your operating system from the official website. Unzip the package and note the path to the executable. Building from source is possible but takes one to five hours depending on hardware, as it compiles the entire WebKit engine.
Add Language Bindings
Add Selenium WebDriver bindings to your project. In Gradle, this requires a single dependency line. For Maven, use the POM-style inclusion. Python, Ruby, and .NET users can install the Selenium package, which includes PhantomJS driver classes natively.
Set Executable Path Capability
Create a capabilities object and set the phantomjs.executable.path property to the location of your PhantomJS binary. Your test script needs this explicit path to locate and launch the headless browser process.
Initialize Driver and Run Tests
Pass the capabilities object to the PhantomJSDriver constructor. From this point forward, the driver behaves like any standard WebDriver implementation. Existing Selenium tests should run without modification in most scenarios.
Use the static final constants provided in the PhantomJSDriverService class to set capability keys. The constant names are verbose but prevent typos and make your configuration code self-documenting.
| Language | Setup Method | Difficulty |
|---|---|---|
| Python | pip install selenium | Easy |
| Ruby | Gem installation | Easy |
| .NET | NuGet package | Easy |
| Java (Gradle) | Single dependency line | Moderate |
| Java (Maven) | POM XML inclusion | Moderate |
Advanced Capabilities and Customization
Ghost Driver supports several advanced capabilities that allow testers to fine-tune PhantomJS behavior. These custom settings bypass the standard WebDriver protocol limitations by passing PhantomJS-specific parameters directly to the page objects created during test execution.
User-Agent Override
- Bypass scraping filters
- Simulate iOS or Android devices
- Set via
phantomjs.page.settings.userAgent - Applies to all sessions
SSL Certificate Ignoring
- Skip certificate validation errors
- Ideal for internal corporate testing
- Pass
--ignore-ssl-errors=truevia CLI args capability - Available in version 1.3+
Custom CLI Arguments
- Pass any PhantomJS command-line flag
- Use
phantomjs.cli.argscapability array - Supports all standard PhantomJS parameters
- Flexible configuration per session
Beyond CLI arguments, Ghost Driver exposes all standard PhantomJS page settings through capabilities. These include JavaScript enabling, image loading toggles, and network access permissions. Refer to the official PhantomJS documentation for the full list of available settings.
| Capability Key | Purpose | Example Value |
|---|---|---|
phantomjs.executable.path | Path to PhantomJS binary | /usr/local/bin/phantomjs |
phantomjs.page.settings.userAgent | Override browser user-agent string | Mozilla/5.0 (iPhone...) |
phantomjs.cli.args | Array of CLI arguments | ["--ignore-ssl-errors=true"] |
phantomjs.ghostdriver.path | Custom Ghost Driver script path | /path/to/ghostdriver.js |
Selenium Grid Integration
Ghost Driver supports registration with Selenium Grid hubs, enabling distributed headless testing across multiple machines. This integration allows CI pipelines to request PhantomJS instances on demand from a centralized hub.
To register PhantomJS with a Selenium Grid, pass the hub URL as a command-line parameter when launching the PhantomJS process. The --webdriver-selenium-grid-hub flag tells PhantomJS where to register itself. Once registered, the hub routes incoming test requests to available PhantomJS instances.
As of the current version, Ghost Driver supports registration with Selenium Grid but does not implement an explicit unregistration protocol. If a PhantomJS process crashes or the machine goes offline, the hub may still attempt to route tests to the dead instance until a timeout occurs.
| Grid Feature | Support Status | Notes |
|---|---|---|
| Hub Registration | Supported | Via --webdriver-selenium-grid-hub flag |
| Instance Unregistration | Not implemented | No explicit deregistration protocol |
| Capability Matching | Supported | Standard WebDriver capabilities |
| Session Timeout | Supported | Hub-level timeout handling |
WebDriver Command: Implementation Status
Ghost Driver does not yet implement every command in the WebDriver specification. Understanding which commands are available helps testers avoid unexpected failures and plan alternative approaches for unsupported functionality.
Review the official command implementation spreadsheet before writing complex test scenarios. This resource tracks which WebDriver commands are fully implemented, partially supported, or planned for future releases.
| WebDriver Command | Status | Workaround |
|---|---|---|
| Navigation (Get, Back, Forward) | Implemented | None needed |
| Element Location (FindElement) | Implemented | None needed |
| Screenshots | Implemented | Captured from in-memory rendering |
| Window Resizing | Implemented | None needed |
| Alert/Confirm/Prompt Handling | Not implemented | Requires PhantomJS core modifications |
| Touch API | Not implemented | No current workaround |
| Geolocation API | Not implemented | No current workaround |
| Local Storage Manipulation | Not implemented | Use JavaScript execution |
| Screen Orientation | Not implemented | Not applicable to headless |
| Log Retrieval | Not implemented | Use console logging |
Best Practices for Testing and Issue Reporting
Effective testing with Ghost Driver requires understanding its strengths as a headless browser and following community guidelines when reporting issues. The project thrives on contributor involvement, and proper issue reports dramatically reduce resolution time.
Always provide a reproducible test case. Issues accompanied by source code that demonstrates the problem get fixed within one to two days. Reports without reproduction steps are nearly impossible to address and will likely be closed.
Before Filing an Issue:
- Search existing issues for similar reports
- Create a minimal reproducible test case
- Verify the issue exists in the latest Ghost Driver version
- Check if the WebDriver command is listed as implemented
- Include error messages and expected behavior
When comparing Ghost Driver against alternatives like HTMLUnit, the key distinction is that PhantomJS runs a real WebKit engine with a full JavaScript implementation. HTMLUnit is a mocked browser that struggles with complex UI frameworks like YUI3. Tests written for PhantomJS will generally produce the same JavaScript behavior as Chrome and Safari, since they share the WebKit foundation.
| Testing Scenario | Recommended Tool | Rationale |
|---|---|---|
| Local development iteration | Ghost Driver | Fast, headless, no window popup |
| CI pipeline without display server | Ghost Driver | No X11 or virtual framebuffer needed |
| Cross-browser validation | Chrome/Firefox | Ghost Driver is WebKit-only |
| Complex UI framework testing | Ghost Driver | Real JavaScript engine, unlike HTMLUnit |
| Mobile device simulation | Ghost Driver | User-agent and viewport overrides |
Ghost Driver excels at development-time iteration and CI environments. It should not fully replace Chrome, Firefox, or Safari testing. Use it alongside real browser drivers for comprehensive cross-browser coverage.
Frequently Asked Questions
Q: What is the difference between Ghost Driver and PhantomJS?
Ghost Driver is a JavaScript implementation of the WebDriver protocol that runs inside PhantomJS. PhantomJS is the headless WebKit browser itself. Ghost Driver translates Selenium WebDriver commands into actions that PhantomJS can execute.
Q: Does Ghost Driver support screenshots in headless mode?
Yes. PhantomJS maintains an in-memory image of the rendered page. When you request a screenshot through the WebDriver screenshot command, Ghost Driver retrieves the image from memory and returns it as a file.
Q: How does Ghost Driver compare to HTMLUnit Driver?
Ghost Driver runs a real WebKit browser engine with full JavaScript support, while HTMLUnit is a simulated browser that cannot handle complex UI frameworks. Tests that pass in Ghost Driver will generally behave the same in WebKit-based browsers like Chrome and Safari.
Q: Can I use Ghost Driver with Selenium Grid?
Yes. PhantomJS can register itself with a Selenium Grid hub using the --webdriver-selenium-grid-hub command-line flag. However, explicit unregistration is not currently supported, which may cause stale instance issues if a process crashes.
Q: Why does my test work in Firefox but fail in Ghost Driver?
Some WebDriver commands are not yet implemented in Ghost Driver, such as alert handling, touch API, and local storage manipulation. Check the command implementation status and verify that your test only uses supported commands.