nuxt/test-utils & happy-dom incompatibility (vitest ^4.x.x)

[simon-kramer]

Description

@nuxt/test-utils@3.19.2 has outdated peer dependency constraints that prevent users from upgrading to the latest stable versions of vitest (v4.x) and happy-dom (v19.x/v20.x).
This creates a dependency management challenge and blocks projects from using the latest features and bug fixes in these dependencies.

Current Peer Dependencies (v3.19.2)

{
  "vitest": "^3.2.0",
  "happy-dom": "^9.10.9 || ^10.0.0 || ^11.0.0 || ^12.0.0 || ^13.0.0 || ^14.0.0 || ^15.0.0 || ^16.0.0 || ^17.0.0 || ^18.0.0"
}

Latest Stable Versions (as of October 2025)

• vitest: 4.0.2 (stable)
• @vitest/coverage-v8: 4.0.2
• happy-dom: 20.0.8

Impact

When attempting to upgrade dependencies to their latest versions, users encounter peer dependency conflicts:

Error Example

npm error ERESOLVE could not resolve
npm error
npm error While resolving: @nuxt/test-utils@3.19.2
npm error Found: happy-dom@20.0.8
npm error node_modules/happy-dom
npm error   dev happy-dom@"^20.0.8" from the root project
npm error
npm error Could not resolve dependency:
npm error peerOptional happy-dom@"^9.10.9 || ^10.0.0 || ... || ^18.0.0" from @nuxt/test-utils@3.19.2
npm error
npm error Conflicting peer dependency: happy-dom@18.0.1

Reproduction

Minimal Reproduction Repository

You can reproduce this issue with the following steps:

1. Create a new Nuxt project with test-utils

npx nuxi@latest init nuxt-test-utils-issue
cd nuxt-test-utils-issue

2. Install @nuxt/test-utils and testing dependencies

npm install --save-dev @nuxt/test-utils vitest @vitest/coverage-v8 happy-dom @vue/test-utils

3. Attempt to upgrade to latest stable versions

npm install --save-dev vitest@^4.0.2 @vitest/coverage-v8@^4.0.2 happy-dom@^20.0.8

Result: Installation succeeds with --legacy-peer-deps but shows peer dependency warnings.

4. Try to install with npm ci (simulating CI/CD)

rm -rf node_modules
npm ci

Result: Fails with ERESOLVE error.

Alternative: Reproduce with existing project

If you have an existing Nuxt project:

Install current stable versions

npm install --save-dev @nuxt/test-utils@^3.19.2

Try to upgrade test dependencies

npm install --save-dev vitest@latest @vitest/coverage-v8@latest happy-dom@latest

This will fail with peer dependency conflicts

npm ci

Expected package.json after upgrade attempt

{
  "devDependencies": {
    "@nuxt/test-utils": "^3.19.2",
    "@vitest/coverage-v8": "^4.0.2",
    "@vue/test-utils": "^2.4.6",
    "happy-dom": "^20.0.8",
    "nuxt": "^4.1.3",
    "vitest": "^4.0.2"
  }
}

Error Output

npm error code ERESOLVE
npm error ERESOLVE could not resolve
npm error
npm error While resolving: @nuxt/test-utils@3.19.2
npm error Found: happy-dom@20.0.8
npm error node_modules/happy-dom
npm error   dev happy-dom@"^20.0.8" from the root project
npm error   peerOptional happy-dom@"*" from vitest@4.0.2
npm error   node_modules/vitest
npm error     dev vitest@"^4.0.2" from the root project
npm error     peer vitest@"4.0.2" from @vitest/coverage-v8@4.0.2
npm error     node_modules/@vitest/coverage-v8
npm error       dev @vitest/coverage-v8@"^4.0.2" from the root project
npm error
npm error Could not resolve dependency:
npm error peerOptional happy-dom@"^9.10.9 || ^10.0.0 || ^11.0.0 || ^12.0.0 || ^13.0.0 || ^14.0.0 || ^15.0.0 || ^16.0.0 || ^17.0.0 || ^18.0.0" from @nuxt/test-utils@3.19.2
npm error node_modules/@nuxt/test-utils
npm error   dev @nuxt/test-utils@"^3.19.2" from the root project
npm error   @nuxt/test-utils@">=3.13.1" from vitest-environment-nuxt@1.0.1
npm error   node_modules/vitest-environment-nuxt
npm error     vitest-environment-nuxt@"^1.0.1" from @nuxt/test-utils@3.19.2
npm error
npm error Conflicting peer dependency: happy-dom@18.0.1
npm error node_modules/happy-dom
npm error   peerOptional happy-dom@"^9.10.9 || ^10.0.0 || ^11.0.0 || ^12.0.0 || ^13.0.0 || ^14.0.0 || ^15.0.0 || ^16.0.0 || ^17.0.0 || ^18.0.0" from @nuxt/test-utils@3.19.2
npm error   node_modules/@nuxt/test-utils
npm error     dev @nuxt/test-utils@"^3.19.2" from the root project
npm error     @nuxt/test-utils@">=3.13.1" from vitest-environment-nuxt@1.0.1
npm error     node_modules/vitest-environment-nuxt
npm error       vitest-environment-nuxt@"^1.0.1" from @nuxt/test-utils@3.19.2
npm error
npm error Fix the upstream dependency conflict, or retry
npm error this command with --force or --legacy-peer-deps

CI/CD Reproduction

Create .gitlab-ci.yml or .github/workflows/test.yml:

  .gitlab-ci.yml
  test:
    image: node:24
    script:
      - npm ci
      - npm run test

Result: Pipeline fails at npm ci step with the above error.
Verification that issue is in @nuxt/test-utils
You can verify the peer dependency constraint by running:

  npm view @nuxt/test-utils@3.19.2 peerDependencies

Output:

  {
    "happy-dom": "^9.10.9 || ^10.0.0 || ^11.0.0 || ^12.0.0 || ^13.0.0 || ^14.0.0 || ^15.0.0 || ^16.0.0 || ^17.0.0 || ^18.0.0",
    "vitest": "^3.2.0"
  }

Compare with latest vitest peer dependencies:

npm view vitest@4.0.2 peerDependencies

  Output:
  {
    "happy-dom": "*"
  }

This shows that vitest@4.0.2 supports any version of happy-dom, but @nuxt/test-utils@3.19.2 limits it to v18.x maximum.

This reproduction section provides:

1. Step-by-step instructions to reproduce the issue
2. Multiple reproduction methods (new project, existing project, CI/CD)
3. Expected vs actual behavior
4. Complete error output
5. Verification commands showing the root cause

Additional context

Update the peer dependency ranges in package.json to include:

• vitest@^3.2.0 || ^4.0.0
• happy-dom versions up to ^20.0.0

This would allow users to stay on the latest stable versions while maintaining backward compatibility with v3.x users.

[saia-richard]

This will also enable to fix the critical issue with happy-dom <= ^20.0.0. GHSA-37j7-fg3j-429f

[ExEr7um]

@simon-kramer It should be fixed in v3.20.1.

[ps-20x]

@ExEr7um the update for happy-dom is fixed but the upgrade of vitest to version 4 is not yet "fixed" as vitest is explicitly required in version 3.2.4.