Trying to get unit tests to work

[thany]

Summary

I'm following the official documentation for this: https://nextjs.org/docs/app/building-your-application/testing/jest

First of all I'm curious how long ago this documentation was reviewed with the latest versions of Next.js and related packages, because there are problems from the get-go.

1. Typescript errors in jest.config.ts

Using the exact same config as in the documentation, the very last line of the config, where it says:

export default createJestConfig(config);

Has an error:

Default export of the module has or is using private name `ConfigGlobals`.

In order to fix this:

- import type { Config } from 'jest';
+ import { Config } from '@jest/types';

- const config: Config = {
+ const config: Config.InitialOptions = {

I wonder why this is neccesary, and why this hasn't been added to the documentation.

2. Errors in the test file

The documentation carries on to suggest a sample test file, called page.test.jsx. For some reason this has to be a JSX suddenly, while the rest of the documentation is typescript. So I naively make it a page.test.tsx and I am immediately confronted with errors.

The functions describe, it and expect are not defined. No wonder, they are not imported from anywhere. Where do I import them from? My VSCode suggest to import them from node:test but I am fairly confident this won't be the correct package to import them from.

So which is it? And then please also add this to the documentation - and add a typescript version of the test as well. Without the correct imports of test functions, surely it will error in javascript with type checking, just as it will in typescript.

3. Errors in the test itself

If I carry on and mentally ignore the errors from (2), to run the example test, I find that it too, produces errors. And not the right kinds of errors.

ReferenceError: TextEncoder is not defined

There are quite a few people running into this problem and providing a workaround that seems to mitigate the situation, where in the jest.setup.ts, you would add:

import { TextEncoder, TextDecoder } from 'util';

Object.assign(global, { TextDecoder, TextEncoder });

I wonder if this should be neccesary. Especially because after adding this, it just starts complaining about the next global it reportedly can't find:

ReferenceError: Request is not defined

So I'm like, "what's next?" Do I assign all possible global objects to the global object? Surely, this shouldn't be neccesary. Surely, some kind of config is missing, that the documentation skips. But what? And please, whatever the solution turns out to be, add it to the documentation.

Additional information

Operating System:
  Platform: win32
  Arch: x64
  Version: Windows 10 Pro
  Available memory (MB): 32440
  Available CPU cores: 20
Binaries:
  Node: 20.18.0
  npm: 10.9.2
  Yarn: 1.22.22
  pnpm: N/A
Relevant Packages:
  next: 15.1.0
  eslint-config-next: 15.0.3
  react: 19.0.0
  react-dom: 19.0.0
  typescript: 5.5.4
Next.js Config:
  output: N/A

Example

No response

[icyJoseph]

Jest makes describe, it, etc, available in the global scope.

The TextEncoder issue comes from JSDOM: jsdom/jsdom#2524

The solution is to provide the TextEncoder within your setup file. See here for example: inrupt/solid-client-authn-js#1676 (comment)

Check this repository out: https://github.com/vercel/next.js/tree/canary/examples/with-jest ~ it also uses TypeScript across the board

Several things are kind of hit or miss when testing. You have to understand that, to simulate the DOM, we use JSDOM and are limited by its capabilities. And also Jest itself, doesn't really understand TypeScript, nor ESM, etc, so you have to handle that yourself. Next.js' setup handles the TypeScript processing for you.

As your unit testing skill grows, you'll see that one has to balance between, adding stuff to the JSDOM globals, mocking them, or just straight up changing your testing strategy, because, otherwise, one would sink a lot more of time adding/mocking, and most likely end up testing your own mocks, instead of your application code.

[thany]

To fix the types. You have to install @types/jest.

Sorry but no, that doesn't fix it.

Cannot find name 'describe'.

Because typescript wants them to be imported from something. How else could it know where to pull them from?

You can use create-next-app with the Next.js with-jest example to quickly get started

Great, but like I said, having an example around is good for peeking on how to write something, but to fix weird problems, I have no idea where to look in that very example. It might as well be magic.

To get Request working, IIRC, you have to do:

I keep repeating myself, but I followed the documentation, so how is it that the documentation recommends testEnvironment: 'jsdom' when that doesn't work with a Next.js page, as is suggested to write a test for?

And some of your unit tests, will need to be in node, others in jsdom.

And why is that? I have never had to do that in other projects. And what if neither works? Why isn't there one environment that works for both at the same time? In short, I don't want to have to care about this - I just want to test code.

[thany]

Welcome to software development?

Thanks, but you should've said that 23 years ago. No offence taken :)

[icyJoseph]

Because typescript wants them to be imported from something. How else could it know where to pull them from?

Have you seen, https://stackblitz.com/edit/nextjs-qkq9bcco?file=jest.config.ts,jest.setup.ts,app%2Ffoo.test.tsx, it works there. Perhaps you have to restart your IDE/text-editor to get the language server to pick up the types?

And why is that? I have never had to do that in other projects. And what if neither works? Why isn't there one environment that works for both at the same time? In short, I don't want to have to care about this - I just want to test code.

JavaScript? What if my test uses fs, but my other test uses localStorage.

[icyJoseph]

Which brings me to this issue: testing-library/react-testing-library#1209 (comment)

Server Components, amidst Unit Testing... oh boy are you in for a ride. That thread linked there has some interesting comments, if you can find them through the GitHub collapsed comments.

• Support for React Server Components testing-library/react-testing-library#1209 (comment)

[icyJoseph]

Was trying to find this thread, #53409, I thought it was a PR, but it was an RFC rather, that sort of addresses your concerns

[thany]

Ok, I got there in the end. I'm not gonna leave everyone in the dust, so to recap my changes on top of what you'll get from the documentation (at the time of writing this):

1. Changes to jest.config.ts

This is to make Typescript happy. I'm not sure why this is needed, and I'm not seeing it required for the example project, but it was required for my setup and I don't know why. Possibly because jest no longer provides typings, but even then Typescript should be able to find them. I have never had to do anything like this. But there's a first for everything, right.

- import type { Config } from 'jest';
+ import { Config } from '@jest/types';

- const config: Config = {
+ const config: Config.InitialOptions = {

2. Changes to jest.setup.ts

Install the dependency that provides Request:

npm i -D whatwg-fetch

And make changes to your jest.setup.ts:

+ import 'whatwg-fetch';

+ import { TextDecoder, TextEncoder } from 'util';
+ Object.assign(global, { TextDecoder, TextEncoder });

First import is needed to mitigate the error ReferenceError: Request is not defined. This can sometimes be worked around by putting a test in the node environment, but this won't work when testing components - only when testing functions (and perhaps server components, which I haven't tried).

The last 2 lines are needed to mitigate the error ReferenceError: TextDecoder is not defined. It's beyond me why this is neccesary. Why is this not baked into Jest? Also I don't know where this util package is coming from, but it exists, apparently.

3. Add typeRoots to tsconfig.json (monorepo only)

When in a monorepo, make sure your tsconfig can "find" types at the monorepo root level. There is no magic that makes that happen automatically, sadly.

{
  "compilerOptions": {
    "typeRoots": [
+     "../../node_modules/@types"
    ]
  }
}

For your particular setup, it might need more or fewer ../ parts to find the directory at the intended root level. For my particular setup, step 4 below was already done for an earlier package at the root level, which is why this step was important. So I guess I'm saying "it depends".

4. Add an additional tsconfig.json for tests

Install the dependency that provides Jest typings:

npm i -D @types/jest

To make testing functions available to tests, add this tsconfig.json to your __tests__ directory:

{
  "extends": "../tsconfig.json",
  "compilerOptions": {
    "types": [ "jest" ]
  }
}

Conclusion

Despite all the messing about trying to get to a working state, I do think this is it. This will make tests in their simplest form at least, run without crashing.

If these findings could be incorporated into the documentation, that'd be great for the next person that comes along to look for guidance on how to install Jest into a Next.js project. And not only the documentation, but the example/boilerplate projects also suffered partly from these problems, and therefor also need to be in scope.

It's important that a basic setup at least does what it says on the tin, which it now does.