[Bug]: vitest browser instances configuration fails in certain project environments with "project name already defined" error

[MH4GF]

Describe the bug

When using instances: [{ browser: 'chromium' }] with Vitest 3 + @storybook/addon-vitest, the following error occurs in certain project environments:

⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯ Startup Error ⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯
Error: Cannot define a nested project for a chromium browser. The project name "storybook (chromium)" was already defined. If you have multiple instances for the same browser, make sure to define a custom "name". All projects should have unique names. Make sure your configuration is correct.
    at file:///my-org/my-repo/node_modules/vitest/dist/chunks/cli-api.BkDphVBG.js:7550:31
    at Array.forEach (<anonymous>)
    at file:///my-org/my-repo/node_modules/vitest/dist/chunks/cli-api.BkDphVBG.js:7541:21
    at Array.forEach (<anonymous>)
    at resolveBrowserProjects (file:///my-org/my-repo/node_modules/vitest/dist/chunks/cli-api.BkDphVBG.js:7512:19)
    at resolveProjects (file:///my-org/my-repo/node_modules/vitest/dist/chunks/cli-api.BkDphVBG.js:7508:9)
    at async Vitest._setServer (file:///my-org/my-repo/node_modules/vitest/dist/chunks/cli-api.BkDphVBG.js:9319:20)
    at async handler (file:///my-org/my-repo/node_modules/vitest/dist/chunks/cli-api.BkDphVBG.js:10169:6)
    at async _createServer (file:///my-org/my-repo/node_modules/vite/dist/node/chunks/dep-Cyk9bIUq.js:63069:20)
    at async createViteServer (file:///my-org/my-repo/node_modules/vitest/dist/chunks/cli-api.BkDphVBG.js:6911:17)

However, the same configuration works perfectly in a fresh reproduction environment.

Reproduction link

https://github.com/MH4GF/storybook-vitest-reproduction

Reproduction steps

No response

System

Storybook Environment Info:

  System:
    OS: macOS 14.6
    CPU: (8) arm64 Apple M2
    Shell: 5.9 - /bin/zsh
  Binaries:
    Node: 22.14.0 - ~/.local/share/mise/installs/node/22.14.0/bin/node
    Yarn: 1.22.19 - /opt/homebrew/bin/yarn
    npm: 10.9.2 - ~/.local/share/mise/installs/node/22.14.0/bin/npm <----- active
    pnpm: 10.14.0 - /opt/homebrew/bin/pnpm
  Browsers:
    Chrome: 139.0.7258.157
    Safari: 17.6

Additional context

Current workaround:
Using the deprecated name: 'chromium' instead of instances: [{ browser: 'chromium' }] works but I want to use instances because of problems with vitest-dev/vitest#7981 (reply in thread).

Investigated factors:

• ✅ Package versions: Identical between failing and working environments
• ✅ Vitest configuration: Same configuration works in reproduction
• ✅ Story files: Removing all stories doesn't resolve the issue
• ✅ Storybook configuration: Configuration changes don't affect the error

Configuration that fails:

// vitest.config.mts
import react from '@vitejs/plugin-react';
import { resolve } from 'path';
import tsconfigPaths from 'vite-tsconfig-paths';
import { defineConfig } from 'vitest/config';
import { storybookTest } from '@storybook/addon-vitest/vitest-plugin';

export default defineConfig({
  plugins: [tsconfigPaths(), react()],
  resolve: {
    alias: {
      '@': resolve(__dirname, './'),
    },
  },
  optimizeDeps: {
    include: ['@storybook/addon-vitest', '@storybook/nextjs-vite'],
    exclude: ['markdown-to-jsx'],
  },
  test: {
    coverage: {
      provider: 'v8',
      reporter: ['text', 'json', 'html'],
      exclude: [
        '**/node_modules/**',
        '**/dist/**',
        '**/.storybook/**',
        '**/coverage/**',
        '**/*.stories.{ts,tsx}',
        '**/*.test.{ts,tsx}',
        '**/*.spec.{ts,tsx}',
      ],
    },
    projects: [
      // Regular unit tests
      {
        plugins: [tsconfigPaths(), react()],
        test: {
          name: 'unit',
          globals: true,
          environment: 'jsdom',
          setupFiles: ['./vitest.setup.mts'],
          include: ['**/*.{test,spec}.{ts,tsx}'],
          exclude: ['**/*.stories.{ts,tsx}', '**/node_modules/**', '**/mock-assets/**'],
          typecheck: {
            enabled: true,
          },
        },
      },
      // Storybook tests
      {
        plugins: [
          tsconfigPaths(),
          react(),
          storybookTest({
            configDir: resolve(__dirname, '.storybook'),
          }),
        ],
        define: {
          global: 'globalThis',
        },
        test: {
          name: 'storybook',
          browser: {
            enabled: true,
            provider: 'playwright',
            headless: true,
            // name: 'chromium',
            instances: [{ browser: 'chromium' }],
          },
          testTimeout: 60000,
          setupFiles: ['./.storybook/vitest.setup.ts'],
          exclude: ['**/node_modules/**'],
        },
      },
    ],
  },
});

Questions for the community:

1. What debugging steps can help identify project-specific factors causing this issue?
2. How can I inspect the internal project names that storybookTest plugin creates?
3. Are there known project environment factors that could cause different behavior with the same configuration?

The reproduction repository demonstrates that the configuration itself is correct, but something in the original project environment causes the conflict. Any guidance on debugging this project-specific issue would be greatly appreciated.

Related issues

• [Bug]: Addon-Test: Vitest 3 - Error: Cannot define a nested project for a chromium browser. #30363

[dosubot]

Here are some targeted steps and insights for debugging your Vitest project name conflict with Storybook and browser instances:

1. Debugging project-specific factors:
This error usually means Vitest detects duplicate project names for browser instances. Since your config works in a fresh repo, something in your original environment is causing the conflict. Try:

• Deleting node_modules and lockfiles (package-lock.json, yarn.lock, etc.), then reinstalling dependencies.
• Clearing Vitest and Vite caches (sometimes hidden in node_modules/.vite or node_modules/.cache).
• Searching your repo for stray Vitest config files or duplicate test properties in Vite configs—merging can cause hidden duplicates (docs).
• Checking for environment variables or CI scripts that might inject extra config.
• Ensuring only one Storybook test project is defined per browser instance.

2. Inspecting internal project names:
The storybookTest plugin generates project names based on your config. If you don’t set a name, it defaults to something like "storybook (chromium)". There’s no built-in verbose flag to print internal names, but you can explicitly set the name field in your Vitest config for each browser instance to guarantee uniqueness. If you want to inspect what names are being generated, you can temporarily log them by editing your local copy of the plugin or by printing the resolved config in your test setup (docs). Manual logging is the most direct way, as the plugin does not expose this info by default.

3. Known environment factors:
Besides config merging, stale build artifacts, hidden files, or leftover cache can cause Vitest to see duplicate projects. Also, if your repo has multiple Vitest configs (e.g., workspace files, legacy configs), they might be picked up together and merged, leading to duplicate names. Always isolate your Storybook tests from other test projects (docs).

References:

• Vitest addon docs: configuration, isolation, debugging
• Vitest workspace/project config example

If you want to guarantee no conflicts, explicitly set a unique name for each browser instance in your config. If the issue persists after all cleanup, try logging the resolved config to see what projects Vitest is registering.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[MH4GF]

@dosu Thanks, I will describe what else I have tried.

• Deleting node_modules and lockfiles (package-lock.json, yarn.lock, etc.), then reinstalling dependencies.
  • This did not solve the problem.
• Clearing Vitest and Vite caches (sometimes hidden in node_modules/.vite or node_modules/.cache).
  • This did not solve the problem.
• Searching your repo for stray Vitest config files or duplicate test properties in Vite configs—merging can cause hidden duplicates (docs).
  • There is only one vite.config.ts in the project.
• Checking for environment variables or CI scripts that might inject extra config.
  • This occurs on Macs as well as CI.
• Ensuring only one Storybook test project is defined per browser instance.
  • Yes, it occurs in only one.
• Changing the name causes problems.

[dosubot]

Thanks for the detailed info. Based on the code and docs, the Storybook Vitest addon does not manage unique project names for browser instances—this is handled by Vitest itself. The plugin only sets a unique project name when running via the Storybook UI, not for CLI or browser instance runs, so any project name conflict (like "storybook (chromium)" already defined) comes from Vitest's own merging logic, not the addon’s code (source).

There’s no built-in way to log internal project names; the only reliable workaround is to set an explicit, unique name for each browser instance in your config. If changing the name causes problems, could you share what specifically breaks (e.g., do tests not run, or do you get a different error)? That detail might help pinpoint a workaround.

For deeper debugging, try running npx vitest config in both your working and reproduction environments and diff the outputs—sometimes subtle config or dependency differences can cause Vitest to merge projects differently. Also, check for shadowed dependencies or subtle differences in how your test projects are picked up.

Let me know what happens when you change the name, and I can help interpret any new errors or behaviors.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}