\n\n_Simple utility to go to a URL and wait for the HTTP response_\n\n[](https://github.com/center-key/puppeteer-browser-ready/blob/main/LICENSE.txt)\n[](https://www.npmjs.com/package/puppeteer-browser-ready)\n[](https://github.com/center-key/puppeteer-browser-ready/actions/workflows/run-spec-on-push.yaml)\n\n**puppeteer-browser-ready** is a helper utility to reduce the amount of boilerplate code needed\nto tell Puppeteer to visit a web page and and retrieve the HTML. \nIt's primarily intended for use within [Mocha](https://mochajs.org) test cases. \nIn addition to the raw HTML, you get a [node-html-parsed](https://github.com/taoqf/node-html-parser)\nroot so you can immediately run queries on the DOM.\n\n## A) Setup\n**Install packages:**\n```shell\n$ npm install --save-dev puppeteer puppeteer-browser-ready\n```\n**Import packages:**\n```javascript\nimport puppeteer from 'puppeteer';\nimport { browserReady } from 'puppeteer-browser-ready';\n```\n\n## B) Usage\nUse the `browserReady.goto(url, options)` function to tell Puppeteer which page to open.\nThe **Promise** will resolve with a **Web** object containing a `title` field and a `html` field.\nPass the **Web** object to the `browserReady.close(web)` function to disconnect the page.\n```javascript\nconst url = 'https://pretty-print-json.js.org/';\nlet web; //fields: browser, page, response, status, location, title, html, root\nbefore(() => puppeteer.launch().then(browserReady.goto(url)).then(info => web = info));\nafter(() => browserReady.close(web));\n```\n### `goto()` Options\n| Name (key) | Type | Default | Description |\n| :----------- | :---------- | :------ | :-------------------------------------------------------- |\n| `parseHtml` | **boolean** | `true` | Return the DOM root as an HTMLElement (node-html-parsed). |\n| `verbose` | **boolean** | `false` | Output HTTP connection debug messages. |\n\n### `startWebServer()` Options\n| Name (key) | Type | Default| Description |\n| :------------ | :---------- | :----- | :----------------------------------------------- |\n| `autoCleanup` | **boolean** | `true` | Terminate connection on interruption (`SIGINT`). |\n| `folder` | **string** | `'.'` | Document root for the static web server. |\n| `port` | **number** | `0` | Port number for server (`0` find open port). |\n| `verbose` | **boolean** | `true` | Output informational messages. |\n\n## C) TypeScript Declarations\nSee the TypeScript declarations at the top of the\n[puppeteer-browser-ready.ts](src/puppeteer-browser-ready.ts) file.\n\nThe `browserReady.goto(url, options)` function returns a function that takes a Puppeteer **Browser**\nobject and returns a **Promise** that resolves with a **Web** object:\n```typescript\ntype Web = {\n browser: Puppeteer.Browser,\n page: Puppeteer.Page,\n response: HTTPResponse | null,\n location: Location,\n title: string,\n html: string,\n root: HTMLElement | null, //see node-html-parsed library\n };\n```\n\nThe optional `browserReady.startWebServer(options)` function starts a static web server and returns\na **Promise** for when the [server](spec/start-web-server.spec.js) is ready:\n```typescript\nexport type Http = {\n server: Server,\n terminator: httpTerminator.HttpTerminator,\n folder: string,\n url: string,\n port: number,\n verbose: boolean,\n };\n```\n\n## D) Examples\n\n### Example 1: Node.js program\n**Code:**\n```javascript\nimport puppeteer from 'puppeteer';\nimport { browserReady } from 'puppeteer-browser-ready';\n\nconst handleResponse = (web) => {\n console.info('Hello, World!');\n console.info('web fields:', Object.keys(web).join(', '));\n console.info(`The HTML from ${web.location.href} is ${web.html.length} characters`,\n `long and contains ${web.root.querySelectorAll('p').length} tags.`);\n return web;\n };\npuppeteer.launch()\n .then(browserReady.goto('https://pretty-print-json.js.org/'))\n .then(handleResponse)\n .then(browserReady.close);\n```\n**Output:**\n```\nHello, World!\nweb fields: browser, page, response, status, location, title, html, root\nThe HTML from https://pretty-print-json.js.org/ is 8200 characters\nlong and contains 7
tags.\n```\n\n### Example 2: Mocha specification suite\n**Code:**\n```javascript\n// Mocha Specification Suite\n\n// Imports\nimport puppeteer from 'puppeteer';\nimport { assertDeepStrictEqual } from 'assert-deep-strict-equal';\nimport { browserReady } from 'puppeteer-browser-ready';\n\n// Setup\nconst url = 'https://pretty-print-json.js.org/';\nlet web; //fields: browser, page, response, status, location, title, html, root\nconst loadWebPage = () =>\n puppeteer.launch().then(browserReady.goto(url)).then(info => web = info);\nconst closeWebPage = () =>\n browserReady.close(web);\n\n/////////////////////////////////////////////////////////////////////////////////////\ndescribe('The web page', () => {\n before(loadWebPage);\n after(closeWebPage);\n\n it('has the correct URL', () => {\n const actual = { status: web.status, url: web.location.href };\n const expected = { status: 200, url: url };\n assertDeepStrictEqual(actual, expected);\n });\n\n it('title starts with \"Pretty-Print JSON\"', () => {\n const actual = { title: web.title.substring(0, 17) };\n const expected = { title: 'Pretty-Print JSON' };\n assertDeepStrictEqual(actual, expected);\n });\n\n it('body has exactly one header, main, and footer -- node-html-parsed', () => {\n const getTags = (elems) => [...elems].map(elem => elem.tagName.toLowerCase());\n const actual = getTags(web.root.querySelectorAll('body >*'));\n const expected = ['header', 'main', 'footer'];\n assertDeepStrictEqual(actual, expected);\n });\n\n it('body has exactly one header, main, and footer -- page.$$eval()', async () => {\n const getTags = (elems) => elems.map(elem => elem.nodeName.toLowerCase());\n const actual = await web.page.$$eval('body >*', getTags);\n const expected = ['header', 'main', 'footer'];\n assertDeepStrictEqual(actual, expected);\n });\n\n });\n\n/////////////////////////////////////////////////////////////////////////////////////\ndescribe('The document content', () => {\n before(loadWebPage);\n after(closeWebPage);\n\n it('has a 🚀 traveling to 🪐!', () => {\n const actual = { '🚀': !!web.html.match(/🚀/g), '🪐': !!web.html.match(/🪐/g) };\n const expected = { '🚀': true, '🪐': true };\n assertDeepStrictEqual(actual, expected);\n });\n\n });\n```\n**Output:**\n```\n The web page\n ✓ has the correct URL\n ✓ title starts with \"Pretty-Print JSON\"\n ✓ body has exactly one header, main, and footer -- node-html-parsed\n ✓ body has exactly one header, main, and footer -- page.$$eval()\n\n The document content\n ✓ has a 🚀 traveling to 🪐!\n```\n\n### Example 3: Start and shutdown a static web server\nThe [startWebServer(options) and shutdownWebServer(http)](spec/start-web-server.spec.js) functions\ncan be used in global fixtures to start and shutdown a static web server.\n\nFor example, the **spec/fixtures/setup-teardown.js** file below starts a web server on port `7123`\nwith the web root pointed to the project's **docs** folder.\n\n**Code:**\n```javascript\n// Specification Fixtures\nimport { browserReady } from 'puppeteer-browser-ready';\nlet http; //fields: server, terminator, folder, url, port, verbose\n\n// Setup\nconst serverOptions = { folder: 'docs', port: 7123 };\nconst mochaGlobalSetup = () =>\n browserReady.startWebServer(serverOptions).then(info => http = info);\n\n// Teardown\nconst mochaGlobalTeardown = () => {\n browserReady.shutdownWebServer(http);\n };\n\nexport { mochaGlobalSetup, mochaGlobalTeardown };\n```\nRun specification suites with global fixtures:
\n`$ npx mocha spec/*.spec.js --require spec/fixtures/setup-teardown.js`\n\n**Output:**\n```\n [2021-07-14T11:38:22.892Z] Web Server - listening: true 7123 http://localhost:7123/\n ...Output of Mocha specification suites here...\n [2021-07-14T11:38:26.704Z] Web Server - shutdown: true\n```\n\n## E) Test Timeout Errors\nBy default Mocha allows a test 2,000 ms to complete before timing out with a failure. \nWeb page load times can vary significantly, so it's sometimes a good idea to use the `timeout`\noption to bump up the allowed test execution time.\n\nExample configuration in **package.json** to allow 7,000 ms:\n```json\n \"scripts\": {\n \"pretest\": \"run-scripts clean build\",\n \"test\": \"mocha spec --timeout 7000\"\n },\n```\n\n
\n\n---\n[MIT License](LICENSE.txt)\n\nSee the `runScriptsConfig` section of [`package.json`](package.json) for a clean way to organize build tasks:\n - 🎋 [`add-dist-header`](https://github.com/center-key/add-dist-header) — _Prepend a one-line banner comment (with license notice) to distribution files_\n - 📄 [`copy-file-util`](https://github.com/center-key/copy-file-util) — _Copy or rename a file with optional package version number_\n - 📂 [`copy-folder-util`](https://github.com/center-key/copy-folder-util) — _Recursively copy files from one folder to another folder_\n - 🪺 [`recursive-exec`](https://github.com/center-key/recursive-exec) — _Run a command on each file in a folder and its subfolders_\n - 🔍 [`replacer-util`](https://github.com/center-key/replacer-util) — _Find and replace strings or template outputs in text files_\n - 🔢 [`rev-web-assets`](https://github.com/center-key/rev-web-assets) — _Revision web asset filenames with cache busting content hash fingerprints_\n - 🚆 [`run-scripts-util`](https://github.com/center-key/run-scripts-util) — _Organize npm package.json scripts into groups of easy-to-manage commands_\n - 🚦 [`w3c-html-validator`](https://github.com/center-key/w3c-html-validator) — _Check the markup validity of HTML files using the W3C validator_\n","readmeFilename":"README.md"}