Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 36 ยท Testing and Debugging

End-to-End Testing in a Real Browser

Run end-to-end tests that load your unpacked extension in Chromium with Playwright or Puppeteer, find the extension id, open the popup, test content scripts on a local page, and run them in CI.

Unit tests prove your logic. End-to-end (E2E) tests prove that the extension works as a whole in a real browser: the manifest parses, the service worker starts, the content script runs on the right page and the popup talks to the worker. You only need a handful of them, but they catch the failures that fakes cannot.

The code in this lesson needs Node and a real Chromium, which cannot run inside the lesson's sandbox. It is shown as read-only snippets, and the interactive example is a stand-in for the test flow.

Loading the extension into Chromium

Chrome has command-line flags to load an unpacked extension:

Text
--disable-extensions-except=/path/to/extension
--load-extension=/path/to/extension

Extensions only work in a persistent browser context, and traditionally in headed mode (a visible window). Recent Chromium builds also support the new headless mode (--headless=new), which loads extensions too. Use Playwright's bundled Chromium or Chrome for Testing; branded Chrome stable has restricted --load-extension in recent versions, so prefer these.

A Playwright test

JavaScript
// tests/extension.spec.js (read-only: needs Node and Playwright)
import { test as base, expect, chromium } from "@playwright/test";
import path from "node:path";

const extensionPath = path.resolve("dist");

const test = base.extend({
  context: async ({}, use) => {
    const context = await chromium.launchPersistentContext("", {
      channel: "chromium",
      args: [
        `--disable-extensions-except=${extensionPath}`,
        `--load-extension=${extensionPath}`
      ]
    });
    await use(context);
    await context.close();
  },
  extensionId: async ({ context }, use) => {
    let [worker] = context.serviceWorkers();
    if (!worker) worker = await context.waitForEvent("serviceworker");
    await use(worker.url().split("/")[2]);   // chrome-extension://<id>/...
  }
});

test("popup shows the saved count", async ({ context, extensionId }) => {
  const page = await context.newPage();
  await page.goto(`chrome-extension://${extensionId}/popup.html`);
  await expect(page.locator("#count")).toHaveText("0");
});

Key ideas:

  • launchPersistentContext with an empty path creates a throwaway profile.
  • The extension id is found from the service worker's URL, so tests never hard-code it. (You can also set a key in the manifest to get a fixed id.)
  • The popup can be opened as a normal page at chrome-extension://<id>/popup.html. You cannot click the toolbar icon in automation, but this tests the popup's own logic.

Testing a content script

Serve a small local page and let the extension run on it. The page can be a static file or a tiny server started by the test.

JavaScript
test("content script highlights prices", async ({ context }) => {
  const page = await context.newPage();
  await page.goto("http://localhost:4173/shop.html");   // matches in the manifest
  const marked = page.locator("mark.price");
  await expect(marked).toHaveCount(3);
});

Use file:// pages only when the extension has "Allow access to file URLs" enabled (not the default), so a local HTTP server is more reliable. Remember the manifest matches must include the test host, for example http://localhost/*; many teams add it only to a test build.

Testing the worker and storage

You can evaluate code inside the service worker or open an extension page and call APIs from it:

JavaScript
test("badge text updates after a message", async ({ context, extensionId }) => {
  const [worker] = context.serviceWorkers();
  await worker.evaluate(() => chrome.storage.local.set({ count: 5 }));
  const stored = await worker.evaluate(() => chrome.storage.local.get("count"));
  expect(stored.count).toBe(5);
});

Keep each test independent by starting from a fresh profile (the factory above does) or by clearing storage in a beforeEach.

A stand-in for the E2E flow

Running E2E in CI

On a CI server (GitHub Actions, GitLab CI), install Playwright's browsers, build the extension, then run the tests. On Linux, headed Chromium needs a virtual display, so wrap the command with xvfb-run, or use Chromium's new headless mode:

YAML
# .github/workflows/e2e.yml (read-only example)
jobs:
  e2e:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npm run build
      - run: xvfb-run npx playwright test

Keep the E2E suite short (a smoke test per feature) so it runs in a minute or two. Pair it with unit tests from the previous lesson, and run a manual pass of the install, update and permission flow before a release.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How does an E2E test usually find the extension id?

    The worker URL is chrome-extension://<id>/..., so the test can read the id from it.
  2. 2. Why use launchPersistentContext?

    Chromium only loads extensions in a persistent context with the load-extension flags.
  3. 3. How can a test check the popup without clicking the toolbar icon?

    The popup is a normal HTML page of the extension and can be opened in a tab.
  4. 4. What should the E2E suite focus on?

    Real-browser tests are slow. Keep them for integration paths and leave details to unit tests.

Summary

  • Load the unpacked extension with --load-extension in a persistent Chromium context.
  • Get the id from the service worker URL; open popup.html as a page.
  • Test content scripts on a local page whose URL matches the manifest.
  • Run a short smoke suite in CI with a virtual display or new headless mode.

Next: Preparing for the Chrome Web Store