Preload a Chrome Extension for Browser Testing

Preloading a Chrome extension means loading it into a fresh Chrome profile before you open your test suite, so every test run starts with the extension already installed and active. This saves you from manually installing it each time, makes your tests deterministic, and lets you simulate a real user who has the extension enabled. Before you start, you need the extension’s unpacked source folder (the one containing its manifest.json) and a copy of Chrome or Chromium on your machine.

What You’ll Need

The unpacked extension folder (with manifest.json at its root).
Chrome or Chromium installed.
Optional: a test runner like Selenium, Puppeteer, or Playwright if you want automated preloading.

Step-by-Step

Locate your extension’s source folder. If it’s packed as a .crx file, extract it with a tool like 7-Zip or use the --pack-extension flag to get the unpacked version. The folder must contain the manifest.json file.
Create a dedicated Chrome user data directory. Use a fresh folder, e.g., ~/chrome-test-profile. This isolates your test profile from your personal one and avoids interference. On Windows, it could be C:\chrome-test-profile.
Launch Chrome with the extension preloaded. Use the command line:
chrome --user-data-dir=/path/to/profile --disable-extensions-except=/path/to/extension --load-extension=/path/to/extension
On Windows, replace chrome with the full path to chrome.exe. On macOS, use open -a "Google Chrome" --args .... The --disable-extensions-except flag ensures only your extension loads, and --load-extension forces it to load.
Verify the extension loads. Open chrome://extensions in that profile and confirm your extension appears and is enabled. If it doesn’t, check the console for errors (right-click the extension card and select “Inspect views: background page”).

For automated testing (Selenium): In your test script, set ChromeOptions to use the same profile:

ChromeOptions options = new ChromeOptions();
options.addArguments("--user-data-dir=/path/to/profile");
options.addArguments("--disable-extensions-except=/path/to/extension");
options.addArguments("--load-extension=/path/to/extension");
WebDriver driver = new ChromeDriver(options);

For Puppeteer/Playwright: Pass the same arguments in the launch method:

const browser = await puppeteer.launch({
  headless: false,
  args: [
    `--disable-extensions-except=${path}`,
    `--load-extension=${path}`,
    `--user-data-dir=${profileDir}`
  ]
});

Note: In headless mode, extensions may not load; use headful mode for extension testing.

Run your tests. The extension should be active on every page load. If your extension injects content scripts, they’ll run automatically. If you need to interact with the extension’s popup or background page, you can access them via chrome-extension://[extension-id]/popup.html or use the Chrome DevTools Protocol.

Common Mistakes

Using the same profile as your personal Chrome. This can cause conflicts with existing extensions and settings. Always use a fresh, dedicated profile.
Forgetting the --disable-extensions-except flag. Without it, Chrome may load all extensions from the profile, which could interfere with your test.
Pointing to the wrong path. The path must be absolute, and on Windows, use forward slashes or escaped backslashes.
Testing in headless mode. Chrome’s headless mode (old headless) doesn’t support extensions. Use headful mode or the new headless (--headless=new) which does support extensions in recent versions.
Not clearing the profile between runs. If your extension stores state, it may persist between tests. Delete the profile folder before each run to start fresh.

Tips

Use a clean profile for each test run. Create a new profile directory programmatically before launching Chrome, or delete the old one. This ensures no leftover state.
Enable logging. Add --enable-logging=stderr --v=1 to see extension errors in the console.
Use a relative path in your test code. Store the extension path in a config file or environment variable so it’s easy to change.
If your extension has a service worker (Manifest V3), you can test it by navigating to chrome://extensions and clicking the service worker link to open its DevTools.
For CI/CD pipelines, use a Docker image with Chrome and preload the extension as part of the image build.

Troubleshooting

Extension doesn’t appear in the toolbar. Check if the extension has a popup or action; it may be hidden behind the puzzle icon. Also, verify the manifest has "action" or "browser_action".
Extension loads but doesn’t work. Open the background page’s console (via chrome://extensions → “Inspect views”) and look for errors. Also, check that your content scripts match the URLs you’re testing.
Chrome refuses to load the extension. Make sure the manifest is valid (no syntax errors) and that the extension folder is not corrupted. Try loading it manually via chrome://extensions with developer mode on.
Tests fail because the extension isn’t ready. Add a wait in your test for the extension’s background page to be ready, e.g., poll for a global variable or use a test hook in your extension.
Profile lock errors. If Chrome is already running with that profile, close it or use a different profile path. Chrome locks the profile directory.

Frequently Asked Questions

Can I preload a packed .crx extension instead of an unpacked folder?

Yes, but it’s less reliable. You can use --load-extension with a .crx file, but Chrome may block it if it’s not from the Web Store. It’s safer to unpack it first.

Does this work with Manifest V3 extensions?

Yes, the same command-line flags work with MV3 extensions. Just ensure your service worker is registered correctly.

Will the extension persist across browser restarts?

Yes, if you use the same profile directory, the extension remains installed. However, for testing, it’s best to start fresh each time.

Can I preload multiple extensions at once?

Yes, use --load-extension=path1,path2 (comma-separated) or repeat the flag. Also list them in --disable-extensions-except to allow them all.

How do I test the extension’s popup UI?

You can open the popup by navigating to chrome-extension://[extension-id]/popup.html in the same profile. In Selenium, you can switch to that window or use the Chrome DevTools Protocol to click the toolbar icon.

What if my extension requires a specific URL pattern to activate?

Make sure your test navigates to a URL that matches the content script’s matches patterns. You can also use --unsafely-treat-insecure-origin-as-secure if you’re testing on HTTP.

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →