Choosing a Chrome for Testing Revision Strategy in Puppeteer CI Pipelines

Recommended Strategy: Pinned Chrome for Testing

For CI pipelines, pinning a specific Chrome for Testing (CfT) revision provides the best balance of stability and freshness. Dynamically selecting the latest system Chrome introduces non-deterministic failures when the browser updates independently of the Puppeteer library, often leading to Chrome DevTools Protocol (CDP) mismatches.

Implementation and Update Cadence

To maintain security without sacrificing reproducibility, adopt a 4-to-6 week update cycle. This aligns with the Chrome stable release cadence, ensuring security patches are integrated while allowing teams to validate the new revision in a staging environment before updating the production pipeline.

To implement this in a Dockerized CI environment, avoid relying on system-installed Chrome. Instead, use the Puppeteer-managed download and cache the binary to prevent redundant network calls:

# Example: Setting the cache directory for Docker persistence
export PUPPETEER_CACHE_DIR=/home/node/.cache/puppeteer
npm install

Headless Mode and Stability

The choice between headless: true and headless: 'shell' significantly impacts flakiness during revision changes:

• headless: true (New Headless): This is the recommended standard for Puppeteer v22+. It is a full browser implementation and is generally more resilient to revision updates.
• headless: 'shell' (Chrome-headless-shell): This is a stripped-down binary. While faster, it is highly sensitive to the exact Chrome revision and more prone to breaking when the underlying CDP implementation shifts.

Comparison Summary

Strategy	Reproducibility	Security Freshness	Risk Factor
Pinned CfT Revision	High	Controlled	Low (predictable)
Latest System Chrome	Low	Immediate	High (version drift)

Verification Steps

When bumping a pinned revision, perform these checks to ensure stability:

1. Run a smoke test suite focusing on network interception and page contexts, as these are most sensitive to CDP changes.
2. Verify the binary path in the CI logs to ensure the PUPPETEER_CACHE_DIR is being hit rather than a fresh download.
3. Confirm that headless: true renders the expected DOM elements by taking a few diagnostic screenshots during the first run of the new revision.

Diagnostic Detail Required: Are you using puppeteer or puppeteer-core? If using puppeteer-core, you must manually manage the executablePath, which changes the recommendation for binary caching.