puppeteer/examples: a gallery of browser automation demos

A gallery of single-purpose scripts, not a framework

The repository description says use case-driven examples for using Puppeteer and headless chrome, and that is accurate down to the file layout. Every demo is a standalone script at the root of the tree. There is no `src/` directory, no entry point, no exported API and no test runner. The `package.json` has no `scripts` block at all, which means there is nothing to run through npm and every file is invoked directly:

node crawlsite.js
node element-to-pdf.js
node side-by-side-pageload.js

The README then does something unusual. Rather than documenting an API, it presents output. Each entry is a heading naming a file, one sentence of intent, and a screenshot or a YouTube link showing what the script produced. The whole page reads like a lab notebook where the artifact matters more than the recipe.

That design has an obvious appeal for anyone evaluating whether headless browser automation can handle a task before committing to it. Seeing a rendered coverage graph or a produced PDF answers a question faster than reading API documentation. The cost is that the README almost never explains how a script is configured, so the configuration lives in the script itself.

The project is licensed Apache 2.0, reports JavaScript as its primary language, sits under the `puppeteer` organisation, and points its homepage field at `https://developers.google.com/web/tools/puppeteer/`. It is not archived and the last recorded push is 2026-06-21.

Coverage and service worker caching, the two checks worth stealing

`code_coverage.js` is described as testing a lazy loading strategy by seeing CSS and JavaScript code coverage usage across a page load. That is a sharper framing than a coverage percentage, because coverage on its own says nothing about waste. If a page reports high coverage and the screenshot shows a lot of unused rules, the lazy loading strategy is doing nothing.

`verify_sw_caching.js` is described as verifying that all the resources you expect are being cached by a service worker for offline use. Service workers fail quietly. A worker registers, claims a fetch handler, and either serves from cache or quietly falls through to the network, and nothing in the browser UI tells you which happened for a given URL. A script that loads the page, then reloads it, then inspects what came from cache is exactly the check most teams skip.

These two are the strongest entries in the collection because they answer questions that are awkward to express as an assertion in a normal test suite. The screenshots in the README are the payoff: a coverage graph and a table of cached versus network responses are legible at a glance in a way a passing test name is not.

Both also share a limit. They are written against a real site, and the README does not say which one or how the target URL is passed. Expect to read the top of each file to find the argument handling before you point either script at your own project.

Search visibility checks that predate the current SEO tooling

`google_search_features.js` is a gut check that a page renders correctly for Google Search, and `lazyimages_without_scroll_events.js` determines whether lazy loaded images will be seen correctly by Google Search. Both are aimed at a real failure mode: a page that works in a normal browser and renders as an empty shell to a crawler.

The dates attached to the screenshots tell you when this was the live concern. The Google search features screenshot is stamped 2018-03-07 and the lazy images one 2018-10-09. At that point rendering a JavaScript application as a crawler saw it was still an open question, and a script that loads a page and captures what appeared was a legitimate diagnostic.

Today the same class of question is usually answered by a crawler simulation mode in a general purpose auditing tool rather than by a bespoke script. That does not make these files useless. A before and after screenshot of your own page before and after you change a `robots.txt` or a lazy loading attribute is still a clearer artifact than a score change, and the scripts remain readable reference implementations for driving a browser and capturing a screenshot.

What the repository does not do is track search engine behaviour. It captures rendering. If you need to know how a specific crawler behaves, the modern answer lives in search engine documentation, not here.

Turning a page into assets: PDF, screenshots and a site map

Three entries turn a browser into a document producer, and these are the ones you can most usefully steal today.

`element-to-pdf.js` turns a DOM element into a PDF. The phrasing matters: it is not page to PDF, it is element to PDF, which is the harder and more useful version. The usual libraries rasterise a viewport or rely on the browser print dialog, while an element scoped export has to isolate the node, deal with its computed styles and produce output sized to the node rather than to the paper.

`crawlsite.js` discovers all the URLs on a site and visualises the subpages. Discovery of this kind sounds trivial until you meet a single page application, where most URLs never appear in the initial HTML. A browser that follows links after rendering sees routes that a plain HTTP crawler cannot, which is why the output is described as a crawl of a site and a single page application.

`side-by-side-pageload.js` loads two or more pages side by side to visually compare page load, with optional desktop viewport and throttling settings. This is the most quietly useful script in the collection. Page load regressions are almost always visual and comparative: what does the page look like at the moment the load indicator disappears, and how does that differ from last week's build. Loading two URLs in one browser and putting the captures next to each other answers that in a way that a numeric metric does not.

`pacman.js` and `speech.js` are the opposite case. The README calls them making your browser talk and playing the Google Pac-Man Doodle, and they are there to show that the browser can be driven for things no test suite would ever assert. Read them as proof of capability rather than as tools.

The dependency list dates the code to 2018

The `package.json` is the single most informative file in the repository, and not because of what it enables. It pins `puppeteer` at `^1.11.0`, `lighthouse` at an alpha of the 4.0 line, `sharp` at `^0.21.1`, `chrome-har` at `^0.7.1` and `pixel-diff` at `^1.0.1`, and it declares `node` as `>=8`. The package version itself is `0.0.1`, which is consistent with a gallery rather than a released tool.

"puppeteer": "^1.11.0",
"lighthouse": "^4.0.0-alpha.2-3.2",
"sharp": "^0.21.1"

That dependency set tells you what each demo needs and what era it came from. `sharp` and `pngjs` together mean image work for the screenshots, `pixel-diff` means visual comparison, `chrome-har` means network capture, and `caniuse-db` plus `chrome-launcher` suggest a script that varies behaviour across browser versions. The tree supports this reading with `cdp/`, `lighthouse/`, `html/` and `output/` directories, plus a `server.js` for serving fixtures locally.

The practical consequence is that installing the repository today gives you a Puppeteer major version from 2019, whose launch and protocol APIs differ substantially from current releases. Expect to fix call sites rather than to run the scripts unchanged, and treat any script that still uses the old launch options as a rewrite candidate.

Ten scripts in the tree that the README never mentions

The README lists nine demos. The tree lists considerably more: `connect.js`, `detect_sound.js`, `fullscreen.js`, `hash_navigation.js`, `monitor_internet_connection.js`, `screenshot_element_on_tab.js`, `server.js`, `verify_download.js`, `verify_download2.js` and `view-source.js` sit alongside the documented ones. Several come in pairs, and `verify_download.js` and `verify_download2.js` are the clearest example of a file that was revised in place rather than renamed.

That gap between README and tree is worth naming plainly, because it changes how you read the project. The README is a curated highlight reel, not an index. If you want to know what the collection actually contains, the tree is the authority, and several undocumented files cover things a testing library handles poorly: verifying that a download actually completed, watching network connectivity changes from inside the page, and capturing audio.

One inconsistency in the metadata is worth knowing about. The `bugs` field in `package.json` points at `https://github.com/GoogleChromeLabs/puppeteer-examples/issues`, and the README footer reads Apache 2.0 (c) 2018 Google Inc., while the repository now lives under the `puppeteer` organisation. The code moved; the issue tracker reference and licence footer did not. If you plan to file an issue, use the tracker on the repository you are reading rather than the one in the manifest.

Editorial conclusion

This repository earns its place as a cookbook, not as a library. Nine README entries each solve one narrow, annoying browser question, and several of them, especially the service worker caching check and the side by side page load comparison, solve questions that general purpose testing tools answer badly. What it is not is maintained software: a Puppeteer 1.x dependency list and a README footer that still reads 2018 mean you should read the scripts before running them and expect small API fixes. Start with crawlsite.js or element-to-pdf.js, since those need no third party site to make sense of, then look at verify_sw_caching.js if you own a service worker.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. Project website
4. puppeteer/examples on GitHub
5. README