Testing frameworks (Vitest) cannot correctly resolve React to the internally used version, causing tests to fail

[jthrilly]

Link to the code that reproduces this issue

https://github.com/jthrilly/vitest-reproduction

To Reproduce

1. Run or build the application. Note that the getServerStuff() function returns the value correctly, without errors.
2. Run the test task, which triggers vitest. Notice that the test fails because React.cache is being resolved to the package.json version of React, 18.2.

The example reproduction uses React.cache, but the same is true of any React canary or experimental APIs which are "supported" in Next.

This issue also impacts other test runners, such as the node test runner and bun.

Current vs. Expected behavior

Current behaviour is that React.cache is not resolved in the test. Expected behaviour is that any test environment should have access to the same module resolution as the build and dev environments. If this is not the case by default, a compatibility layer must be provided.

Provide environment information

Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 23.4.0: Fri Mar 15 00:12:49 PDT 2024; root:xnu-10063.101.17~1/RELEASE_ARM64_T6020
  Available memory (MB): 32768
  Available CPU cores: 12
Binaries:
  Node: 20.11.0
  npm: 10.2.4
  Yarn: N/A
  pnpm: 8.15.5
Relevant Packages:
  next: 14.2.2 // Latest available version is detected (14.2.2).
  eslint-config-next: 14.2.2
  react: 18.2.0
  react-dom: 18.2.0
  typescript: 5.4.5
Next.js Config:
  output: N/A

Which area(s) are affected? (Select all that apply)

Testing

Which stage(s) are affected? (Select all that apply)

next dev (local), next build (local), next start (local)

Additional context

Unit tests (run via vitest, bun test, or the node test runner) that touch canary or experimental React features fail because they resolve React to the version in package.json, rather than the internal version used by Next.

Additionally, some next subpackage exports cannot be resolved by vittest, such as next/headers, next/cache, etc.

These issues have two causes:

1. Next is using an internal version of React, which is not resolved outside of next specific build/serve commands.
2. The way next/cache etc are exported is not compatible with the way that vite ESM module resolution works (a file extension is expected, for some reason).

Since vitest is one of the recommended ways to introduce unit testing into a NextJs app (as per the docs), I expect code that works in dev and production to also work in this test environment.

The React issue specifically can be worked around using a resolve alias in vitest that points to next/dist/compiled/react/cjs/react.development.js (this is demonstrated in the repro), but this creates a maintenance issue. Regardless of alias config, vitest cannot correctly resolve other next packages such as next/cache, next/headers etc.

Bottom line is that there should never be an intentional difference between the dev/prod and test environments. It totally undermines the testing!

[mdavish]

Also having this issue. Is there anything that can be done about this? Seems problematic given that NextJS specifically recommends testing with Vitest:

https://nextjs.org/docs/app/building-your-application/testing/vitest