Poltergeist 0.6.0: Javascript error handling and remote debugging

15 April 2012

Recently I pushed version 0.6.0 of Poltergeist. This version brings some pretty awesome features that I am very excited about.

My goal with Poltergeist is to create the fastest and best Capybara driver. A common problem when using Capybara, particularly when using a headless driver, is debugging. To be the best driver, Poltergeist needs to be the easiest to debug.

Javascript errors

Prior to 0.6.0, Poltergeist had rudimentary support for detecting Javascript errors on the page, but it was impossible to report the stack trace for these errors. This stems from a lack of support for reporting stack traces in QtWebKit, which PhantomJS is based on. This problem affects capybara-webkit too.

PhantomJS 1.5 was recently released, and prior to the release I worked hard to add stack trace support there. This was a pretty hard task and involved diving deep into WebKit’s source, but I got there eventually.

Poltergeist 0.6.0 updates the PhantomJS dependency to 1.5, and so I am happy to say that if there is a Javascript error in your page (or in Poltergeist’s Javascript code), the error will trigger an exception in your Capybara test, and you’ll see a full stack trace showing where it happened.

To my knowledge, Poltergeist is the first Capybara driver to support Javascript error handling at this level.

Remote debugging

You may have heard of the ‘remote debugging’ feature in Safari or Chrome. Essentially remote debugging means that your browser can run a WebSocket API on a given port, and then another browser (possibly on a completely different computer) can connect to it and use a Web Inspector to interact with the page.

This feature is actually a feature of WebKit which means that PhantomJS, being built on WebKit, can have remote debugging too. I’m sure you’ve guessed by now where this is going, so yes, Poltergeist 0.6.0 supports remote debugging.

There is an important caveat. It has been reported that remote debugging in PhantomJS doesn’t work on OS X. I don’t own a Mac, so it’s hard for me to confirm this problem or debug it myself. For now all I can say is that I have used the remote debugging feature successfully on Linux, and I would be delighted if somebody wants to step up and work out how to fix it on OS X.

Here’s how it works:

If you setup Poltergeist with the :inspector => true option (see the docs for details), PhantomJS will get set up in remote debugging mode. Note that due to internal WebKit reasons, we can’t report Javascript stack traces in this mode (but that’s okay, because you can see the stack traces in your inspector window).

With the inspector enabled, you can insert page.driver.debug into your test. This will pause the test and launch a browser window with two links. The first one is the “page” that PhantomJS runs its script in (don’t worry about this).

The second one is the one you want. Click on it and you’ll see a web inspector - this should look familiar. You can now add breakpoints to your code, or inspect the DOM, or whatever. When you’re read press return in the console and your test will continue. If you want to pause it again, just add page.driver.pause.