Painless Puppeteer Debugging

One of the things that becomes obvious when working with Puppeteer is how frustrating and time-consuming it can be to debug. Node’s debugging tools can only do so much (you can’t see the browser), and taking screenshots at every step only scales so far. By the time you’ve fixed the issue, you’re back to removing all your debugging code, which also costs precious time.

browserless is dedicated to improving the development and debugging experience of headless browser work, including when your scripts are even running in production. Given that most developers will likely know how to use Chrome’s developer toolset, we also don’t want to re-invent the wheel as well. With those thoughts in mind, and after a few weeks of building, today we’re happy to announce our new Live Debugger. See it in action below!

How to use it

When running an API call (such as the /pdf or /content APIs), or when running with puppeteer.connect, you can specify a new query-string parameter of ?pause. This tells browserless to start the session but to immediately pause execution on newly-created pages. This way you don’t lose any context on what’s going on when loading the debugger.

Here’s our example code from our gif above:

const puppeteer = require('puppeteer');

async function run() {
  let browser = null;
  try {
    browser = await puppeteer.connect({
      browserWSEndpoint: `ws://localhost:3000?pause`, // Use ?pause to halt execution
    });

    const page = await browser.newPage();
    await page.goto('https://example.com');
    await page.click('a');
  } catch(e) {
    console.log(e);
  } finally {
    if (browser) browser.close();
  }
}
run();

Once that’s running, your next step is to simply load the debugging webpage and click the “☰” link. If you’re running our docker image, you can find it located here: http://localhost:3000. Dedicated accounts can find running sessions on their account page.

After that it’s a simple click to open the devtools and resume your script. Simply press the Play button in the the “Sources” tab!

How it actually works

Anytime browserless starts a new session it holds onto the browser object internally. When a JSON request to /session happens (which is what the Debugger site does), browserless then iterates over all the pages inside the browser, and returns a JSON response with links to load the remote developer tools. This works out-of-the-box for all our REST API’s as well as for puppeteer. Support for webdriver and selenium is coming soon.

Since Chrome loads the static assets directly from the browser that created them, we automatically serve them for you. This means you don’t need to host static assets elsewhere, and can debug pages in isolation (if that’s a requirement). It also means you don’t necessarily need to have HTTPS configured for your domain!

Starting today we support this feature in our Docker releases (v1.5.0) as well as for Dedicated accounts on our platform. We hope to enable this soon for usage-based accounts as well.