Extensions, WebView2, and components need three different harnesses

An extension check passes in a normal Chromium tab, then fails the moment the same team points it at WebView2. A component spec is copied into that project and cannot even find its mount fixture. All three use a Chromium engine somewhere, but they do not expose the same process, context, or lifecycle.

The fix is architectural before it is syntactic. Browser extensions need a persistent Chromium context launched with the extension. WebView2 needs an already running Windows application that exposes a CDP port. Component tests need a small render surface and the component API that matches the installed Playwright version. One generic "browser integration" fixture hides those differences and turns setup errors into misleading locator timeouts.

Name the browser boundary before choosing an API

A browser extension is code installed into a browser profile. Its background work may run in a Manifest V3 service worker, and its popup uses a chrome-extension:// URL. A test has to prove that the extension was loaded into the profile before it makes claims about content changes or popup behavior. Launching an ordinary ephemeral context does not satisfy that precondition.

A WebView2 control is different. Microsoft Edge WebView2 lives inside a Windows desktop process. Playwright does not create that host window through chromium.launch(). The application enables Chrome DevTools Protocol access, and Playwright attaches with chromium.connectOverCDP(). The web content appears as pages in the existing default context. Native title bars, menus, file pickers, and other desktop controls remain outside Playwright's web automation boundary.

A component harness is smaller than either of those. It renders a component scenario into a page controlled by a test server or component-testing package. There is no extension profile and no desktop shell to discover. The assertion should target the rendered component root, its state, and its browser-visible effects.

Those mechanisms produce different first checkpoints:

This table is not cosmetic. If context.serviceWorkers() is empty in an extension project, searching the page for a modified heading is premature. If browser.contexts() is empty after a WebView2 attachment, increasing a locator timeout cannot create the missing target. If mount is undefined in a component test, the product component has not failed; the runner and package are mismatched.

Version is part of this boundary. The repository in this example is pinned to Playwright 1.61.1. In that line, browser.bind() and the WebView2 APIs discussed here exist, while component testing still uses matching @playwright/experimental-ct-* packages. Playwright 1.62 introduces the stable story-gallery model and a built-in mount fixture from @playwright/test. Copying a 1.62 component snippet into a 1.61 project invents availability that the installed type definitions do not promise.

Before debugging any integration, capture the installed runner version and the surface-specific readiness signal. These commands are deliberately narrow. They answer whether the expected files and CDP endpoint exist; they do not claim the feature works.

npx playwright --version
test -f ./my-extension/manifest.json
curl --fail --silent http://127.0.0.1:9222/json/version

Run the manifest check on the machine that launches the extension. Run the HTTP check only after the WebView2 host has enabled remote debugging. A successful /json/version response proves CDP is listening, not that the correct control is initialized. That distinction becomes important when a desktop process contains more than one control or an old process still owns the port.

Prove the extension exists before testing its effect

The official extension guide sets three constraints that should shape the fixture. Extensions run in Chromium, they require a persistent context, and current Chrome and Edge releases no longer accept the command-line flags Playwright relies on for side-loading. Use the Chromium build bundled with Playwright, selected with the chromium channel in the documented fixture.

The profile directory is part of test data. Passing an empty string asks Playwright to create a temporary user data directory. Supplying a stable directory can preserve cookies, extension storage, permissions, and cached state between launches. That persistence is useful for a deliberate upgrade test and dangerous for independent tests. Two browser processes also cannot safely launch against the same user data directory. Default to one fresh profile per test or worker, then opt into reuse for a named scenario.

The following fixture loads one unpacked Manifest V3 extension. It waits for an existing service worker first because the worker may have started before the listener is registered. If none exists, it waits for the serviceworker event. The extension ID comes from the worker URL rather than a hard-coded development ID.

import path from 'node:path';
import { test as base, chromium, type BrowserContext } from '@playwright/test';

export const test = base.extend<{ extensionId: string }>({
  context: async ({}, use) => {
    const extensionPath = path.join(process.cwd(), 'my-extension');
    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()[0];
    if (!worker)
      worker = await context.waitForEvent('serviceworker');

    const workerUrl = new URL(worker.url());
    if (workerUrl.protocol !== 'chrome-extension:')
      throw new Error(`Unexpected extension worker URL: ${worker.url()}`);

    await use(workerUrl.host);
  },
});

export { expect } from '@playwright/test';

A test importing that fixture can now establish two independent facts. First, the expected extension runtime exists. Second, the popup or content effect behaves correctly. Testing only the second fact risks a false positive when the unmodified page already contains the expected text.

For a popup, navigate explicitly to chrome-extension://${extensionId}/popup.html and assert a control unique to the extension. For a content script, choose a fixture page whose original DOM is known, then assert a change the server would not produce on its own. Keep the server response or baseline markup available in the test so reviewers can see what would make the assertion fail.

Service-worker timing creates a common near-miss. Manifest V3 workers can be suspended while idle. Modern Playwright keeps its Worker object across the documented restart behavior, so waiting for a second serviceworker event after suspension is the wrong synchronization plan. Trigger the extension behavior through its real user-facing action and assert the resulting state. If an evaluation happens during a restart window, inspect that operation rather than registering an endless event wait.

Do not set serviceWorkers: 'block' in the extension project. That option is useful for ordinary web tests that want predictable routing, but an MV3 extension depends on its service worker. A shared base config can accidentally carry the setting into every project. Put extension launch options in their own fixture and review the resolved project configuration when no worker appears.

The cost of this fixture is startup time. A persistent browser context per test is heavier than Playwright Test's default isolated page fixture. Reusing one context per worker reduces launches but creates an extension-storage cleanup problem. If you choose reuse, clear the exact extension state your tests mutate and add a rejection test that seeds one identity, starts the next test, and proves that identity is absent. "The second test passed" is not a cleanup assertion.

Side-loading also has a coverage boundary. It validates extension behavior in Playwright's bundled Chromium. It does not validate Chrome Web Store installation, enterprise policy, update delivery, signing, or a user's existing profile. Keep a smaller packaging or managed-browser check for those risks instead of stretching the side-loaded fixture beyond what it controls.

Attach to the WebView2 process you actually started

The WebView2 guide describes the connection sequence precisely. The host application starts its control with a remote debugging port, either through WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS or the WebView2 initialization options. Playwright then calls chromium.connectOverCDP() and reads the existing default browser context.

This is an attachment, not a Playwright launch. Options normally passed to chromium.launch() cannot be assumed to reconfigure an already running WebView2 process. Browser channel, profile location, and remote-debugging arguments belong to the desktop process startup. Put them in the process fixture so the test and the app agree on ownership.

Parallel workers need two unique resources: a user data folder and a port. The official guide warns that WebView2 uses the same user data directory by default, which lets instances interfere. A worker that inherits another worker's login can make an isolation failure look like successful authentication. Assigning a directory per worker prevents that state from being shared through the profile.

The fixture below expects the application to print WebView2 initialized after its CoreWebView2InitializationCompleted event succeeds. That line is an application contract, not a Playwright API. Replace it with the real readiness message emitted by your host. The assertion on URL or title later still has to identify the intended page.

import { spawn, type ChildProcess } from 'node:child_process';
import { chromium, test as base, type Browser, type Page } from '@playwright/test';

const executable = process.env.WEBVIEW2_APP_PATH;

export const test = base.extend<{ webviewPage: Page }>({
  webviewPage: async ({}, use, testInfo) => {
    if (!executable)
      throw new Error('WEBVIEW2_APP_PATH must point to the Windows test application');

    const port = 10_000 + testInfo.parallelIndex;
    const userDataFolder = testInfo.outputPath('webview2-user-data');
    const app: ChildProcess = spawn(executable, [], {
      env: {
        ...process.env,
        WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS: `--remote-debugging-port=${port}`,
        WEBVIEW2_USER_DATA_FOLDER: userDataFolder,
      },
      stdio: ['ignore', 'pipe', 'pipe'],
    });
    const appExited = new Promise<void>(resolve => app.once('exit', () => resolve()));
    let browser: Browser | undefined;

    try {
      await new Promise<void>((resolve, reject) => {
        const timer = setTimeout(
          () => reject(new Error('WebView2 host did not report initialization')),
          30_000,
        );
        app.once('exit', code => {
          clearTimeout(timer);
          reject(new Error(`WebView2 host exited before initialization: ${code}`));
        });
        app.stdout?.on('data', chunk => {
          if (chunk.toString().includes('WebView2 initialized')) {
            clearTimeout(timer);
            resolve();
          }
        });
      });

      browser = await chromium.connectOverCDP(`http://127.0.0.1:${port}`);
      const context = browser.contexts()[0];
      const page = context?.pages().find(candidate => candidate.url().includes('/desktop-shell'));
      if (!page)
        throw new Error('CDP connected, but the expected WebView2 page was not found');

      await use(page);
    } finally {
      try {
        if (browser)
          await browser.close();
      } finally {
        if (app.exitCode === null) {
          app.kill();
          await appExited;
        }
      }
    }
  },
});

The code does not select pages()[0] blindly. A host may create a splash control, an authentication control, and the main application control. Page order is a weak identity. Match a known URL, then assert a unique application marker such as a heading and a host-provided build label. If URLs are all about:blank during startup, wait for the host's navigation rather than sleeping for an arbitrary duration.

There are two readiness failures that look alike from a locator. In the first, the CDP endpoint never opens because the environment variable was not inherited or the port was occupied. The HTTP diagnostic fails, and connectOverCDP() cannot attach. In the second, CDP attaches but the expected page is absent. browser.contexts() and context.pages() are the relevant evidence. The second problem belongs to WebView initialization, page identity, or application navigation, not networking to the debugging endpoint.

CDP is lower fidelity than Playwright's native protocol connection, as the BrowserType API notes. Use it here because WebView2 exposes CDP. Do not generalize that choice to a browser Playwright launched itself, where browserType.connect() or the normal test fixtures preserve the intended Playwright protocol behavior.

The isolation cost is disk and process startup. Every worker creates a WebView2 profile and desktop process. Cleanup must stop the process and let your artifact policy remove the output directory after useful logs are collected. Reusing a host can reduce startup but couples tests through browsing state, native window state, and application memory. Start with isolation; optimize only after a test proves the reset boundary.

Keep component rendering in its own versioned project

Component testing fails differently because its browser usually starts correctly. The missing piece is the render harness. A component is not found at an application route until a runner mounts it or a gallery serves it. Copying an end-to-end page.goto() fixture into component specs can test a deployed page, but it does not provide the component isolation the suite claims.

For Playwright 1.61, supported React and Vue projects use the corresponding experimental component package at the same version as Playwright Test. The package supplies the mount fixture and component-aware configuration. The following 1.61 React example is a real component test, not an end-to-end substitute.

import { test, expect } from '@playwright/experimental-ct-react';
import { SaveButton } from './SaveButton';

test('moves from ready to saved after activation', async ({ mount }) => {
  const component = await mount(<SaveButton documentId="qa-42" />);

  const button = component.getByRole('button', { name: 'Save document' });
  await button.click();

  await expect(component.getByRole('status')).toHaveText('Saved');
  await expect(button).toBeEnabled();
});

This assertion can fail if the component never changes its status or remains disabled. It does not merely assert that mount() returned. The component root scopes locators so a similarly named button in the harness cannot satisfy the test.

Playwright 1.62 changes the model. Components move to stories rendered by a gallery that the application team owns, and plain @playwright/test provides the built-in mount fixture. That upgrade removes the framework-specific runtime from the test API, but it is a migration rather than a drop-in import edit. Story IDs, gallery setup, callbacks, and config all change. Use the component testing documentation that matches the target version and keep the old project running until migrated specs pass under the new gallery.

Component tests should not inherit the extension fixture. A persistent context with side-loading flags adds browser state the component does not need. They should not attach to WebView2 either, unless the product requirement specifically concerns how a component behaves inside that host and the test is honestly classified as an integration test. Ordinary component behavior is cheaper and clearer in the component runner.

The near-miss here is a successful mount of the wrong scenario. A broad assertion such as "Save" being visible can pass against the gallery navigation or another component. Scope from the returned component locator and assert a state transition caused by the test action. When a render fails, inspect the component runner's browser console and build output. When mount is unavailable at collection time, inspect package versions and imports before touching component code.

Component isolation also costs fidelity. A mounted component may use fake providers, fixed props, and intercepted network responses. That is ideal for rendering states and interaction logic. It does not prove routing, authentication cookies, server rendering, or integration with the real backend. Preserve a smaller end-to-end journey for those contracts.

Read the first missing artifact, not the final timeout

These integrations often end with the same message shape: a locator was not found before its timeout. The last error is rarely the best classification. Work backward to the first surface-specific artifact.

For an extension, record the persistent context launch options, the resolved extension directory, the service-worker URLs, and the popup URL. If the worker list is empty, the test has not reached extension behavior. Check manifest.json, the Chromium channel, side-loading arguments, and any inherited service-worker setting. If the worker exists but the content page is unchanged, inspect the extension's own worker console and permissions rather than declaring a page locator flaky.

For WebView2, record process stdout and stderr, the chosen port, the CDP version response, context count, and page URLs. A connection refusal points to process startup or the debugging port. A connection with no matching page points to control initialization or page discovery. A matching page with a failing assertion finally reaches web application behavior. That ordered evidence keeps desktop, protocol, and product failures separate.

For components, retain the installed component package version, runner config, build output, browser console, and mounted scenario identity. A TypeScript error importing mount is collection or version wiring. A Vite or application-bundler error is harness compilation. A visible component with the wrong accessible state is a product assertion. Increasing a common timeout treats three different causes as one.

State leakage has different evidence too. In an extension suite, read extension storage and cookies from the persistent context at the start of the next test. In WebView2, compare the assigned user data folder and the authenticated UI marker for each worker. In component tests, mount a clean story and assert its initial state before interaction. Do not use process completion as proof of cleanup.

A normal Chromium test can imitate all three at a superficial level. It can visit a page modified by server-side code that looks like an extension effect. It can open the same URL shown inside a desktop shell. It can render a route containing a component. What it cannot prove is that the extension runtime, WebView2 host, or isolated component harness produced the result. The integration boundary is part of the oracle.

Split rollout, CI, and ownership by surface

Create three Playwright projects or three focused configurations. Give extension tests their persistent-context fixture and bundled Chromium requirement. Restrict WebView2 tests to Windows agents that have the desktop application artifact. Keep component tests with their version-matched package or gallery server. Separate output directories and project names make reports useful before any custom diagnostics are added.

Move one representative test per surface first. The extension test should fail when the extension path is wrong. The WebView2 test should fail when the host does not enable CDP and should produce a different error when the target page is missing. The component test should fail when its action does not produce the expected state. Those controlled failures prove the harness detects the boundary it claims to cover.

Do not run every surface on every pull request by habit. Component tests are usually suitable for broad, fast coverage. Extension tests may run on Chromium-capable agents for extension changes and a scheduled regression. WebView2 requires Windows and a packaged host, so teams often place it behind path rules plus a release job. The exact schedule depends on product risk, but the release rule must remain visible.

Provisioning failures need their own labels. An extension job must install the Chromium revision that belongs to the locked Playwright package; a missing executable is not an extension regression. A WebView2 job must verify the application artifact and Edge WebView2 runtime before starting the test runner. A component job must install the component package at the same Playwright version and start the expected build pipeline. Put those checks in named CI steps so a red setup step does not arrive as a generic test failure.

Keep the WebView2 debugging endpoint on loopback unless remote access is an intentional, protected design. CDP gives its client extensive control over the attached web content. Publishing the port broadly to solve an agent-routing problem expands the test's attack surface and makes it easier to attach to the wrong host. If the runner and desktop process live on separate machines, use an authenticated tunnel or an isolated network owned by the CI platform, and still identify the page after connection. A reachable port is not an identity check.

Treat fixture teardown as reportable work. Extension context closure flushes artifacts owned by that context. A WebView2 fixture must disconnect Playwright, terminate the host, and preserve process logs when the assertion fails. Component servers may be worker-scoped, so their final output can explain failures from several tests. If cleanup itself fails, report that error alongside the product assertion instead of replacing the first failure with an unqualified process timeout.

During a component migration, keep old and new test files in explicitly named projects. Do not let both projects discover the same spec through broad testMatch patterns, because duplicate execution can look like increased coverage. Port one scenario, remove it from the old project's discovery, and compare the browser-visible assertion. When the last spec moves, remove the experimental package and its dedicated config together. A half-migrated import graph is harder to diagnose than either complete model.

Ownership should follow the process. The browser automation team can own Playwright fixtures. The extension team owns the manifest and permission model. The desktop team owns WebView2 startup, readiness output, and native cleanup. Component owners maintain stories or mountable states. A single QA helper cannot repair a host that never opens CDP or a component bundle that does not compile.

Do not use the extension harness to certify marketplace installation or managed policies. Do not use the WebView2 fixture to claim coverage of native menus and operating-system dialogs. Do not use component tests as proof that routing, authentication, and deployed assets work together. Add the adjacent tool or end-to-end layer required by each uncovered boundary.

The trade-off of splitting is duplicated configuration and more CI labels. That is cheaper than a universal fixture full of conditionals for channel, platform, profile, protocol, and mount behavior. Explicit projects let an engineer see which process failed, which evidence should exist, and which team can act on it. For these three surfaces, that clarity is the difference between debugging an integration and waiting longer for a locator that never had a valid target.