Running a PhantomJS script

This recipe demonstrates how to run a script using the PhantomJS runtime.

Getting ready

To run this recipe, we will need PhantomJS installed on our PATH. We will also need a script to run with PhantomJS; the script in this recipe is available in the downloadable code repository as recipe03.js under chapter01. If we run the provided example script, we must change to the root directory for the book's sample code.

Tip

Downloading the example code

You can download the example code files for all Packt books you have purchased from your account at http://www.packtpub.com. If you purchased this book elsewhere, you can visit http://www.packtpub.com/support and register to have the files e-mailed directly to you. Alternatively, you can use the Git version control system to clone the repository. The repository is hosted on GitHub at https://github.com/founddrama/phantomjs-cookbook.

How to do it…

Given the following script:

console.log('A console statement from PhantomJS on ' +
  new Date().toDateString() + '!');

phantom.exit();

Type the following at the command line:

phantomjs chapter01/recipe03.js

Tip

Throughout this book, we will be using POSIX-compatible filesystem paths for command-line examples. Windows users may find it helpful to change the forward slashes (/) to back slashes (\) in filesystem paths.

How it works…

Our preceding example script performs the following actions:

1. We print a message to the console (including a date string) using console.log.
2. The script exits the PhantomJS runtime using phantom.exit.
3. Since we did not provide an integer argument to phantom.exit, it returns an exit code of 0 (its default) to the shell.

As we learned in the Launching the PhantomJS REPL recipe, PhantomJS will enter the REPL when invoked without any arguments. However, the runtime environment will attempt to evaluate and execute the first unrecognized argument as though it were a JavaScript file, regardless of whether or not it ends in .js. Most of the time that we work with PhantomJS, we will interact with it using scripts such as these.

As long as PhantomJS can resolve the first unrecognized argument as a file and correctly parse its contents as syntactically valid JavaScript, it will attempt to execute the contents. However, what happens if those preconditions are not met?

If the argument cannot be resolved as a file on disk, or if the file has no contents, PhantomJS will print an error message to the console, for example:

phantomjs does-not-exist-or-empty
Can't open 'does-not-exist-or-empty'

If the argument exists but the file's contents cannot be parsed as a valid JavaScript, then PhantomJS will print an error message to the console and hang, for example:

phantomjs invalid.js
SyntaxError: Parse error

Note

In the event of such a SyntaxError, the PhantomJS process will not automatically terminate, and we must forcefully quit it (Ctrl + C).

Recall that PhantomJS is a headless web browser, and it helps to think of it as a version of Chrome or Safari that has no window. Just as we interact with our normal web browser by entering URLs into the location bar, clicking the back button, or clicking links on the page, so we will need to interact with PhantomJS. However, as it has no window and no UI components, we must interact with it through its programmable API. The PhantomJS API is written in JavaScript, and scripts targeting the PhantomJS runtime are also written in JavaScript; the API is documented online at http://phantomjs.org/api/.

There's more…

If you have been exposed to both PhantomJS and Node.js, you may be wondering about the differences between them, especially after witnessing demonstrations of their respective REPLs and script running abilities. When comparing the two, it is helpful to consider them using the phrase "based on" as your frame of reference. Node.js is based on Google Chrome's V8 JavaScript engine; PhantomJS is based on the WebKit layout engine. Node.js is a JavaScript runtime; PhantomJS has a JavaScript runtime. Where Node.js is an excellent platform for building JavaScript-based server applications, it does not have any native HTML rendering. This is the key differentiator when comparing it to PhantomJS. The mission of PhantomJS is not to provide a platform for building JavaScript applications, but instead to provide a fast and standards-compliant headless browser.

See also

• The Running a PhantomJS script with arguments recipe