Vitest Browser Mode - "Cannot find provider" / Browser Not Launching

By Daniel Zoghalchali·Latchkey

Vitest browser mode runs tests in a real browser via a provider (Playwright or WebdriverIO). In CI it fails when the provider package or browser binaries are missing, or when it tries to launch headed on a runner with no display.

What this error means

A vitest --browser run aborts with "Cannot find provider" or a browser launch error. The same tests pass in jsdom/node mode; only browser mode fails, because the headless browser stack is not fully installed.

Error: Cannot find provider "playwright". Please install it:
  npm i -D @vitest/browser playwright

# or, on a headless runner:
Error: Failed to launch chromium: Missing X server or $DISPLAY

Common causes

Provider or browser binaries not installed

Browser mode needs @vitest/browser plus a provider (playwright/webdriverio) and the actual browser binaries. CI that only installs deps without playwright install has no browser to launch.

Headed launch on a display-less runner

Without headless: true, the browser tries to open a window. A CI runner has no $DISPLAY, so the launch fails.

How to fix it

Install the provider and browsers, run headless

npm i -D @vitest/browser playwright
npx playwright install --with-deps chromium

Configure browser mode for CI

// vitest.config.ts
import { defineConfig } from 'vitest/config';
export default defineConfig({
  test: {
    browser: {
      enabled: true,
      provider: 'playwright',
      headless: true,
      instances: [{ browser: 'chromium' }],
    },
  },
});

How to prevent it

• Install the browser provider and run playwright install in CI.
• Force headless: true for CI runs.
• Cache the browser binaries between runs to speed up CI.

Frequently asked questions

Related guides

References

• GitHub Actions documentation