Support Vitest `projects` option for Browser Mode

[JessicaSachs]

Describe the feature

I'd like to run multiple Vitest projects.

Currently there is no documentation for how to support multiple Nuxt test utils projects. There's a method defineVitestProject which sounds great, but it's not documented. I'm getting an exception when I try to use it, so I'm not sure if it's broken or if I'm using it wrong.

Desired Functionality

I would like to:

1. Kick off a suite of Nuxt-environment (node-based) unit tests (this works)
2. Kick off a suite of Nuxt Browser Mode component tests (throws exception during cleanup, see comment below)
3. Kick off a suite of Nuxt e2e tests (this works)

Attempted Configuration

The syntax that I believe should cause this to happen is something along the lines of the following:

import { defineVitestProject } from '@nuxt/test-utils/config'
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    projects: [
      defineVitestProject({
        test: {
          browser: {
            enabled: true,
            provider: 'playwright',
            instances: [{ browser: 'chromium' }],
          },
          environment: 'nuxt',
          include: ['**/*.browser.test.{ts,js}'],
          setupFiles: ['vitest-browser-vue'],
          name: 'component',
        }
      }),
      defineVitestProject({
        test: {
          include: ['**/*.unit.test.{ts,js}'],
          name: 'unit',
          environment: 'nuxt',
        }
      }),
      defineVitestProject({
        test: {
          include: ['**/*.e2e.test.{ts,js}'],
          name: 'e2e',
          environment: 'nuxt',
        }
      })
    ]
  }
})

Results

When I run pnpm vitest run, my suite works, and then I get an error that says "Cannot set properties of undefined (setting 'PROD')" and the process exits with an error code.

Workaround

Using defineVitestConfig and hoisting the configuration up to root works fine. Unfortunately I'd need to run three Vitest tasks and couldn't make use of the projects functionality.

For example:

pnpm vitest --config vitest.browser.config.ts
pnpm vitest --config vitest.unit.config.ts
pnpm vitest --config vitest.e2e.config.ts
# 😔

---

So, I can't figure out how to get it working. I've tried different combinations, singular projects, and using the deprecated workspaces key. The method defineVitestProject isn't documented and I've read through the code and I'm not really sure why I'm getting an error.

Nuxt Info

- Operating System: `Darwin`
- Node Version:     `v22.14.0`
- Nuxt Version:     `3.17.5`
- CLI Version:      `3.25.1`
- Nitro Version:    `2.11.12`
- Package Manager:  `pnpm@10.11.1`
- Builder:          `-`
- User Config:      `compatibilityDate`, `modules`
- Runtime Modules:  `@nuxt/test-utils/module@3.19.1`
- Build Modules:    `-`

Additional information

• Would you be willing to help implement this feature?
• Could this feature be implemented as a module?

Final checks

• Read the contribution guide.
• Check existing discussions and issues.

[danielroe]

Your e2e tests should not run in a nuxt environment - that's only for your runtime tests (the ones that are running in a DOM environment)

[karladler]

@danielroe nevertheless I think workspaces should be considered, I currently get the warning when staring vitest setup as described in the docs:

DEPRECATED The test.workspace option is deprecated and will be removed in the next major. To hide this warning, rename test.workspace option to test.projects.

(vitest 3.2.4, nuxt 3.17)

[danielroe]

yes, we released it workspace support immediately before vitest renamed it to projects. we'll update in the next release, dropping support for older vitest versions

(but that doesn't affect my comment - you should still not run your e2e tests in a config created with defineVitestConfig from the nuxt test utils)

[JessicaSachs]

OK! Let me simplify this a bit further. I'm still getting that "prod" error, but it's because of browser mode being run within projects - not because of a lack of support for projects of mixed types.

The following suite runs successfully. The addition of Browser Mode causes there to be an unhandled error during cleanup.

This unhandled error for Browser mode only occurs when the projects key is being used and only on completion of all projects. Going to update the issue to be more specific.

Node/Nuxt-based Multi-Project Config (working fine)

import { defineVitestProject } from '@nuxt/test-utils/config'
import { defineConfig } from 'vitest/config'


export default defineConfig({
  test: {
    projects: [
      defineVitestProject({
        test: {
          environment: 'nuxt',
          include: ['**/*.test.{ts,js}'],
          name: 'unit',
        },
      }),
      {
        test: {
          name: 'e2e',
          environment: 'node',
          include: ['test/e2e/**/*.test.{ts,js}'],
          setupFiles: ['test/e2e/setup.ts'],
        },
      },
    ],
  },
})

Browser Mode (with Projects, fails during cleanup)

Config

import { defineVitestProject } from '@nuxt/test-utils/config'
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    projects: [
      defineVitestProject({
        test: {
          browser: {
            enabled: true,
            provider: 'playwright',
            instances: [{ browser: 'chromium' }],
          },
          environment: 'nuxt',
          include: ['**/*.browser.test.{ts,js}'],
          setupFiles: ['vitest-browser-vue'],
          name: 'component',
        },
      }),
    ],
  },
})

Browser Mode (top-level, passes)

Config

import { defineVitestConfig } from '@nuxt/test-utils/config'


export default defineVitestConfig({
  test: {
    browser: {
      enabled: true,
      provider: 'playwright',
      instances: [{ browser: 'chromium' }],
    },
    environment: 'nuxt',
    include: ['**/*.browser.test.{ts,js}'],
    setupFiles: ['vitest-browser-vue'],
    name: 'component',
  },
})