Discover Puppeteer, the Open Source Headless Chrome Node API.

Puppeteer: a Node.js library to control headless Chrome

In the last time, a lot of headless browsers based in Chromium have appeared like Chromeless, Chrominator, Navalia, Lambdium and others, making the desicion of which browser testing framework to choose difficult. That's why today, we want to share with you one of the most awesome browser testing framework to choose with Node.js, we are talking about Puppeteer, a project leaded by the Google Chrome Developer Tools team.

What is Puppeteer

Basically, Puppeteer is a Node library that provides a high-level API to control a headless Chrome over the DevTools Protocol. It can also be configured to use full Chrome. Most things that you can do manually in the browser can be done using Puppeteer and its API, for example:

  • Generate screenshots and PDFs of pages.
  • Crawl a SPA and generate pre-rendered content (i.e. "SSR").
  • Scrape content from websites.
  • Automate form submission, UI testing, keyboard input, etc.
  • Create an up-to-date, automated testing environment. Run your tests directly in the latest version of Chrome using the latest JavaScript and browser features.
  • Capture a timeline trace of your site to help diagnose performance issues.

Installing Puppeteer

When you install Puppeteer using a package manager like NPM or Yarn, it downloads a recent version of Chromium (that weighs about ~71Mb on Mac, ~90Mb on Linux, ~110Mb on Windows) that is guaranteed to work with the API. That means, that unlike other browser testing frameworks, you aren't going to worry about to maintain your own instance of chrome/chromium and launch the headless server with the command line.

As mentioned, you can install Puppeteer using NPM or Yarn with Node.js. Just run any of the following commands in the terminal:

REM If you use NPM:
npm i puppeteer

REM Or with yarn
yarn add puppeteer

After the installation, you will be able to control the headless browser by requiring the puppeteer module in some JS file. For more information about the library and its source code, don't forget to visit the official repository at Github here.

Requirements

Originally Puppeteer required Node.js 7.x to work, as it uses the await keyword in the source code, which makes the asynchronous code easier to read and understand. However to provide backwards compatibility with older Node.js (and LTS) version, puppeteer can be now used with Node.js Version 6.x (since version v0.10.0), that means that you can use it with a LTS version of node installed:

REM Needs to output at least version 6
node -v

With puppeteer you will be able to create screenshots, generate PDFs, automatized testing and a lot of other tasks.

Running a script with Puppeteer

To execute some tasks with puppeteer, you only need basic Node.js knowledge. Install the puppeteer module in your project, create a script file namely script.js and write the code that uses puppeteer inside, in this case we are going to create a screenshot of Our Code World with the following code (copy and paste the code inside the script.js file):

// Require puppeteer
const puppeteer = require('puppeteer');

(async () => {
    // Create an instance of the chrome browser
    const browser = await puppeteer.launch();

    // Create a new page
    const page = await browser.newPage();

    // Set some dimensions to the screen
    page.setViewport({
        width: 1920,
        height: 1080
    });

    // Navigate to Our Code World
    await page.goto('http://ourcodeworld.com');

    // Create a screenshot of Our Code World website
    await page.screenshot({
        path: 'screenshot.png'
    });

    // Close Browser
    browser.close();
})();

Finally, just run the script with Node using:

node script.js

And you would only need to wait till the task finishes, then you will find a screenshot of Our Code World in the same directory of the script.js file.

Using the Developer Tools

The most awesome thing on Puppeteer, is the possibility to use the Chrome Developer Tools as you are using Chrome under the hood ! Just don't forget to disable the headless browser mode in your initialization script:

// Require puppeteer
const puppeteer = require('puppeteer');

(async () => {
    // Create an instance of the chrome browser
    // But disable headless mode !
    const browser = await puppeteer.launch({
        headless: false
    });

    // Create a new page
    const page = await browser.newPage();

    // Set some dimensions to the screen
    page.setViewport({
        width: 1920,
        height: 1080
    });

    // Navigate to Our Code World
    await page.goto('http://ourcodeworld.com');

    // Create a screenshot of Our Code World website
    await page.screenshot({
        path: 'screenshot.png'
    });

    // Don't close via script but manually
    // closing the chromium window !
    // browser.close();
})();

The script would start the chromium process and you will be able to use the developer tools as usual, just awesome right?

Puppeteer Headless Browser Testing with Developer Tools

Contributing to Puppeteer

Puppeteer is an open source project, so issues reporting, code contributions are welcome in the official Github repositoryThe Chrome DevTools team maintains the library, however if you can help, you are free to do it, so don't forget to take a look to the contribution guidelines of the project here.


Senior Software Engineer at Software Medico. Interested in programming since he was 14 years old, Carlos is a self-taught programmer and founder and author of most of the articles at Our Code World.

Sponsors