Using A Remote Debugger With CasperJS and PhantomJS

Earlier this year, my colleague wrote about how we've started using CasperJS at Lullabot to perform regression testing. I didn't have much chance to dig into it until recently, when we decided to implement some tests for Drupalize.Me. So far, I'm really enjoying CasperJS—except when something in my test simply doesn't work, and I spend hours asking CasperJS to take screenshots using console.log(), trying to discover what's happening. Fed up with this process, I wanted a debugger...

CasperJS Under The Hood

Under the hood CasperJS serves as a driver for PhantomJS, a headless, WebKit-based, browser. When you write commands in CasperJS like casper.click('a#about');, CasperJS acts like the test monkey clicking on the link to the about page in the PhantomJS browser. As such, when we're writing and running tests with CasperJS we also have access to everything that PhantomJS can do. And one of those utilities is entering into remote debugging mode.

When you run casperjs at the command line the casperjs utility passes along any options to PhantomJS, so any of the command line flags documented on the PhantomJS website will work as expected. This includes the --remote-debugger-port, and --remote-debugger-autorun flags. When the --remote-debugger-port flag is set, PhantomJS starts up your script within a debugging harness and listens on the specified port. With the debugging harness started, PhantomJS permits inspection of the currently running script, and the page that it's accessing, via any other WebKit-based browser.

Let's combine this with CasperJS and see it in action.

Debugging A Simple CasperJS Test

For the Drupalize.Me site we've got a script that performs some basic tests on our Library page. The code for these tests is in the library.js file, and looks something like this:

/**
 * @file
 * Tests for /videos page.
 */
(function() {
  casper.test.begin('Library page accessible for anon. users.', 3, function suite(test) {
    casper.start();

    casper.thenOpen('http://dev.drupalize.lan/videos', function() {
      test.assertExists('.videos-list li', 'There is at least one video listed.');
      test.assertNotVisible('.videos-list li.collection:first-of-type .series-list', 'The series list is collapsed.');
      this.click('.videos-list li.collection:first-of-type a.show-list');
      test.assertVisible('.videos-list li.collection:first-of-type .series-list', 'The series list is visible after clicking the toggle.');
    });

    casper.run();
  });
})();

If I want to run those tests with CasperJS I would use a command as shown below. The library.js script would be loaded, all the tests would run, and the session would exit. Nothing too exciting here. But also, little to no useful output when trying to figure out what's going on inside PhantomJS while the test is running.

casperjs test library.js

Enabling The PhantomJS Remote Debugger

Ready to start debugging? Here's what you'll need to do.

• Enable remote debugging when executing your tests.
• Set a breakpoint in your test file.
• Launch the remote debugging interface.
• Be a Ninja.

You can enable remote debugging by passing the --remote-debugger-port=9000 flag, which will instantiate CasperJS and PhantomJS, and then halt execution. Your library.js script won't be loaded yet however since the debugger is halting at the first line of code it encounters. Since we're not trying to debug CasperJS or PhantomJS itself, we're going to use a little trick to skip ahead in our debugging session to the part we're actually interested in.

Add the debugger; keyword to the library.js script, or whatever script you're trying to debug. Our code will look something like this now:

debugger;

(function() {
    // .. do testing stuff ..
  });
})();

This is the equivalent of setting a breakpoint in your script and it tells the debugger that once it starts running it should halt when it gets to this line.

Now run this command:

casperjs test --url=http://dev.drupalize.lan library.js  --remote-debugger-port=9000

This starts up CasperJS and PhantomJS and just halts. It hasn't started running our test yet, and thus hasn't hit our breakpoint. Before it'll proceed any further we need to tell the debugger to go ahead and start running the code.

You can access the debugger by navigating to http://localhost:9000 in your WebKit-based browser of choice and you'll be presented with a page that contains a single link. Likely titled about:blank. If you click that link it'll open the WebKit inspector, and if you've ever debugged JavaScript before things should start to look pretty familiar at this point.

Image

In the inspector navigate to the Console tab, and run the following command in the Javascript console.

__run();

This tells the PhantomJS debugger to go ahead and start execution of the script. And everything will just chug along like normal–until it hits that debugger; line that is. When it does... BLAM! Execution is halted, and the WebInspector shows us our library.js script, and the line on which it halted. And then things get awesome.

Image

From here you can use the JavaScript debugger just like you would if you where viewing any other page. Set breakpoints, step through the code, and inspect variables. Ready to have your mind blown?

Set a breakpoint somewhere inside your CasperJS tests so that execution halts after a point at which CasperJS has instructed PhantomJS to load a page. Then hit the play button and let the script run until your new breakpoint. Execution halts again, and won't continue until you hit play. During this time before you hit play you can navigate over to the Console tab and inspect what's been going on.

Image

Here's the real kicker though. Open another window and navigate to http://localhost:9000 again. This time you'll see two links. One for about:blank and another for the site that PhantomJS is currently navigating. That's right, you can now open a second WebKit inspector and start inspecting the page that PhantomJS is currently looking at. No more taking screenshots, and dumping HTML into files so you can inspect them after the tests have run. You can now see exactly what PhantomJS, and thus CasperJS, are looking at in real time.

Image

Happy debugging.