Debugging tips

  1. Turn off headless mode - sometimes it's useful to see what the browser is displaying. Instead of launching in headless mode, launch a full version of the browser using headless: false:

    const browser = await puppeteer.launch({headless: false});
  2. Slow it down - the slowMo option slows down Puppeteer operations by the specified amount of milliseconds. It's another way to help see what's going on.

    const browser = await puppeteer.launch({
      headless: false,
      slowMo: 250 // slow down by 250ms
  3. Capture console output - You can listen for the console event. This is also handy when debugging code in page.evaluate():

    page.on('console', msg => console.log('PAGE LOG:', msg.text()));
    await page.evaluate(() => console.log(`url is ${location.href}`));
  4. Stop test execution and use a debugger in browser

  5. Use {devtools: true} when launching Puppeteer:

    const browser = await puppeteer.launch({devtools: true});

  6. Change default test timeout:

    jest: jest.setTimeout(100000);

    jasmine: jasmine.DEFAULT_TIMEOUT_INTERVAL = 100000;

    mocha: this.timeout(100000); (don't forget to change test to use function and not '=>')

  7. Add an evaluate statement with debugger inside / add debugger to an existing evaluate statement:

    await page.evaluate(() => {debugger;});

    The test will now stop executing in the above evaluate statement, and chromium will stop in debug mode.

  8. Enable verbose logging - internal DevTools protocol traffic will be logged via the debug module under the puppeteer namespace.

    # Basic verbose logging
    env DEBUG="puppeteer:*" node script.js
    # Debug output can be enabled/disabled by namespace
    env DEBUG="puppeteer:protocol" node script.js # protocol connection messages
    env DEBUG="puppeteer:session" node script.js # protocol session messages (protocol messages to targets)
    # Protocol traffic can be rather noisy. This example filters out all Network domain messages
    env DEBUG="puppeteer:session" env DEBUG_COLORS=true node script.js 2>&1 | grep -v '"Network'
  9. Debug your Puppeteer (node) code easily, using ndb

  10. npm install -g ndb (or even better, use npx!)

  11. add a debugger to your Puppeteer (node) code

  12. add ndb (or npx ndb) before your test command. For example:

    ndb jest or ndb mocha (or npx ndb jest / npx ndb mocha)

  13. debug your test inside chromium like a boss!