Workflow:Puppeteer Puppeteer Cross Browser Automation
| Knowledge Sources | |
|---|---|
| Domains | Browser_Automation, Cross_Browser_Testing, Protocol_Selection |
| Last Updated | 2026-02-11 23:30 GMT |
Overview
End-to-end process for configuring and running Puppeteer automation across different browsers (Chrome and Firefox) and protocols (CDP and WebDriver BiDi).
Description
This workflow covers the standard procedure for running Puppeteer automation scripts against multiple browser engines. Puppeteer supports Chrome (via CDP or WebDriver BiDi) and Firefox (via WebDriver BiDi). The workflow demonstrates how to install the target browser binary using the @puppeteer/browsers package, configure browser-specific launch options (browser type, extra preferences, executable path), select the communication protocol, and execute the same automation logic across different browser environments. The WebDriver BiDi protocol is the modern cross-browser standard that enables Puppeteer to work with Firefox natively.
Usage
Execute this workflow when you need to verify that web automation scripts or tests work correctly across multiple browser engines. This is essential for cross-browser compatibility testing, ensuring consistent behavior across Chrome and Firefox, migrating from CDP to WebDriver BiDi protocol, or when Firefox-specific testing is required.
Execution Steps
Step 1: Install Target Browser
Ensure the target browser binary is available locally. Puppeteer automatically downloads a compatible Chrome binary during npm install. For Firefox or other browsers, use the @puppeteer/browsers CLI or programmatic API to download and cache the browser binary. Alternatively, provide a path to an existing browser installation.
Key considerations:
- Chrome is downloaded automatically by the puppeteer package
- Firefox requires explicit installation: npx puppeteer browsers install firefox
- The @puppeteer/browsers package manages download, caching, and version resolution
- Custom binaries can be specified via executablePath in launch options
Step 2: Configure Browser Launch Options
Prepare the launch configuration specifying the target browser and protocol. For Chrome, the default protocol is CDP; for Firefox, WebDriver BiDi is used. Browser-specific preferences can be passed (e.g., Firefox extra preferences, Chrome launch arguments).
Configuration options:
- browser: 'chrome' or 'firefox' to select the browser engine
- protocol: 'cdp' or 'webDriverBiDi' to select the communication protocol
- extraPrefsFirefox: object with Firefox-specific about:config preferences
- args: array of browser command-line arguments (Chrome)
- dumpio: boolean to pipe browser process stdout/stderr for debugging
Step 3: Launch Browser With Configuration
Pass the configured options to puppeteer.launch() to start the browser process. The launcher selects the appropriate browser binary (from cache or executablePath), computes the command-line arguments for the target browser, starts the subprocess, and establishes the protocol connection.
Key considerations:
- The launcher automatically selects Chrome or Firefox launcher based on browser option
- Protocol negotiation happens during connection establishment
- Use DEBUG=puppeteer:launcher environment variable for debugging launch issues
- Browser version information is available via browser.version()
Step 4: Execute Automation Logic
Run the automation script against the launched browser. The Puppeteer API surface is consistent across browsers and protocols, allowing the same page creation, navigation, interaction, and evaluation code to work with both Chrome and Firefox.
Key considerations:
- Most core APIs work identically across browsers
- Some CDP-specific features (Tracing, Coverage) are only available with Chrome CDP
- WebDriver BiDi is the recommended protocol for cross-browser compatibility
- Check the supported browsers documentation for feature parity details
Step 5: Verify Browser Behavior
Optionally verify browser-specific behavior by checking the browser version, testing browser-specific rendering, or comparing results across browser engines. This step is particularly important for cross-browser test suites.
Key considerations:
- Use browser.version() to confirm the correct browser is running
- Be aware of rendering differences between Chrome and Firefox
- Some selectors or DOM behaviors may differ across browsers
Step 6: Close Browser
Terminate the browser process and clean up resources. This is identical across all browsers and protocols.