TypeScript icon, indicating that this package has built-in type declarations

    0.3.4 • Public • Published



    Simple utility to go to a URL and wait for the HTTP response

    License:MIT npm Vulnerabilities Build

    puppeteer-browser-ready is a convenient helper utility to reduce the amount of boilerplate code needed to tell Puppeteer to visit a web page and and retrieve the HTML.  It's primarily intended for use within Mocha test cases.  In addition to the raw HTML, you get a cheerio reference so you can immediately run queries on the DOM.

    A) Setup

    Install packages:

    $ npm install --save-dev puppeteer puppeteer-browser-ready

    Import packages:

    import puppeteer from 'puppeteer';
    import { browserReady } from 'puppeteer-browser-ready';

    B) Usage

    Use the browserReady.goto() function to tell Puppeteer which page to open. The Promise will resolve with a Web object containing a title field and a html field. Pass the Web object to the browserReady.close() function to disconnect the page.

    const url = 'https://pretty-print-json.js.org/';
    let web;  //fields: browser, page, response, status, location, title, html, $
    before(async () => web = await puppeteer.launch().then(browserReady.goto(url));
    after(async () =>  await browserReady.close(web));

    C) TypeScript Declarations

    The TypeScript Declaration File file is puppeteer-browser-ready.d.ts in the dist folder.

    The browserReady.goto() function returns a function that takes a Puppeteer Browser object and returns a Promise that resolves with a Web object:

    type Web = {
       browser:  Puppeteer.Browser,
       page:     Puppeteer.Page,
       response: HTTPResponse | null,
       location: Location,
       title:    string,
       html:     string,
       $:        cheerio.Root | null,  //like jQuery

    The optional browserReady.startWebServer() function starts a static web server and returns a Promise for when the server is ready:

    export type Http = {
       server:     Server,
       terminator: httpTerminator.HttpTerminator,
       folder:     string,
       url:        string,
       port:       number,
       verbose:    boolean,

    D) Examples

    Example: Node.js program


    import puppeteer from 'puppeteer';
    import { browserReady } from 'puppeteer-browser-ready';
    const handleResponse = (web) => {
       console.log('Hello, World!');
       console.log('web fields:', Object.keys(web).join(', '));
       console.log(`The HTML from ${web.location.href} is ${web.html.length} characters`,
          `long and contains ${web.$('p').length} <p> tags.`);
       return web;


    Hello, World!
    web fields: browser, page, response, title, html, $
    The HTML from https://pretty-print-json.js.org/ is 8200 characters
    long and contains 7 <p> tags.

    Example: Mocha specification suite


    // Mocha Specification Suite
    // Imports
    import puppeteer from 'puppeteer';
    import { assertDeepStrictEqual } from 'assert-deep-strict-equal';
    import { browserReady } from 'puppeteer-browser-ready';
    // Setup
    const url = 'https://pretty-print-json.js.org/';
    let web;  //fields: browser, page, response, status, location, title, html, $
    const loadWebPage = async () =>
       web = await puppeteer.launch().then(browserReady.goto(url));
    const closeWebPage = async () =>  
       await browserReady.close(web);
    describe('The web page', () => {
       it('has the correct URL -> ' + url, () => {
          const actual =   { status: web.status, url: web.location.href };
          const expected = { status: 200,        url: url };
          assertDeepStrictEqual(actual, expected);
       it('has exactly one header, main, and footer', () => {
          const actual = {
             header: web.$('body >header').length,
             main:   web.$('body >main').length,
             footer: web.$('body >footer').length,
          const expected = { header: 1, main: 1, footer: 1 };
          assertDeepStrictEqual(actual, expected);
    describe('The document content', () => {
       it('has a 🚀 traveling to 🪐!', () => {
          const actual =   { '🚀': !!web.html.match(/🚀/g), '🪐': !!web.html.match(/🪐/g) };
          const expected = { '🚀': true,                    '🪐': true };
          assertDeepStrictEqual(actual, expected);


      The web page
        ✓ has the correct URL -> https://pretty-print-json.js.org/
        ✓ has exactly one header, main, and footer
      The document content
        ✓ has a 🚀 traveling to 🪐!

    Example: Start and shutdown a static web server

    The startWebServer() and shutdownWebServer() functions can be used in global fixtures to start and shutdown a static web server.

    For example, the spec/fixtures/setup-teardown.js file below starts a web server on port 7123 with the web root pointed to the project's docs folder.


    // Specification Fixtures
    import { browserReady } from 'puppeteer-browser-ready';
    let http;  //fields: server, terminator, folder, url, port, verbose
    // Setup
    const mochaGlobalSetup = async () => {
       http = await browserReady.startWebServer({ folder: 'docs', port: 7123 });
    // Teardown
    const mochaGlobalTeardown = async () => {
       await browserReady.shutdownWebServer(http);
    export { mochaGlobalSetup, mochaGlobalTeardown };

    Run specification suites with global fixtures:
    $ npx mocha spec/*.spec.js --require spec/fixtures/setup-teardown.js


      [2021-07-14T11:38:22.892Z] Web Server - listening: true 7123 http://localhost:7123/
      ...Output of Mocha specification suites here...
      [2021-07-14T11:38:26.704Z] Web Server - shutdown: true

    MIT License


    npm i puppeteer-browser-ready

    DownloadsWeekly Downloads






    Unpacked Size

    19.5 kB

    Total Files


    Last publish


    • dpilafian