How can I use Puppeteer with Chrome extensions?

Yes, you can use Puppeteer with Chrome extensions, but there are specific requirements and limitations to consider. Chrome extensions only work when running Puppeteer in headful mode (not headless) and require special launch arguments.

Basic Setup

To load a Chrome extension with Puppeteer, use the --load-extension and --disable-extensions-except flags:

const puppeteer = require('puppeteer');

async function runWithExtension() {
    const extensionPath = '/absolute/path/to/your/extension';

    const browser = await puppeteer.launch({
        headless: false, // Required for extensions
        args: [
            `--disable-extensions-except=${extensionPath}`,
            `--load-extension=${extensionPath}`,
            '--no-sandbox',
            '--disable-setuid-sandbox'
        ]
    });

    const page = await browser.newPage();
    await page.goto('https://example.com');

    // Your automation code here

    await browser.close();
}

runWithExtension();

Loading Multiple Extensions

You can load multiple extensions by separating paths with commas:

const extensionPaths = [
    '/path/to/extension1',
    '/path/to/extension2',
    '/path/to/extension3'
];

const browser = await puppeteer.launch({
    headless: false,
    args: [
        `--disable-extensions-except=${extensionPaths.join(',')}`,
        `--load-extension=${extensionPaths.join(',')}`
    ]
});

Working with Unpacked Extensions

For development extensions (unpacked), point to the extension directory:

const puppeteer = require('puppeteer');
const path = require('path');

async function runWithUnpackedExtension() {
    // Absolute path to your unpacked extension directory
    const extensionPath = path.resolve(__dirname, 'my-extension');

    const browser = await puppeteer.launch({
        headless: false,
        args: [
            `--disable-extensions-except=${extensionPath}`,
            `--load-extension=${extensionPath}`,
            '--disable-web-security', // Sometimes needed for dev extensions
            '--disable-features=VizDisplayCompositor'
        ]
    });

    const page = await browser.newPage();

    // Wait for extension to load
    await page.waitForTimeout(2000);

    await page.goto('https://example.com');
    await browser.close();
}

Finding Extension Background Pages

You can access extension background pages for debugging:

async function accessExtensionPages() {
    const browser = await puppeteer.launch({
        headless: false,
        args: [`--load-extension=${extensionPath}`]
    });

    // Get all pages (includes extension pages)
    const pages = await browser.pages();

    // Find extension pages
    const extensionPages = pages.filter(page => 
        page.url().startsWith('chrome-extension://')
    );

    console.log('Extension pages:', extensionPages.map(p => p.url()));

    await browser.close();
}

Using User Data Directory

For extensions requiring authentication or persistent data:

const userDataDir = './chrome-user-data';

const browser = await puppeteer.launch({
    headless: false,
    userDataDir: userDataDir,
    args: [
        `--load-extension=${extensionPath}`,
        '--disable-extensions-except=' + extensionPath
    ]
});

Important Limitations

Extension Automation

No direct extension UI interaction: You cannot directly click extension buttons or interact with extension popups through Puppeteer
Background script access: Limited ability to interact with extension background scripts
Content script communication: Possible but requires careful coordination

Technical Constraints

Headless mode: Extensions don't work in headless mode (headless: true)
Manifest V3: Some newer extensions may have additional restrictions
Security policies: Extensions with strict CSP may not function properly

Authentication Issues

Profile data: Extensions requiring login won't have saved credentials
OAuth flows: May not work properly in automated environments

Common Use Cases

Web Scraping with Ad Blockers

const adBlockerPath = '/path/to/adblocker-extension';

const browser = await puppeteer.launch({
    headless: false,
    args: [`--load-extension=${adBlockerPath}`]
});

const page = await browser.newPage();
await page.goto('https://example.com');
// Page loads with ads blocked

Testing Extension Functionality

async function testExtension() {
    const browser = await puppeteer.launch({
        headless: false,
        args: [`--load-extension=${extensionPath}`]
    });

    const page = await browser.newPage();

    // Test if extension content script loaded
    const extensionLoaded = await page.evaluate(() => {
        return window.myExtensionVariable !== undefined;
    });

    console.log('Extension loaded:', extensionLoaded);
    await browser.close();
}

Troubleshooting Tips

Use absolute paths: Always provide absolute paths to extension directories
Check Chrome version: Ensure extension compatibility with Puppeteer's Chrome version
Wait for loading: Add delays after browser launch to allow extensions to initialize
Check console logs: Monitor browser console for extension errors
Test manually first: Verify the extension works in regular Chrome before automating

Alternative Approaches

If you need headless operation with extension-like functionality: - Inject custom JavaScript that mimics extension behavior - Use proxy servers for request modification - Implement functionality directly in your Puppeteer script

Table of contents