{"record":{"id":"beb68d82f031baa5","repo":"vitest-dev/vitest","slug":"you-ve-enabled-headless-mode-for-preview-provide","errorCode":null,"errorMessage":"You've enabled headless mode for \"preview\" provider but it doesn't support it. Use \"playwright\" or \"webdriverio\" instead: https://vitest.dev/guide/browser/#configuration","messagePattern":"You've enabled headless mode for \"preview\" provider but it doesn't support it\\. Use \"playwright\" or \"webdriverio\" instead: https://vitest\\.dev/guide/browser/#configuration","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/browser-preview/src/preview.ts","lineNumber":32,"sourceCode":"}\n\nexport class PreviewBrowserProvider implements BrowserProvider {\n  public name = 'preview' as const\n  public supportsParallelism: boolean = false\n  private project!: TestProject\n  private open = false\n\n  public distRoot: string = distRoot\n\n  public initScripts: string[] = [\n    resolve(distRoot, 'locators.js'),\n  ]\n\n  constructor(project: TestProject) {\n    this.project = project\n    this.open = false\n    if (project.config.browser.headless) {\n      throw new Error(\n        'You\\'ve enabled headless mode for \"preview\" provider but it doesn\\'t support it. Use \"playwright\" or \"webdriverio\" instead: https://vitest.dev/guide/browser/#configuration',\n      )\n    }\n  }\n\n  isOpen(): boolean {\n    return this.open\n  }\n\n  getCommandsContext() {\n    return {}\n  }\n\n  async openPage(_sessionId: string, url: string): Promise<void> {\n    this.open = true\n    this.project.vitest.logger.log(`Browser runner started at ${url}\\n`)\n    if (!this.project.browser) {\n      throw new Error('Browser is not initialized')","sourceCodeStart":14,"sourceCodeEnd":50,"githubUrl":"https://github.com/vitest-dev/vitest/blob/1fa9837ec26533512fdcad8baebf249771bd340a/packages/browser-preview/src/preview.ts#L14-L50","documentation":"The preview provider opens a real headed browser window for manual debugging; it does not implement headless execution. Its constructor checks `project.config.browser.headless` and throws immediately if headless is enabled, pointing you to playwright or webdriverio which do support headless. This fails at provider construction (startup), before any test runs.","triggerScenarios":"Configuring `browser: { provider: 'preview', headless: true }` (or setting `--headless` with preview). Common when copy-pasting a playwright config and only changing the provider name.","commonSituations":"CI environments where headless is the default; switching from playwright to preview without dropping the headless flag; sharing a config object across providers.","solutions":["Remove `headless: true` when using the preview provider (it is headed only).","Switch provider to 'playwright' or 'webdriverio' if you need headless runs.","Keep separate config presets for local (preview) vs CI (playwright headless)."],"exampleFix":"// before\nexport default defineConfig({\n  test: { browser: { provider: 'preview', headless: true } },\n})\n\n// after - option A: keep preview, drop headless\nexport default defineConfig({ test: { browser: { provider: 'preview' } } })\n// after - option B: stay headless, switch provider\nexport default defineConfig({ test: { browser: { provider: 'playwright', headless: true } } })","handlingStrategy":"validation","validationCode":"const provider = process.env.CI ? 'playwright' : 'preview'\nconst headless = !!process.env.CI\n\nexport default defineConfig({\n  test: {\n    browser: {\n      provider,\n      // preview does not support headless; only set it for playwright\n      ...(provider === 'playwright' ? { headless } : {}),\n    },\n  },\n})","typeGuard":"function supportsHeadless(provider: string): boolean {\n  return provider === 'playwright' || provider === 'webdriverio'\n}","tryCatchPattern":null,"preventionTips":["Remember preview is headed-only; never combine it with headless: true.","Use environment-driven config presets to switch provider/headless together.","Document the constraint in the repo's testing readme."],"tags":["browser","config","provider","preview","headless"],"backgroundTag":null,"analyzedSha":"1fa9837ec26533512fdcad8baebf249771bd340a","analyzedAt":"2026-08-11T16:11:39.638Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}