DEV Community

Swiftproxy - Residential Proxies
Swiftproxy - Residential Proxies

Posted on

Puppeteer Stealth Guide for Automated Browsing

#puppeteer

A large portion of web traffic today comes from bots, which might surprise you. However, not all bots are welcomed. Websites have grown more sophisticated, using tools like Cloudflare and anti-spam scripts to detect and block automated traffic. If you use Puppeteer without any tweaks, you’re likely to face captchas, IP bans, and frequent roadblocks.
That’s why Puppeteer Stealth exists. It disguises your bot as a real human — masking browser fingerprints, mimicking mouse movements, and wiping out automation footprints.
In this guide, you’ll learn how to install and enable Puppeteer Stealth effortlessly, use key plugins and settings to dodge anti-bot defenses, and test your setup to avoid blocks and interruptions.

Step 1: Launch Puppeteer and Enable Stealth Mode

Start by installing the core Puppeteer library, the extra plugin system, and the stealth plugin. It’s quick:
npm install puppeteer puppeteer-extra puppeteer-extra-plugin-stealth

Here’s the breakdown:

  • puppeteer: The heart of browser automation.
  • puppeteer-extra: Enables plugin support.
  • puppeteer-extra-plugin-stealth: The magic that hides your automation traces.

By default, Puppeteer screams "I'm a bot!" with headers like HeadlessChrome. The stealth plugin fixes that.

Step 2: Connect and Launch Puppeteer with Stealth

Create an index.js file and add this:

const puppeteer = require('puppeteer-extra'); const StealthPlugin = require('puppeteer-extra-plugin-stealth'); puppeteer.use(StealthPlugin()); (async () => { const browser = await puppeteer.launch({ headless: true }); const page = await browser.newPage(); await page.goto('https://bot.sannysoft.com/'); await page.screenshot({ path: 'result.png' }); console.log('Test complete. Screenshot saved.'); await browser.close(); })();
Enter fullscreen mode Exit fullscreen mode

Run this. Then check result.png. That page is a bot detection goldmine. If your screenshot looks normal, you’re on the right track.

Step 3: Fine-Tune Startup Parameters for Maximum Realism

Make Puppeteer’s browser look even more like a human user by adding these flags when launching:

const browser = await puppeteer.launch({ headless: true, args: [ '--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage', '--disable-accelerated-2d-canvas', '--disable-gpu' ] });
Enter fullscreen mode Exit fullscreen mode

Why these? They reduce resource usage, avoid sandbox conflicts, and sidestep potential detection triggers. A lean, stealthy browser runs smoother and less suspicious.

Step 4: Test Your Setup on Trusted Sites

Use these sites to confirm your bot isn’t flagged:

  • bot.sannysoft.com – Comprehensive bot behavior test.
  • whatismybrowser.com – Reveals browser fingerprint details.
  • httpbin.org/headers – Shows exactly what headers your bot sends.

Run your Puppeteer script against these URLs. Adjust until your bot blends perfectly.

Step 5: Add a Proxy to Mask Your IP

Sending all requests from one IP is a red flag. Proxies solve this by rotating IP addresses, keeping your requests anonymous and distributed.

Choose your proxy type:

  • Server proxies for speed and stability.
  • Mobile proxies to mimic real mobile device IPs — harder to detect.

How to add a proxy:

const browser = await puppeteer.launch({ headless: true, args: ['--proxy-server=http://username:password@proxy_address:port'] });
Enter fullscreen mode Exit fullscreen mode

Replace username, password, and proxy_address with your proxy details.

Step 6: Proxy Rotation to Avoid IP Bans

Rotate proxies on every request to stay ahead of bans. Here’s a simple way:

const proxyList = [ 'http://user1:pass1@proxy1_address:port', 'http://user2:pass2@proxy2_address:port', 'http://user3:pass3@proxy3_address:port' ]; const getRandomProxy = () => proxyList[Math.floor(Math.random() * proxyList.length)]; (async () => { for (let i = 0; i < 5; i++) { const proxy = getRandomProxy(); const browser = await puppeteer.launch({ headless: true, args: [`--proxy-server=${proxy}`] }); const page = await browser.newPage(); await page.goto('https://httpbin.org/ip'); console.log(`Request made via proxy: ${proxy}`); await browser.close(); } })();
Enter fullscreen mode Exit fullscreen mode

This distributes requests, reduces the risk of IP blocks, and helps keep your scraping uninterrupted.

Step 7: Test Proxy Stability Before Scaling

Don’t skip this. Test your proxies for:

  • Reliability: Load multiple pages sequentially.
  • Speed: Slow proxies drag down your whole process.
  • Geolocation: Match proxies to the target region for best results.

Step 8: Final Testing and Debugging

Even after all this, bugs can slip in. Access denied errors, unexpected browser crashes — watch out.

Verify your setup by revisiting test sites:

  • bot.sannysoft.com
  • whatismybrowser.com
  • httpbin.org/headers

Use this code snippet for a final stealth check:

const puppeteer = require('puppeteer-extra'); const StealthPlugin = require('puppeteer-extra-plugin-stealth'); puppeteer.use(StealthPlugin()); (async () => { const browser = await puppeteer.launch({ headless: true }); const page = await browser.newPage(); await page.goto('https://bot.sannysoft.com/'); await page.screenshot({ path: 'stealth-test.png' }); console.log('Test complete. Screenshot saved.'); await browser.close(); })();
Enter fullscreen mode Exit fullscreen mode

Check your screenshot. If your bot passes these tests, congratulations — you have a stealthy, resilient Puppeteer setup.

Wrapping Up

Anti-bot defenses are tough, but not unbeatable. With Puppeteer Stealth, smart proxy use, and careful testing, your scripts will run smoothly and invisibly. No more blocks. No more captchas. Just pure data collection power.

Top comments (0)