vitest-environment-web-ext

A Vitest environment for end-to-end testing browser extensions with Playwright.

Document

Features

• E2E testing for Chrome extensions
• Supports MV3 manifest versions
• TypeScript ready

Installation

pnpm add -D vitest-environment-web-ext

Quick Start

vitest.config.ts

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    environment: 'web-ext',
  },
})

tsconfig.json

{
  "compilerOptions": {
    "types": [
      "vitest-environment-web-ext/types"
    ]
  }
}

Options

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    environment: 'web-ext',
    environmentOptions: {
      'web-ext': {
        path: './dist',
        compiler: false,
        autoLaunch: true,
        extensionId: '',
        detectExtensionId: true,
        detectTimeout: 15_000,
        targetUrl: 'https://www.example.com',
        playwright: {
          slowMo: 100,
          headless: false,
          userDataDir: false,
          devtools: false,
        },
      },
    },
  },
})

| Option | Default | Description | | --- | --- | --- | | path | – (required) | Directory containing the extension manifest | | compiler | false | Shell command executed before tests run. Runs once per worker process (Vitest instantiates the environment for every test file; repeated runs in the same process are skipped). For a single build per run, prefer building in a globalSetup or a pretest script | | autoLaunch | true | Load and launch the browser + extension during environment setup | | extensionId | – | Explicit extension id; skips detection entirely when set. Useful for offline environments or extensions without a service worker (e.g. Manifest V2) | | detectExtensionId | true | Detect the extension id by opening a tab at targetUrl. Disable for offline/air-gapped environments, when getPopupPage() / getSidePanelPage() are not used, or when extensionId is set | | detectTimeout | 15000 | Max time in ms spent detecting the extension id | | targetUrl | 'https://www.example.com' | URL opened while detecting the id; the tab is closed automatically | | playwright.slowMo | 100 | Slow down Playwright operations (ms) | | playwright.headless | false | Run without a visible window. The default headless shell cannot load extensions, so this keeps the full Chromium binary via Playwright's chromium channel (Playwright >= 1.49). | | playwright.userDataDir | false | Browser profile directory; true uses a per-test-file profile under path.join(process.cwd(), '.vitest-web-ext-cache') so parallel test files never share a Chromium profile; false gives every launch a fresh temporary profile | | playwright.devtools | false | Auto-open DevTools for tabs |