with-jest and documentation not showing how to test route handlers

Verify canary release

• I verified that the issue exists in the latest Next.js canary release

Provide environment information

Operating System:
  Platform: linux
  Arch: x64
  Version: #56-Ubuntu SMP PREEMPT_DYNAMIC Sat Feb  8 00:37:57 UTC 2025
  Available memory (MB): 31782
  Available CPU cores: 12
Binaries:
  Node: 20.12.2
  npm: 10.5.0
  Yarn: N/A
  pnpm: 8.15.6
Relevant Packages:
  next: 15.2.1 // Latest available version is detected (15.2.1).
  eslint-config-next: N/A
  react: 18.3.1
  react-dom: 18.3.1
  typescript: 5.3.3
Next.js Config:
  output: N/A

Which example does this report relate to?

with-jest

What browser are you using? (if relevant)

No response

How are you deploying your application? (if relevant)

No response

Describe the Bug

Hi,
I am writing a short course on testing with Next.js and I hit a few issues with server code :

1. First nextJest from next/jest doesn't seem to support Jest projects option (as discussed here), which is needed to use the proper option testEnvironment: node for route handlers testing. Without this option, Next.js will trigger an error "ReferenceError: Request is not defined" (related issue). Hopefully we can set it up by hand using a top-level @jest-environment comment but that's not ideal. The fact that jsdom environment chokes on the web fetch API is unsettling, this old ticket seems to indicate that it is not supported. As far as I understand this could be problematic for testing React components too but haven't explored this area yet.

2. More problematic, it doesn't seem possible to mock next/headers module out-of-the-box. This discussion mentions that it could be related to SWC compilation, and advocates falling back to Babel. The other alternative is to use next-test-api-route-handler, it basically reimplements a Node.js async context. The complexity of a solution that you have to abbreviate to NTARH to pronounce it is not ideal for unit testing :)

3. On the bright side, async server components seems to be testable using a non-JSX syntax, it could be interesting to document that this is possible, or at least make it clear whether this is recommended or to be avoided for some reasons. I haven't explored calling fetch within these, perhaps it will raise issues with jsdom.

I can't tell if these issues also affect Vitest or Cypress and Playwright Component Testing systems but I suspect they could, since they are more related to Next.js building system.

Expected Behavior

Unit testing should feel more natural in Next.js.

To Reproduce

I've crafted a tiny demo, adding a route handler to "with-jest" example. You'll see the expected syntax for mocking in app/api/hello.test.js as well as the expected syntax for projects configuration in jest.config.js.

https://github.com/eric-burel/jest-route-handler-test-expectation
https://codesandbox.io/p/github/eric-burel/jest-route-handler-test-expectation/draft/late-shadow

Start with the with-jest example, especially app/api/hello.test.js and jest.config.js, then compare it with the linked route-handler reproduction. Document the supported testing setup and the relevant limitations around route handlers, next/headers, and server components, with guidance that matches the example.