The browser configuration must have a "name" property when using preview() with empty/omitted browser.instances

[irfanandriansyah1997]

Describe the bug

Running Vitest 4.1.10 with @vitest/browser-preview and browser.enabled: true crashes at startup (before any test runs) when browser.instances is an empty array or omitted.

Error: The browser configuration must have a "name" property. This is a bug in Vitest. Please, open a new issue with reproduction

Expected: Vitest should either:

1. Default the preview provider to a named Chromium instance (the comment in resolveConfig already intends this), or
2. Throw a user-facing config error asking for browser.instances: [{ browser: 'chromium' }].

Actual: Vitest injects { browser: 'chromium' } for the preview provider, then resolveBrowserProjects throws an internal "this is a bug" error because that injected instance has no name.

Root cause

In packages/vitest/src/node/config/resolveConfig.ts (4.1.10), when browser mode is enabled:

if (!browser.instances) browser.instances = []
if (!browser.instances.length && browser.provider?.name === 'preview') {
  browser.instances = [{ browser: 'chromium' }]
}

Instance names are assigned earlier in the Vite config / configResolved hooks:

instance.name ??= originalName ? `${originalName} (${instance.browser})` : instance.browser

That assignment runs before the default Chromium instance is injected, so the injected instance stays unnamed. resolveBrowserProjects then does:

if (name == null) throw new Error(`The browser configuration must have a "name" property. This is a bug in Vitest. ...`)

On main (v5), names appear to be assigned after the preview default is injected:

browser.instances.forEach((instance) => {
  instance.name ??= resolved.name
    ? `${resolved.name} (${instance.browser})`
    : instance.browser
})

This still fails on the latest stable (4.1.10).

Workaround

Explicitly set at least one instance:

instances: [{ browser: 'chromium' }]

Reproduction

https://github.com/irfanandriansyah1997/vitest-preview-empty-instances-name-bug

npm install
npx vitest run

Minimal config:

import { preview } from '@vitest/browser-preview'
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    browser: {
      enabled: true,
      instances: [], // also fails if this key is omitted
      provider: preview(),
    },
  },
})

System Info

System:
  OS: macOS 15.6
  CPU: (8) arm64 Apple M1 Pro
  Memory: 81.58 MB / 16.00 GB
  Shell: 5.9 - /bin/zsh
Binaries:
  Node: 20.19.0 - ~/.nvm/versions/node/v20.19.0/bin/node
  npm: 10.8.2 - ~/.nvm/versions/node/v20.19.0/bin/npm
  pnpm: 10.11.0 - ~/.nvm/versions/node/v20.19.0/bin/pnpm
Browsers:
  Chrome: 151.0.7922.137
  Safari: 18.6
npmPackages:
  @vitest/browser-preview: 4.1.10 => 4.1.10
  vitest: 4.1.10 => 4.1.10

Used Package Manager

npm

Validations

• Follow our Code of Conduct
• Read the Contributing Guidelines
• Read the docs
• Check that there isn't already an issue that reports the same bug
• Check that this is a concrete bug
• The provided reproduction is a minimal reproducible example of the bug