Next page tester

The missing DOM integration testing tool for Next.js.

Given a Next.js route, this library will render the matching page in JSDOM, provided with the expected props derived from Next.js' routing system and data fetching methods.

import { getPage } from 'next-page-tester';
import { screen, fireEvent } from '@testing-library/react';

describe('Blog page', () => {
  it('renders blog page', async () => {
    const { render } = await getPage({
      route: '/blog/1',
    });

    render();
    expect(screen.getByText('Blog')).toBeInTheDocument();

    fireEvent.click(screen.getByText('Link'));
    await screen.findByText('Linked page');
  });
});

What
API
Options
Setting up your dev environment
Examples
Next.js versions support
FAQ

What

The idea behind this library is to reproduce as closely as possible the way Next.js works without spinning up servers, and render the output in a local JSDOM environment.

In order to provide a valuable testing experience next-page-tester replicates the rendering flow of an actual next.js application:

fetch data for a given route
render the server-side rendered result to JSDOM as plain html (including head element)
mount/hydrate the client application to the previously rendered html

The mounted application is interactive and can be tested with any DOM testing library (like @testing-library/react).

next-page-tester will take care of:

loading and execute modules in the expected browser or server environments
resolving provided routes into matching page component
calling Next.js data fetching methods (getServerSideProps, getInitialProps or getStaticProps) if the case
wrapping page with custom _app and _document components
emulating client side navigation via Link, router.push, router.replace
handling pages' redirect returns
supporting next/router, next/head, next/link, next/config and environment variables

API

getPage

getPage accepts an option object and returns 4 values:

import { getPage } from 'next-page-tester';

const { render, serverRender, serverRenderToString, page } = await getPage({
  options,
});

render()

Type: () => { nextRoot: HTMLElement<NextRoot> }
Returns: #__next root element element.

Unless you have an advanced use-case, you should mostly use this method. Under the hood it calls serverRender() and then mounts/hydrates the React application into JSDOM #__next root element. This is what users would get/see when they visit a page.

serverRender()

Type: () => { nextRoot: HTMLElement<NextRoot> }
Returns: #__next root element element.

Inject the output of server side rendering into the DOM but doesn't mount React. Use it to test how Next.js renders in the following scenarios:

before Reacts mounts
when JS is disabled
SEO tests

serverRenderToString()

Type: () => { html: string }

Render the output of server side rendering as HTML string. This is a pure method without side-effects.

page

Type: React.ReactElement<AppElement>

React element of the application.

Options

Property	Description	type	Default
route (mandatory)	Next route (must start with `/`)	`string`	-
req	Enhance default mocked request object	`req => req`	-
res	Enhance default mocked response object	`res => res`	-
router	Enhance default mocked Next router object	`router => router`	-
useApp	Render custom App component	`boolean`	`true`
~~useDocument~~ (experimental. Temporarily disabled due to this issue)	Render Document component	`boolean`	`false`
nextRoot	Absolute path to Next.js root folder	`string`	auto detected
dotenvFile	Relative path to a `.env` file holding environment variables	`string`	-
wrappers	Absolute path to wrappers file. Useful to decorate component tree with mocked providers.	`string`	-
sharedModules	List of modules that should preserve identity between client and server context.	`string[]`	[]

Setting up your dev environment

Handling special imports

If your pages/components import file types not natively handled by Node.js (like style sheets, images, .svg, ...), you should configure your testing environment to properly process them. Eg, in case of Jest you might want configuring some moduleNameMapper.

Setup JSDOM environment

next-page-tester expects to run into a JSDOM environment. If using Jest add this line to your jest configuration:

"testEnvironment": "jsdom",

Skipping Auto Cleanup & Helpers Initialisation

Since Next.js is not designed to run in a JSDOM environment we need to setup the default JSDOM to allow a smoother testing experience. By default, next-page-tester will:

Provide window.scrollTo and IntersectionObserver mocks
Cleanup DOM after each test
Setup jest to preserve the identity of some specific modules between "server" and "client" execution

However, you may choose to skip the auto cleanup & helpers initialisation by setting the NPT_SKIP_AUTO_SETUP env variable to true. You can do this with cross-env like so:

cross-env NPT_SKIP_AUTO_SETUP=true jest

Optional: patching Jest v26

If using Jest v26 you might need to patch it in order to load modules with proper server/client environments. Maintenance efforts will target latest Jest version.

Examples

Under examples folder we're documenting the testing cases which next-page-tester enables.

Next.js versions support

next-page-tester focuses on supporting only the last version of Next.js and Jest:

next-page-tester	next.js	Jest
v0.1.0 -> v0.7.0	v9.X.X	v26.X.X
v0.8.0 -> v0.22.0	v10.0.0 -> v10.0.7
v0.23.0 -> v0.25.X	v10.0.8 -> v11.0.X
v0.26.0 -> v0.27.X	v10.0.8 -> v11.0.X	v27.X.X
v0.28.0 -> v0.28.X	v11.1.0
v0.29.0 +	v11.1.1 +

Since:

this project is not supported by Next.js team
this project relies on a few Next.js internals which can change without notice in any version

please note that we cannot guarantee support for future versions of Next.js out of the box. Even patch or minor versions could break. In this case you'll have to wait for a new next-page-tester version to be released.

Contributions are very welcome and we do our best to support external contributors.

Notes

Data fetching methods' context req and res objects are mocked with node-mocks-http
Next page tester is designed to be used with any testing framework/library but It's currently only tested with Jest and Testing Library. Feel free to open an issue if you had troubles with different setups
It might be necessary to install @types/react-dom and @types/webpack when using Typescript in strict mode due to this bug

Experimental `useDocument` option

useDocument option is partially implemented and might be unstable.

FAQ

How do I mock API calls in my data fetching methods?

The first suggested way to mock network requests, consists of mocking at network layer with libraries like Mock service worker and Mirage JS.

Another viable approach might consist of mocking the global fetch object with libraries like fetch-mock.

In case you wanted a more traditional approach involving mocking the user land modules responsible for fetching data, you need to consider an extra step: since next-page-tester isolates modules between "client" and "server" rendering, those mocks that are created in tests (client context) won't execute in server context (eg. data fetching methods).

To overcome that, we need to "taint" such modules to (preserve/share) their identity between "client" and "server" context by passing them through the sharedModules option.

test('as a user I want to mock a module in client & server environment', async () => {
  const stub = jest.spyOn(api, 'getData').mockReturnValue(Promise.resolve('data'))

  const { render } = await getPage({
    route: '/page',
    nextRoot,
    sharedModules: [`${process.cwd()}/src/path/to/my/module`],
  });

  expect(stub).toHaveBeenCalledTimes(1); // this was executed in your data fetching method
}

How do I make cookies available in Next.js data fetching methods?

You can set cookies by appending them to document.cookie before calling getPage. next-page-tester will propagate cookies to ctx.req.headers.cookie so they will be available to data fetching methods. This also applies to subsequent fetching methods calls triggered by client side navigation.

test('authenticated page', async () => {
  document.cookie = 'SessionId=super=secret';
  document.cookie = 'SomeOtherCookie=SomeOtherValue';

  const { render } = await getPage({
    route: '/authenticated',
  });
  render();
});

Note: document.cookie does not get cleaned up automatically. You'll have to clear it manually after each test to keep everything in isolation.

Error: Not implemented: window.scrollTo

Next.js Link component invokes window.scrollTo on click which is not implemented in JSDOM environment. In order to fix the error you should set up your test environment or provide your own window.scrollTo mock.

Warning: Text content did not match. Server: "x" Client: "y" error

This warning means that your page renders differently between server and browser. This can be an expected behavior or signal a bug in your code.

Error: ReferenceError: fetch is not defined

This warning means that your application during rendering process performs some network requests which have not been mocked. You should find them and mock as needed.

Todo's

Consider reusing Next.js code parts (not only types)
Consider supporting Next.js trailingSlash option
Render custom _error page
Provide a debug option to log execution info

Contributors ✨

Thanks goes to these wonderful people (emoji key):

_{Andrea Carraro} 💻 🚇 ⚠️ 🚧	_{Matej Šnuderl} 💻 🚇 ⚠️ 👀 🤔 📖	_{Jason Williams} 🤔	_arelaxend 🐛	_kfazinic 🐛	_{Tomasz Rondio} 🐛	_{Alexander Mendes} 💻
_{Jan Sepke} 🐛	_DavidOrchard 🐛	_{Doaa Ismael} 🐛	_{Andrew Hurle} 🐛	_{massimeddu-sonic} 🐛	_{Jess Telford} 🐛	_Joseph 🐛 💻
_{Gergo Tolnai} 🐛 💻	_Brett 🐛	_{Vlad Elagin} 📖	_{Daniel Stockman} 💻	_madeuz 💻	_{Dr. Derek Austin} 🐛 💻	_Feargal 🐛
_{Jan R. Biasi} 🐛 💻	_{Otávio Augusto Soares} 🐛