Skip to content


Repository files navigation

Next page tester (deprecated)

deprecated Build status Test coverage report Npm version

This project is deprecated

Next.js took a development course which makes the testing approach adopted by this library obsolete. Next page tester maintainers suggest to use browser testing, instead.


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',

    await screen.findByText('Linked page');

Table of contents


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:

  1. fetch data for a given route
  2. render the server-side rendered result to JSDOM as plain html (including head element)
  3. 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



getPage accepts an option object and returns 4 values:

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

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


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.


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


Type: () => { html: string }

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


Type: React.ReactElement<AppElement>

React element of the application.


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.


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 -> v11.X
v0.31.0 + v12.1.0
v0.32.0 + v12.1.1 +


  • 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.


  • 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.


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',
    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',

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.


  • 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






Tomasz Rondio


Alexander Mendes


Jan Sepke




Doaa Ismael


Andrew Hurle




Jess Telford



๐Ÿ› ๐Ÿ’ป

Gergo Tolnai

๐Ÿ› ๐Ÿ’ป



Vlad Elagin


Daniel Stockman




Dr. Derek Austin

๐Ÿ› ๐Ÿ’ป



Jan R. Biasi

๐Ÿ› ๐Ÿ’ป

Otรกvio Augusto Soares


This project follows the all-contributors specification. Contributions of any kind welcome!