Puppeteer Stealth: Setup, Detection Tests, and When to Switch
Puppeteer is a strong headless browser library for automating real user interactions, but its default configuration leaves automation traces that anti-scraping systems can spot. The Puppeteer Stealth plugin, distributed as puppeteer-extra-plugin-stealth and hosted by Puppeteer Extra, patches a set of those traces. This guide walks through installing and configuring the plugin, running two public detection tests before and after, scraping a product page as a worked example, and deciding when the plugin is not enough.
What Puppeteer Stealth changes
Puppeteer Stealth is an extension for Puppeteer built on top of Puppeteer Extra. It targets browser fingerprinting and evasion gaps that anti-scraping systems use to flag automation. The plugin ships with 17 evasion modules.
The main mechanisms are:
- Fingerprint modification. The plugin rewrites signals that headless sessions normally broadcast. Two examples are the
headless: truelaunch marker and thenavigator.webdriverproperty; both are altered so the session looks less like a scripted browser. Other automation-revealing properties and behaviors are adjusted as well. - Built-in evasion modules. Individual modules cover specific detection tricks. One hides the
sourceurlattribute; another adjustsnavigator.languagesso the browser resembles a normal Chrome install. The complete list lives in the plugin documentation. - Human-like behavior. Mouse movements and keyboard input are simulated to reduce the chance of triggering anti-scraping scripts.
The plugin is not a guarantee. The project's own documentation notes that some advanced detection systems can still identify automated activity. The design goal is to make detection expensive enough that it becomes impractical, not to make it impossible.
Baseline: what default Puppeteer reveals
Before adding the plugin, the source guide runs two public tests to show how the default setup behaves. The outcomes below are the captured reference results from that guide, not a fresh test run performed for this page.
Test 1 uses the headless detection page at https://arh.antoinevastel.com/bots/areyouheadless. In a normal browser, the page confirms it is not headless. In the captured default Puppeteer run, the page reported chrome headless, meaning the headless browser was detected.
Test 2 uses the fingerprint test at https://bot.sannysoft.com/. In the captured default Puppeteer run, the results showed red bars, indicating that bot fingerprints were detected.
Both baseline results point to the same conclusion: default Puppeteer has limited ability to bypass bot detection and usually needs manual overrides. The two scripts used for these tests are provided as code modules alongside this page. Re-run them in your own environment before drawing conclusions about a specific target.
Install and configure the plugin
Puppeteer Extra is the host that lets you add plugins such as the Stealth plugin. Install both packages with npm; the exact install command is provided as a code module alongside this page.
Then import Puppeteer Extra, import the Stealth plugin, and register it with default settings so all evasion modules are active. The default settings are the simplest starting point; the plugin README covers how to customize individual modules.
If you use CommonJS, the equivalent require form is provided in the code modules. The launch call in the source uses headless: "new"; the full worked example later uses headless: true. Both are valid launch options in the captured code.
Launch, navigate, and verify the plugin
After registering the plugin, launch the browser, open a page, set a viewport (the example uses 1280 by 720), and navigate to the target. The worked example navigates to an Amazon product page for a Meta Quest listing. Take a screenshot and close the browser when done.
Re-run the two detection tests with the plugin active. In the captured reference run, the headless detection page reported not chrome headless and the fingerprint test reported fingerprints not detected. Those outcomes indicate the plugin is masking the automation traces that the default setup exposed.
Passing these two public tests is a useful signal, but it is not proof that every anti-bot system will treat the session as human. Treat the results as one checkpoint in your own verification, not as a blanket clearance.
Worked example: scraping a product page
The worked example extracts six fields from the Amazon product page. The selectors below are the ones used in the captured code; treat them as a starting point and re-check them if the page markup changes.
- Title:
#productTitle, read fromtextContentand trimmed. - Price:
span.a-offscreen, read fromtextContentand trimmed. - Description:
#productDescription, read fromtextContentand trimmed. - Image URL:
#landingImage, read from thesrcattribute. - Rating:
#acrPopover, read from thetitleattribute without of 5 starsremoved. - Number of reviews:
#acrCustomerReviewText, read fromtextContentand trimmed.
The extracted values are stored in a product data object with the keys Title, Price, Description, Image Link, Rating, and Number of Reviews. The object is written to product_data.json using fs/promises, and the browser is closed at the end. The full script is provided as a code module alongside this page.
A useful check before trusting the output: confirm that each selector still resolves on the current page markup. If a selector returns null or throws, the field is missing rather than empty, and the JSON output will reflect that.
Where the plugin falls short
The plugin reduces detection, but three limits matter in practice:
- Advanced anti-bot systems. Services such as Cloudflare and DataDome can still detect and block scripts even with the plugin active.
- Performance overhead. The plugin adds work to each session and can slow execution.
- Maintenance. The plugin needs correct configuration and regular updates to keep pace with new detection methods.
Rate limits are a separate failure mode. Making many requests in a short window can trigger CAPTCHA challenges even when the fingerprint looks clean. The source author reported hitting an Amazon CAPTCHA after running the scraper repeatedly; that is a captured observation, not a result reproduced for this page. Practical mitigations include throttling requests, rotating proxies, and integrating a CAPTCHA-solving service. None of these removes the underlying arms race: anti-bot vendors keep updating, and open-source evasion packages keep patching.
Alternatives to consider
When the plugin is not enough, several alternatives are commonly used. The descriptions below reflect the captured reference material and should be re-checked against each project's current status before relying on them.
- Selenium Stealth. Selenium exposes automation features and command-line flags that anti-bot systems can pick up easily. This plugin masks many of those leaks so a Selenium session is harder to flag.
- Undetected ChromeDriver. A modified ChromeDriver that patches many of the signals anti-bot services use to spot Selenium bots. The captured description names Cloudflare, Distil Network, Imperva, and DataDome as targets, and notes that the result looks more human than a standard driver.
- Nodriver. A Python library derived from Undetected ChromeDriver, aimed at CAPTCHAs and WAFs such as Cloudflare. Instead of going through Selenium or webdriver binaries, it talks to the browser directly, which the captured description says lowers detection rates and improves performance.
- Cloudscraper. A Python library built on Requests that mimics a real browser to get past Cloudflare's anti-bot challenges.
A shared risk with open-source evasion packages is that anti-bot vendors can study their methods and patch the vulnerabilities they rely on. That is why the choice is often between maintaining an in-house evasion stack and using a managed scraping API that handles the bypass work for you.
Decision checklist
Use this checklist to choose between the plugin, an alternative library, and a managed API.
- Does the target pass the two public detection tests with the plugin active? If not, the plugin alone is unlikely to be enough.
- Does the target use Cloudflare, DataDome, or a similar advanced system? If yes, plan for an alternative or a managed API from the start.
- Are you hitting CAPTCHAs after a small number of requests? That points to rate limiting rather than fingerprinting; add throttling and proxy rotation before changing tools.
- Can you maintain the plugin and its evasion modules over time? If not, a managed API removes that maintenance burden.
- Do you need a specific language or runtime? Nodriver and Cloudscraper are Python-based; the Puppeteer Stealth plugin is JavaScript-based.
- Is the target page markup stable? If selectors change often, budget time for selector maintenance regardless of which tool you use.
Frequently asked questions
What is Puppeteer Stealth?
It is the puppeteer-extra-plugin-stealth package, an extension for Puppeteer built on top of Puppeteer Extra. It patches browser fingerprinting and other automation traces so headless sessions are harder to detect. The plugin ships with 17 evasion modules.
Does Puppeteer Stealth guarantee that a site will not detect my scraper?
No. The project's documentation notes that some advanced detection systems can still identify automated activity. The plugin's goal is to make detection expensive enough to be impractical, not to make it impossible.
Which public tests can I use to check whether the plugin is working?
Two tests are used in this guide: the headless detection page at arh.antoinevastel.com/bots/areyouheadless and the fingerprint test at bot.sannysoft.com. In the captured reference run with the plugin active, the first reported not chrome headless and the second reported fingerprints not detected. Passing both is a useful signal but not proof against every anti-bot system.
Why do I still get CAPTCHAs after enabling the plugin?
CAPTCHAs often come from rate limits rather than fingerprinting. Sending many requests in a short window can trigger a challenge even when the browser looks human. Throttling requests, rotating proxies, and integrating a CAPTCHA-solving service are the mitigations described in this guide.
Can I use the plugin with CommonJS?
Yes. The same packages can be loaded with require instead of import. The CommonJS form is provided in the code modules alongside this page.