Running PhantomJS with a JSON configuration file

In this recipe, we will learn how to store PhantomJS configuration options in a JSON document and load those options using the config command-line argument.

Getting ready

To run this recipe, we will need a JSON-formatted configuration file with our PhantomJS command-line options.

The script in this recipe is available in the downloadable code repository as recipe07.js under chapter01. If we run the provided example script, we must change to the root directory for the book's sample code. An example configuration file is also in this directory as recipe07-config.json.

Lastly, the script in this recipe runs against the demo site that is included with the cookbook's sample code repository. To run that demo site, we must have Node.js installed. In a separate terminal, change to the phantomjs-sandbox directory (in the sample code's directory) and start the app with the following command:

node app.js

How to do it…

Select our command-line configuration options (changing hyphenated property names into their camel-cased equivalents) and apply our values. Save these configuration settings to a JSON-formatted document. For example, the contents of recipe07-config.json under chapter01:

{
  "cookiesFile"     : "cookie-jar.txt",
  "ignoreSslErrors" : true
}

Tip

For more information about JSON, including its formatting rules, visit http://www.json.org.

Given the script from the Running PhantomJS with cookies recipe earlier in this chapter, enter the following at the command line:

phantomjs --config=chapter01/recipe07-config.json chapter01/recipe07.js

How it works…

The configuration file is a JSON document where we can take our preferred command-line arguments and store them on disk. The keys in the JSON object have a one-to-one correspondence with the command-line arguments themselves – the hyphenated command-line argument names are converted to their camel-cased versions (for example, cookies-file becomes cookiesFile). The values in the JSON object follow easy conversion rules based on the most applicable JavaScript primitives: strings are strings, numbers are numbers, and true/false or yes/no become the corresponding true or false Boolean literals. Creating our own JSON-formatted configuration file requires only two things: a text editor and the knowledge of which command-line arguments we wish to capture in it.

Tip

See http://phantomjs.org/api/command-line.html for the complete list of documented command-line options in the PhantomJS API.

Note

The help and version command-line arguments do not have corresponding versions in the JSON configuration file. Also, at the time of writing this book, there is a documented defect wherein the JSON key for the load-images argument is not recognized.

The example script in this recipe (recipe07.js under chapter01) is identical to the one that we used for our demonstration in the Running PhantomJS with cookies recipe; we are reusing it here for convenience. For a more thorough explanation of what it is doing, see the How it works… section under that recipe.

When launching PhantomJS with the config command-line argument, the PhantomJS runtime interprets the argument's value as a path on the filesystem and attempts to load and evaluate that file as a JSON document. If the file cannot be parsed as a JSON document, then PhantomJS prints a warning and ignores it. If the file is correctly parsed, then PhantomJS configures itself as if the arguments in the JSON document had been passed as normal command-line arguments.

This raises an interesting question: given equivalent arguments, which one takes precedence? The one specified in the JSON configuration file? Or the one specified on the command line? The answer is that it depends which one comes last. In other words, given recipe07-config.json, we can run:

phantomjs --cookies-file=jar-of-cookies.txt --config=chapter01/recipe07-config.json chapter01/recipe07.js

That creates cookie-jar.txt, as specified in recipe07-config.json. While the following command creates jar-of-cookies.txt, as specified on the command line:

phantomjs --config=chapter01/recipe07-config.json --cookies-file=jar-of-cookies.txt chapter01/recipe07.js

There's more…

Saving a PhantomJS configuration to a JSON document can help us in a couple of ways. First, by putting it into a file, we can put it under version control and track the changes to that configuration over time. Also, by putting the configuration into a file, it can more easily be shared across teams or jobs in continuous integration.

See also

• The Running PhantomJS with cookies recipe