What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
First identify which stage is failing: browser installation, Chrome launch, page navigation, or screenshot comparison. A Puppeteer update can also update the browser it downloads, so a changed screenshot is not automatically a BackstopJS or application regression. Check the exact error, dependency lockfile, browser version, and CI environment before changing configuration.
Identify what failed before changing versions
Record the complete error output and where it appears. BackstopJS runs browser automation and compares rendered pages; the same vague “test failed” result can stem from different causes.
As an Amazon Associate I earn from qualifying purchases.
- Missing browser: errors such as “Could not find Chrome” point first to browser installation or cache configuration.
- Launch or crash: Chrome is present but exits, hangs, or reports missing system libraries, permissions, or sandbox problems.
- Navigation failure: the browser launches but cannot load the target page or times out. Investigate the target, network, and wait conditions rather than assuming a launch-option problem.
- Image-diff failure: pages render, but BackstopJS reports changed snapshots. Check for browser or environment drift before treating the difference as a product change.
Note whether the failure is local or CI-only. Capture the Node.js version, BackstopJS and Puppeteer versions, operating system or CI/container image, and the failing scenario. Without these details, there is no evidence-based exact version pin or universal config patch.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsCheck which Puppeteer and browser versions are in use
Inspect package.json and the lockfile, including whether the project uses puppeteer directly or receives puppeteer-core transitively. Reproduce from a clean dependency installation if practical, keeping the lockfile and runtime environment fixed so you can distinguish a dependency change from unrelated drift.
#1 Best Overall
Compare the installed Puppeteer version with the official Puppeteer supported-browser table. Puppeteer’s package version is paired with a specific browser build; if you supply Chrome or Chromium yourself, check that build against the table and confirm the executable path used by the test.
The Puppeteer maintainers explain the compatibility reason in their FAQ: “Every Puppeteer release is tightly bundled with a specific browser release to ensure compatibility with the implementation of the underlying protocols, the Chrome DevTools Protocol and WebDriver BiDi.” Pinning only the automation package while silently changing an external browser can therefore leave the project with an unverified pairing.
Fix a missing Chrome or Chromium download
The standard puppeteer package downloads a compatible browser through its installation script. A package manager or CI policy that blocks dependency install scripts may install the package without downloading that browser. Puppeteer’s installation guide documents the manual browser installation command:
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Rank #2
npx puppeteer browsers install
Run it in the project environment where the relevant Puppeteer package is installed, then rerun the failing BackstopJS command. Check the install output and configured cache location if Chrome still cannot be found; Puppeteer’s troubleshooting guide describes configuring PUPPETEER_CACHE_DIR when the default cache path does not suit the environment.
If the project deliberately manages a system browser instead of downloading one, verify that the executable exists in the test environment and that BackstopJS is pointed at it. Puppeteer recommends puppeteer-core for projects that manage browser downloads themselves; it does not provide the bundled-browser installation behavior of puppeteer. Choose one installation strategy deliberately rather than reinstalling BackstopJS as a catch-all remedy.
Put BackstopJS launch overrides in engineOptions
BackstopJS exposes Puppeteer settings through engineOptions, where options can be added or defaults overridden. Review the configuration actually loaded by the failing command, including any environment-specific config, before applying flags copied from an unrelated issue.
A minimal shape for the relevant configuration is:
module.exports = { engine: "puppeteer", engineOptions: { args: [] } };
This only illustrates where launch arguments belong; it is not a complete BackstopJS configuration or a recommendation to add a particular argument. Use the BackstopJS documentation and project README to check the current engine settings and the project’s installed version. Add a launch flag only when the error and execution environment justify it. For example, do not add --no-sandbox by default: first establish that sandboxing is the actual launch obstacle and understand the security trade-off in the host environment.
Diagnose CI and container launch failures
A browser that launches locally but not in CI often exposes differences in system libraries, permissions, home directories, or container configuration. Match the fix to the runner and error rather than applying a generic Docker recipe.
Rank #4
- Used Book in Good Condition
- Missing Linux libraries: inspect Chrome’s launch output and install the dependencies required by the browser on the specific base image.
- Cache or profile path is not writable: check the user running the job and the permissions of the Puppeteer cache and browser profile paths. Configure a writable cache location when needed.
- Sandbox or container restriction: determine whether the environment permits Chrome’s sandbox and only alter launch arguments if the observed failure calls for it.
- Alpine image: check Puppeteer’s documented Alpine-specific compatibility requirements instead of assuming a Debian/Ubuntu dependency list applies.
Puppeteer’s troubleshooting guide covers missing Linux dependencies, restricted container paths, and Alpine considerations. Compare the local and CI image, user, environment variables, and browser executable; a dependency update may reveal an existing environment mismatch rather than introduce the sole cause.
When tests run but screenshots changed
If Chrome starts and navigation succeeds, establish whether the output change comes from the browser build or the page under test. Compare the old and new Puppeteer/browser pairing, operating-system or container image, installed fonts, viewport, and target page state. Also check whether the scenario’s waits still capture the intended page state.
BackstopJS is a visual regression tool, and Puppeteer releases are paired with browser releases. That makes rendering drift a plausible explanation, not proof that the new browser caused every pixel difference. Review the diff and page behavior first; update reference images only after confirming the new rendering is expected.
Best Value
When to change engines or pin dependencies
If the project needs reproducible screenshots, keep the dependency lockfile, Node runtime, browser build, and CI image controlled together. Whether to use Puppeteer’s downloaded browser or manage an external executable depends on whether the project can install and cache the browser in every environment.
| Approach | Useful when | Trade-off to manage |
|---|---|---|
Use the browser downloaded for the installed puppeteer release |
You want Puppeteer’s paired browser and can run its browser installation in local and CI environments. | Ensure installation scripts and browser caching work in each environment. |
Manage an external browser with puppeteer-core |
Your team controls the browser image or executable separately. | Keep the browser build compatible with Puppeteer and configure the executable path consistently. |
Do not switch engines just to work around one unexplained failure. BackstopJS also documents a Playwright engine; its README says to change the engine and the associated onBefore/onReady scripts together. Treat that as a migration with its own compatibility checks, not a drop-in fix for an unclassified Puppeteer error.
Troubleshooting checklist
| Symptom | Likely area to inspect | Next action |
|---|---|---|
| “Could not find Chrome” | Install script, browser cache, or executable configuration | Check whether install scripts ran; install with npx puppeteer browsers install if appropriate, then verify the cache or configured browser path. |
| Chrome exits during launch in CI | System libraries, permissions, sandbox, or container image | Use the launch error to identify the missing dependency or restriction; consult Puppeteer’s environment-specific troubleshooting steps. |
| Only Alpine-based jobs fail | Alpine-specific browser compatibility | Check the documented Alpine requirements for the installed Puppeteer/browser combination. |
| Browser runs but page times out | Navigation, target availability, or scenario wait conditions | Confirm the page is reachable in that environment and inspect the scenario’s timeout and readiness conditions. |
| Browser runs but snapshots differ | Browser, OS, fonts, viewport, or target state changed | Compare those inputs and review the rendered difference before accepting new reference images. |
Or skip the browser setup
If your goal is to capture a page rather than maintain a local browser test rig, ScreenshotNeo provides a screenshot API and MCP server. One GET request returns an image or PDF; the request below saves a WebP screenshot. See the ScreenshotNeo API documentation for request options.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
Quick Recap
ScreenshotNeo accepts cookie/consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; those steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status. Its MCP server includes tools for AI agents to take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots. Sign up free for ScreenshotNeo.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
