next-page-tester

Next page tester

The missing DOM integration testing tool for Next.js.

Given a Next.js route, this library will return an instance of the matching page component instantiated with the properties derived by Next.js' routing system and data fetching methods.

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

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

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

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

What

The idea behind this library is to enable DOM integration tests on Next.js pages along with data fetching and routing.

The testing approach suggested here consists of manually mocking external API's dependencies and get the component instance matching a given route.

Next page tester will take care of:

• resolving provided routes into matching page component
• calling Next.js data fetching methods (getServerSideProps, getInitialProps or getStaticProps) if the case
• set up a mocked next/router provider initialized with the expected values (to test useRouter and withRouter)
• wrapping page with custom _app and _document components
• instantiating page component with expected page props
• emulating client side navigation via Link, router.push, router.replace
• handling pages' redirect returns

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)	Render Document component	boolean	false
nextRoot	Absolute path to Next.js root folder	string	auto detected

Set up your test environment

Since Next.js is not designed to run in a JSDOM environment we need to tweak the default JSDOM environment to avoid unexpected errors and allow a smoother testing experience:

• Provide a window.scrollTo mock
• Provide a IntersectionObserver mock
• Silence validateDOMNesting(...) error
• Remove initial <head/> element
• Resolve next/dist/next-server/lib/side-effect module in non-brwoser environment

Next page tester provides a helper to setup the expected JSDOM environment as described.

Run initTestHelpers in your global tests setup (in case of Jest It is setupFilesAfterEnv file):

import { initTestHelpers } from 'next-page-tester';
initTestHelpers();

If useDocument option enabled

In case your tests make use of experimental useDocument option, take the following additional steps:

import { initTestHelpers } from 'next-page-tester';
const { setup, teardown } = initTestHelpers();

beforeAll(() => {
  setup();
});

afterAll(() => {
  teardown();
});

Optional: patch Jest

Until Jest v27 is published, you might need to patch jest in order to load modules with proper server/client environments. Don't do this until you actually encounter issues.

1. Install patch-package and follow its setup instructions
2. Manually update node_modules/jest-runtime/build/index.js file and replicate this commit
3. Run npx patch-package jest-runtime or yarn patch-package jest-runtime

Notes

• Data fetching methods' context req and res objects are mocked with node-mocks-http
• Next page tester can be used with any testing framework/library (not tied to Testing library)
• 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. It might produce a UnhandledPromiseRejectionWarning warning on client side navigation.

Next.js versions support

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

next-page-tester	next.js
v0.1.0 - v0.7.0	v9.X.X
v0.8.0 +	v10.X.X

FAQ

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 { page } = 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 provide your own window.scrollTo mock.

useDocument option and validateDOMNesting(...) error

Rendering the page instance returned by next-page-tester with useDocument option enabled in a JSDOM environment, causes react-dom to trigger a validateDOMNesting(...) error.

This happens because the tested page includes tags like <html>, <head> and <body> which are already declared by JSDOM default document.

A temporary workaround consists of mocking global console.error to ignore the specific error.

Todo's

• Consider reusing Next.js code parts (not only types)
• Consider supporting Next.js trailingSlash option

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Andrea Carraro 💻 🚇 ⚠️ 🚧

Matej Šnuderl 💻 🚇 ⚠️ 👀 🤔 📖

Jason Williams 🤔

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