vitest-browser-bun

A Vitest Browser Mode provider powered directly by Bun.WebView using the Chrome backend.

It runs Vitest browser tests in Chromium without Playwright, WebDriverIO, Puppeteer, or another browser-driver runtime dependency. The published package has zero regular runtime dependencies; vitest and @vitest/browser are peer dependencies.

0.0.4 targets Vitest 5.0.x and keeps a narrow peer range because Vitest's custom browser-provider API is experimental.

Why use it?

Vitest Browser Mode
        │
        ▼
 vitest-browser-bun
        │
        ├── Bun.WebView native browser operations
        └── Bun.WebView.cdp()
                 │
                 ▼
              Chromium

Vitest remains responsible for test discovery, Vite module serving, mocking, Browser UI, assertions, trace view, coverage integration, and locator semantics. This package implements the provider bridge from those APIs to Bun.WebView and Chrome DevTools Protocol.

Requirements

• Bun: >=1.3.12
• Vitest: >=5.0.0 <5.1.0
• @vitest/browser: matching 5.0.x
• Browser: a Chromium-family executable discoverable by Bun, or an explicit chromePath
• Runtime: the Vitest CLI must run under Bun

The provider accepts the Vitest browser names chromium and chrome. Both use the same Bun.WebView Chrome backend. Use chrome for Vitest V8 browser coverage because Vitest 5.0.1 validates that mode against the chrome browser name.

Install

bun add -D [email protected] @vitest/[email protected] vitest-browser-bun

Configure Vitest

import { defineConfig } from 'vitest/config'
import { bunWebView } from 'vitest-browser-bun'

export default defineConfig({
  test: {
    browser: {
      enabled: true,
      headless: true,
      provider: bunWebView(),
      instances: [{ browser: 'chromium' }],
    },
  },
})

Run Vitest under Bun:

bun run --bun vitest run

A package script is convenient:

{
  "scripts": {
    "test:browser": "bun run --bun vitest run"
  }
}

bun run vitest can respect Vitest's #!/usr/bin/env node shebang and start the CLI under Node. A Node process cannot construct Bun.WebView, so use bun run --bun. Do not substitute bun test; that invokes Bun's own test runner rather than Vitest.

Provider options

bunWebView({
  // Optional Chromium-family executable. Bun auto-detects when omitted.
  chromePath: '/path/to/chrome',

  // Extra flags appended to Bun's Chrome launch arguments.
  chromeArgs: ['--lang=en-US'],

  // Initial viewport overrides. Otherwise Vitest browser.viewport is used.
  width: 1280,
  height: 720,

  // Normally leave false because Vitest already handles test console output.
  forwardConsole: false,

  // Useful when diagnosing browser startup failures.
  stdout: 'ignore',
  stderr: 'ignore',

  // Optional construction/isolation boundary. The built-in direct factory is
  // serialized; a factory may enable file parallelism only by explicitly
  // declaring isolatedSessions === true and satisfying the isolation contract.
  webViewFactory: undefined,
})

The provider uses Bun's Chrome backend with url: false, so it starts its own browser instead of attaching to an unrelated remote-debugging instance.

Supported surface

The 0.0.4 conformance and regression suites cover:

• Vitest semantic locators and locator composition
• expect.element(...)
• custom locator extensions
• click, double-click, triple-click, buttons, modifiers and positions
• fill, clear, type, keyboard state, tab and cleanup
• hover, unhover and wheel
• selectOptions
• native HTML5 drag/drop and pointer-style drag fallback
• clipboard copy, cut and paste
• uploads from browser File objects and project-relative files
• same-origin frameLocator, including nested same-origin frames
• open Shadow DOM locators and native interactions
• actionability, scrolling, force and obscuring overlays
• page and locator screenshots
• screenshot assertions and failure screenshots
• viewport changes
• public cdp() send/event APIs
• browser mocking
• custom Browser Commands
• multiple Chromium instances
• Browser UI mode
• orchestrator scripts
• Vitest Trace View
• V8 and Istanbul browser coverage

The default direct Bun.WebView factory advertises supportsParallelism = false because Chrome-backed WebViews created in one Bun process share browser state. vitest-browser-bun supports Vitest browser-file parallelism when an injected factory explicitly guarantees isolated sessions. The reference implementation is [email protected], which uses one Bun helper/Chrome isolation boundary per active lease.

Supported process-isolated parallelism

Install the standalone isolation package alongside the provider:

bun add -D [email protected]

Then inject its factory:

import { defineConfig } from 'vitest/config'
import { createParallelWebViewFactory } from 'bun-webview-parallel'
import { bunWebView } from 'vitest-browser-bun'

export default defineConfig({
  test: {
    browser: {
      enabled: true,
      headless: true,
      provider: bunWebView({
        webViewFactory: createParallelWebViewFactory({ pool: true }),
      }),
      instances: [{ browser: 'chromium' }],
    },
    fileParallelism: true,
    maxWorkers: 4,
  },
})

The default provider path remains direct and serialized. vitest-browser-bun enables supportsParallelism only when the injected factory declares isolatedSessions === true; labels such as isolation: 'process' do not enable parallel scheduling by themselves. The provider does not import subprocess or IPC code itself.

bun-webview-parallel uses attached Bun helper processes as the isolation boundary. By default each created WebView owns a dedicated helper. [email protected] can optionally reuse released helpers with createParallelWebViewFactory({ pool: true }); context reset and pool lifecycle stay inside that package, so no locator/action/provider logic changes.

The supported claim is deliberately scoped: it covers the process-isolated configuration and the browser/session surfaces listed in the conformance capability manifest. It is not a claim that every possible Chromium or operating-system state surface is equivalent to a Playwright browser context. Custom factories may opt in with isolatedSessions: true, but they are responsible for meeting the same isolation contract.

See docs/PARALLELISM.md for the integration architecture.

The release conformance matrix includes synchronized four-session state/permission isolation, routing/CDP isolation, crash containment, sustained pooled-host churn, and a 16-file Vitest orchestration/artifact matrix. bun run test:capabilities audits the machine-readable proof map in docs/parallel-capabilities.json; run bun run test:parallel for the normal gate or bun run test:parallel:soak for repeated stress.

The orchestration matrix runs 16 real browser files with four workers against a pooled process-isolated factory. Every overlap sample must contain four distinct Vitest sessions and helper PIDs, while each file concurrently exercises a custom BrowserCommand, native interaction, CDP evaluation, trace-view marks, and a uniquely saved screenshot. A separate expected-failure matrix verifies that parallel screenshotFailures output produces distinct failure artifacts instead of colliding on shared paths.

Raw CDP

The provider augments Vitest's CDPSession and maps the public cdp() facade to the active Bun.WebView:

import { cdp } from 'vitest/browser'

const result = await cdp().send('Runtime.evaluate', {
  expression: 'document.title',
  returnByValue: true,
})

Supported session methods:

• send
• on
• off
• once

Provider commands and public CDP calls share a per-session operation queue so Bun.WebView operations do not race each other.

Custom Browser Commands

Vitest Browser Commands receive the standard command context plus Bun-specific handles:

import type { BrowserCommand } from 'vitest/node'

export const getTitle: BrowserCommand<[]> = async ({ bunWebView }) => {
  return bunWebView.evaluate<string>('document.title')
}

The context exposes:

• webview — the real Bun.WebView in direct mode, or the injected WebView proxy in isolated mode
• bunWebView — the provider session wrapper, which serializes operations

Prefer bunWebView when command ordering matters.

Compatibility notes

• Chromium engine only. chromium and chrome both select the Bun.WebView Chrome backend.
• Headless only for the current 0.0.x line.
• Vitest must run under Bun.
• Browser-file parallelism is supported with a verified isolated factory. [email protected] is the reference process-isolated implementation. The built-in direct Bun.WebView factory remains serialized.
• No Playwright .trace.zip. Vitest's provider-independent Trace View is supported; Playwright trace archives are provider-specific.
• Same-origin frame traversal is verified. Cross-origin frame behavior is not claimed.
• Open Shadow DOM is verified. Closed roots are not traversable through ordinary page JavaScript.
• V8 coverage uses the chrome alias in Vitest 5.0.1.

See docs/COMPATIBILITY.md for the detailed provider comparison.

Testing the provider itself

For contributors and maintainers:

bun run test:browser
bun run test:regression
bun run test:conformance

test:regression is the focused bug-regression runner. test:conformance is the full release gate.

See:

• docs/TESTING.md — test commands, local development, and failure triage
• docs/REGRESSIONS.md — regression catalog and the bugs each test protects against
• docs/CONFORMANCE.md — complete release gate
• docs/ARCHITECTURE.md — implementation architecture
• docs/MAINTENANCE.md — upgrade and compatibility workflow
• docs/RELEASE.md — publishing checklist
• docs/RELEASE-NOTES-0.0.4.md — changes and support boundary for the 0.0.4 stable release

Maintenance policy

When Vitest, Vite, Bun or Chromium changes:

1. keep the existing compatibility range until the candidate is tested;
2. reproduce any failure with the narrowest conformance group;
3. add or strengthen a regression when the provider is wrong;
4. make the smallest provider change needed;
5. run the focused regression runner;
6. run the complete conformance matrix;
7. only then widen compatibility or publish.

License

MIT