Understanding PhantomJS

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.

//userAgent.js
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;
    });
    console.log(ua);
  }
  phantom.exit();
});

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.

//github.js
var page = require('webpage').create();
page.open('http://github.com/', function() {
  page.render('github.png');
  phantom.exit();
});

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() {
  page.render('github.png');
  phantom.exit();
});

Testing

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.

Conclusions

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:

• Introduction to PhantomJS and CasperJS
• Automation with PhantomJS
• Web Scraping & Automation with PhantomJS & CasperJS
• Automation with jQuery, PhantomJS, on Node

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