PRICING
PRODUCT
SOLUTIONS
by use cases
AI Lead ManagementInvoicingSocial MediaProject ManagementData Managementby Industry
learn more
BlogTemplatesVideosYoutubeRESOURCES
COMMUNITIES AND SOCIAL MEDIA
PARTNERS
Puppeteer lets you automate Chrome or Chromium browsers, and choosing between headless or headful mode can significantly impact performance and debugging. Here's a quick breakdown:
Feature | Headless Mode | Headful Mode |
---|---|---|
Visual Interface | No GUI | Full GUI |
Resource Usage | Lower | Higher |
Execution Speed | Faster | Standard |
Memory Footprint | Smaller | Larger |
Debugging Ease | Console-based | Visual feedback |
New Headless Mode combines the performance of headless with improved debugging tools, making it a balanced choice for many workflows.
Choose:
This guide explains how to configure each mode, their benefits, and when to use them.
Standard headless mode is Puppeteer's default setup, running Chrome or Chromium without its graphical user interface (GUI). By skipping the GUI, it uses less memory, processes pages faster, and reduces CPU usage.
Key Features
Standard headless mode supports a wide range of browser operations, including:
Feature | What It Does |
---|---|
User Simulation | Handles clicks, form inputs, navigation |
Content Manipulation | Injects JavaScript, modifies the DOM |
Asset Generation | Captures screenshots, creates PDFs |
Network Monitoring | Tracks requests and responses |
Page Automation | Runs scripts, extracts content |
How to Use It
You can launch headless mode with the following code:
const browser = await puppeteer.launch(); // Default headless
// OR
const browser = await puppeteer.launch({ headless: true }); // Explicit headless
Why It’s Useful
Headless mode is ideal for tasks like web scraping, automated testing, and creating screenshots or PDFs. For example, Optimizely cut its testing cycle from 24 hours to just one hour by leveraging headless browser testing in the cloud.
Challenges to Keep in Mind
While it's efficient, headless mode comes with some hurdles:
To improve reliability and avoid detection, you can:
For even greater efficiency in specific server-side tasks, you might consider the chrome-headless-shell
variant. This lightweight option is perfect for automation-focused workflows. Launch it with:
const browser = await puppeteer.launch({ headless: 'shell' });
This mode is especially effective for server-side operations, offering streamlined performance.
Next, we’ll dive into Chrome’s new headless mode and how it takes performance to the next level.
Chrome has introduced an upgraded headless mode that brings browser automation to a new level. Unlike the older version, this mode uses the same codebase as the regular Chrome browser, ensuring better stability and access to all browser features. It combines the efficiency of headless operation with the functionality of a full browser, making automation and debugging much smoother.
The new headless mode operates by creating platform windows without displaying them. This allows you to use the browser's full capabilities while still enjoying the performance benefits of headless operation. Here's how you can use it in your code:
const browser = await puppeteer.launch({ headless: 'new' }); // Explicitly use new headless mode
// OR
const browser = await puppeteer.launch({ headless: true }); // Defaults to new headless mode
This mode also includes several tools to make debugging easier:
Feature | Purpose |
---|---|
Visual Inspection | View browser behavior (set headless: false ) |
Operation Timing | Use the slowMo option to delay actions |
Console Monitoring | Capture console output for analysis |
Protocol Analysis | Enable DevTools protocol logging |
Browser Diagnostics | Use dumpio: true for detailed logs |
1. Using DevTools for Debugging
You can enable Chrome's built-in DevTools to inspect browser behavior in detail:
const browser = await puppeteer.launch({
headless: 'new',
devtools: true
});
2. Performance Monitoring and Error Tracking
The shared codebase allows for precise performance profiling and error resolution. Use this setup to monitor and debug both client-side and server-side operations:
const browser = await puppeteer.launch({
headless: 'new',
devtools: true,
slowMo: 100,
args: ['--enable-logging', '--v=1']
});
Although the older headless mode (headless: 'old'
) is still available, it’s a good idea to switch to the new version. The legacy mode will eventually be phased out, so transitioning now ensures consistency and prepares you for future updates.
By using a unified codebase, the new headless mode delivers consistent behavior across various environments. This consistency reduces environment-specific issues and enhances the reliability of automated workflows.
Browser display mode opens a visible browser window during Puppeteer operations. While it uses more resources, it offers better debugging tools and visual feedback.
Running in display mode increases resource usage but provides some advantages:
const browser = await puppeteer.launch({
headless: false,
args: ['--enable-gpu-rasterization'],
defaultViewport: null
});
With a visible browser, GPU hardware acceleration can be enabled, which improves performance on image-heavy websites. Additionally, this mode reduces the chances of bot detection by mimicking standard browser behavior.
Display mode is ideal for troubleshooting, offering immediate visual feedback. Here's a useful debugging setup:
const browser = await puppeteer.launch({
headless: false,
devtools: true,
slowMo: 250,
defaultViewport: {
width: 1920,
height: 1080
}
});
This configuration opens DevTools automatically, introduces a 250ms delay for better inspection, and uses a standard viewport size for consistent testing.
Scenario | Benefits | Configuration Tips |
---|---|---|
Visual Debugging | See interactions in real-time | Enable DevTools, use slowMo |
GUI Testing | Observe user interface behaviors | Set a fixed viewport size |
Complex Workflows | Verify detailed interactions | Combine with console logging |
To keep things running smoothly in display mode:
"Sometimes it's useful to see what the browser is displaying. Instead of launching in headless mode, launch a full version of the browser with headless set to
false
." - Puppeteer Documentation
For more demanding tasks, you can enhance display mode with additional settings:
const browser = await puppeteer.launch({
headless: false,
args: [
'--enable-gpu-rasterization',
'--window-size=1920,1080',
'--disable-web-security'
],
dumpio: true
});
This setup improves visibility, enables detailed logging, and allows cross-origin access. These tweaks ensure a smoother experience and lay the groundwork for comparing performance and functionality in the next guide.
When setting up Puppeteer, each mode offers a different mix of speed, resource usage, and debugging capabilities. Picking the right one depends on your specific needs.
Here’s a breakdown of the modes:
Puppeteer leverages the Chrome DevTools Protocol for precise browser control, including network interception and JavaScript execution, allowing you to fine-tune configurations.
For instance, here’s how you can optimize the New Headless Mode:
const browser = await puppeteer.launch({
headless: 'new',
args: [
'--disable-gpu',
'--no-sandbox',
'--disable-setuid-sandbox'
]
});
Use Standard Headless for fast, resource-efficient automation, Browser Display for detailed debugging, or New Headless when you need a balance of performance and functionality.
When selecting a mode in Puppeteer, consider your project's specific goals and requirements. Puppeteer emphasizes speed, security, stability, and simplicity. Here's a breakdown to help you decide:
Standard Headless Mode is ideal if you need:
New Headless Mode works best when you require:
Browser Display Mode is suited for scenarios that involve:
Project Type | Recommended Mode | Key Advantage |
---|---|---|
CI/CD Pipeline Testing | Standard Headless | Fast execution with minimal resource usage |
Development & Debugging | Browser Display | Complete visual feedback and DevTools |
Production Automation | New Headless | A solid mix of features and performance |
Puppeteer’s API makes it easy to switch between these modes as your project evolves.