Understanding PhantomJS

Share this article

Since its release, PhantomJS has become a staple in the workflow of many JavaScript engineers. In the article titled “Headless WebKit and PhantomJS”, Colin Ihrig has introduced the concept of “Headless WebKit” and wrote a few words on PhantomJS. With over 11,000 stars on GitHub, PhantomJS has become the go-to tool for developers, especially when dealing with testing their code. However, there are still many developers who have to refrain from implementing this tool in their projects due to lack of knowledge of what it really is. To help fill this gap, in this article I’ll explain the core concepts of PhantomJS, and try to demystify some of the complexities that often seem to confuse developers. Once you’ve read this article, you will have a deep understanding of what PhantomJS is and why it is considered such a powerful tool.

“A Headless What?”

On PhantomJS’ website, the technology is explained as follows:
PhantomJS is a headless WebKit scriptable with a JavaScript API. It has fast and native support for various web standards: DOM handling, CSS selector, JSON, Canvas, and SVG.
Clearly, those of you who are new to PhantomJS will probably find some difficulties in seeing a number of foreign terms. This description might overwhelm aspiring developers, and make those new to the technologies believe that it is only for very expert developers. However, I can assure you that these concepts are quite simple to understand. PhantomJS is a web browser that exists only in script. There is no GUI, but rather a headless browser that can automate different processes with JavaScript. Let’s look at some of the benefits that come with this tool right out of the box. Before explaining the topic, I recommend you to install PhantomJS on your computer if you don’t have it already. It can be installed via npm by running the command below in your CLI:
npm install phantomjs -g
Once installed, you will have access to the phantomjs command.

PhantomJS Core Concepts

Let’s dive into the details of its core concepts.

Page Automation

PhantomJS allows developers to access the browser’s DOM API. After all, PhantomJS is still a browser even if it hasn’t a GUI. Developers can write JavaScript code that will be evaluated against a specified page. Although this may not seem very important, this allows us to automate any sort of interactions with a web page without having to open a browser (operation that will save you a tremendous amount of time). This is helpful especially when using PhantomJS to run tests, and we’ll see more about that shortly. For now, let’s take a look at the example below from the project’s website. It shows how the evaluate() function can be used to return different objects from a page. In this case, evaluate() is being used to return the textContext property of the element with the ID of myagent
. All we have to do to start this example is run a file called phantomjs userAgent.js in the command line, and we’ll receive our results in the console.
var page = require('webpage').create();
console.log('The default user agent is ' + page.settings.userAgent);
page.settings.userAgent = 'SpecialAgent';
page.open('http://www.httpuseragent.org', function(status) {
  if (status !== 'success') {
    console.log('Unable to access network');
  } else {
    var ua = page.evaluate(function() {
      return document.getElementById('myagent').textContent;

Screen Capture

By utilizing WebKit, PhantomJS provides the ability to render any content on a web page and save it as an image. Therefore, it can be used to automate the process of capturing screenshots of web pages that developers can analyse to ensure that everything looks good. These images can be saved in several format such as PNG, JPEG, PDF, and GIF. The code below is taken from the PhantomJS’ documentation regarding the screen capture. By running phantomjs github.js in the command line, the following code will render a PNG image of the GitHub’s homepage.
var page = require('webpage').create();
page.open('http://github.com/', function() {
PhantomJS also allows developers to adjust the size of these screenshots, and specify the exact areas that we want to capture. Below, we can see an example of this, which is just a modified version of our github.js script shown above.
var page = require('webpage').create();
//viewportSize being the actual size of the headless browser
page.viewportSize = { width: 1024, height: 768 };
//the clipRect is the portion of the page you are taking a screenshot of
page.clipRect = { top: 0, left: 0, width: 1024, height: 768 };
//the rest of the code is the same as the previous example
page.open('http://example.com/', function() {


PhantomJS helps developers to automate the process of running tests without a need for any sort of GUI. PhantomJS makes use of its headless browser to handle different unit tests instead, and uses the command line to tell developers where they are running into error. There is no doubt that PhantomJS is primarily known for its use in testing; however, it’s worth noting that it isn’t a testing framework. In development, PhantomJS is used to launch different tests frameworks, such as Karma. By visiting the documentation page about headless testing, you can see which frameworks have been built to support PhantomJS, as well a list of the frameworks that can be accessed via external test runner, such as the PhantomJS Runner QUnit Plugin
. PhantomJS is also used in continuous integration systems. For those who are unfamiliar with the process of continuous integration, it deals with a way to monitor your application. Developers can integrate PhantomJS with CI systems (such as Travis CI) in order to run tests on any new code being added to a project, before actually pushing the code. As a result, developers are able to detect problems in code as soon as they arise, and fix them, thus ensuring that no broken code will be pushed to the project.

Network Monitoring

Another core feature of PhantomJS is its ability to monitor the network connection. As defined in the documentation:
Because PhantomJS permits the inspection of network traffic, it is suitable to build various analysis on the network behavior and performance.
This means that PhantomJS can be programmed to collect different data about the performance of a web page. When paired with PhantomJS, YSlow can output the results from these tests using different formats (TAP, for example). When implemented, TAP allows communication between unit tests, and a testing harness, which in this case would be PhantomJS. Additionally, PhantomJS and YSlow make use of TAP protocol in continuous integration systems, and monitor the performance of new code being added to a project. In this way, developers can be informed of any regression in performance before the code is pushed.


Hopefully by now you have a firm understanding of what PhantomJS is, how it works and how truly powerful it is. If you are new to PhantomJS and testing in general and want to learn more about these topics, here is a list of resources that you could find very useful for this purpose: I hope you enjoyed this article. If you have questions or doubts, feel free to comment in the section below.

Frequently Asked Questions (FAQs) about PhantomJS

What is the main purpose of PhantomJS?

PhantomJS is a scriptable headless browser used for automating web page interaction. It provides a JavaScript API enabling automated navigation, screenshots, user behavior, and assertions making it a suitable tool for website testing. It also allows web pages to be manipulated and rendered on the server side, which is useful for web scraping, page rendering, and understanding web semantics.

How does PhantomJS differ from other headless browsers?

Unlike other headless browsers, PhantomJS allows for native support for various web standards such as DOM handling, CSS selector, JSON, Canvas, and SVG. It also supports webpage capturing, which can be useful for generating website screenshots or PDFs. PhantomJS is also known for its fast and native support for various web standards.

Is PhantomJS suitable for web scraping?

Yes, PhantomJS is a great tool for web scraping. It can render and understand web pages in a similar way to a human user, but with the advantage of being able to automate the process. This makes it a powerful tool for extracting information from websites, especially those that rely heavily on JavaScript.

Can PhantomJS be used for testing mobile websites?

Yes, PhantomJS is a versatile tool that can be used for testing mobile websites. It allows developers to emulate various screen sizes and resolutions, making it possible to test how a website will look and function on different devices.

How does PhantomJS handle JavaScript?

PhantomJS has excellent JavaScript handling capabilities. It can execute complex JavaScript functions and even render web pages that rely heavily on JavaScript. This makes it a powerful tool for testing dynamic web pages.

Can PhantomJS capture web page screenshots?

Yes, one of the key features of PhantomJS is its ability to capture screenshots of web pages. This can be particularly useful for testing visual aspects of a website, such as layout, design, and responsive behavior.

Is PhantomJS suitable for continuous integration systems?

Yes, PhantomJS is designed to be used in continuous integration systems. Its headless nature makes it ideal for running tests in the background without disrupting other processes.

How does PhantomJS support web standards?

PhantomJS has native support for a wide range of web standards, including DOM handling, CSS selector, JSON, Canvas, and SVG. This means it can accurately render and interact with web pages in the same way a human user would.

Can PhantomJS render PDFs?

Yes, PhantomJS has the ability to render PDFs. This can be useful for generating printable versions of web pages or for creating documentation.

Is PhantomJS open source?

Yes, PhantomJS is an open-source project. This means that its source code is freely available for anyone to view, modify, and distribute. It also means that it benefits from the contributions of a large community of developers, who work together to improve the software and add new features.

Thomas GrecoThomas Greco
View Author

Thomas Greco is a web developer based out of New York City specializing in full-stack development with the M.E.A.N. stack technologies. Before web development, Thomas worked as a graphic designer, and he continues to utilize his background in design when building web applications. Have a question for Thomas ? You can reach him on Twitter.

AurelioDHeadless BrowserJavaScriptPhantomJStoolswebkit
Share this article
Read Next
Get the freshest news and resources for developers, designers and digital creators in your inbox each week
Loading form