Utils

Methods

launchWithExtension

launchWithExtension() creates a persistent Chromium context and returns an Extension. Use it for custom shared fixtures or outside Playwright Test. It requires an unpacked Chromium Manifest V3 extension. A background service worker is optional.

Usage

import { launchWithExtension } from 'playwright-webext';

const extension = await launchWithExtension({
  extensionPath: './dist',
  launchOptions: { headless: true },
});

// ...interact with extension

await extension.close();

extension.close() closes the context and removes temporary extension copies. Setup failures close the context and clean up copies before the launch rejects.

Arguments

One options object, typed as LaunchWithExtensionOptions:

• extensionPath (string, required): unpacked build directory. Relative paths resolve against the current working directory. Absolute paths are used unchanged.
• extensionAutoInstall (boolean, optional): defaults to true. Set to false to install manually.
• launchOptions (LaunchOptions, optional): browser launch settings, including headless. The package uses the chromium channel and adds the flags needed to load extensions.
• contextOptions (BrowserContextOptions, optional): context settings. Explicit locale selects the extension's translation catalog; explicit storageState is restored before installation.

Omitted browser options retain Playwright's native defaults and inheritance. During Playwright tests, context settings can inherit the active test's configuration. See the shared-context guide for how this affects worker fixtures. The function does not provide the built-in fixture's per-test video retention or attachments. An inherited storageState is not automatically restored by persistent launch; pass it explicitly when needed.

Extension lifecycle waits use Playwright's context timeout settings. Playwright Test also limits fixture setup and test execution through its fixture and test timeouts. launchOptions.timeout controls browser startup.

Returns

Promise<Extension> — installed and ready when automatic installation is enabled, including a ready worker if one is declared. With extensionAutoInstall: false, the context is available immediately, but metadata and worker operations require await extension.install() first.

poll

Polls a synchronous or asynchronous callback until it returns a truthy value, then returns that value. Falsy values such as undefined, null, false, 0, and '' cause another attempt.

Usage

import { poll } from 'playwright-webext';

const result = await poll(() => doSomething());

To wait for a page by URL, use extension.pollForPage().

Arguments

• callback (() => T | Promise<T>) — Function called on each attempt. Asynchronous results are awaited. Return a truthy value to stop polling.
• options (object, optional) — Forwarded to Playwright's expect.poll:
  • timeout (number, optional) — Polling timeout in milliseconds. Defaults to the configured Playwright assertion timeout (5_000 ms unless changed). Set to 0 to disable the polling timeout; the test's own timeout still applies.
  • intervals (number[], optional) — Delays between attempts in milliseconds. Defaults to [100, 250, 500, 1_000]. After exhausting the array, polling repeats the last interval until the callback returns a truthy value or the timeout expires.

Returns

Promise<T> — Resolves to the first truthy callback result. Rejects if the timeout expires or the callback throws or rejects.