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 server side data fetching.

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 server side 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 component
instantiating page component with expected page props
Emulate client side navigation via Link, router.push, router.replace

Options

Property	Description	type	Default
route (mandatory)	Next route (must start with `/`)	`string`	-
req	Access default mocked request object (`getServerSideProps` only)	`res => res`	-
res	Access default mocked response object (`getServerSideProps` only)	`req => req`	-
router	Access default mocked Next router object	`router => router`	-
useCustomApp	Use custom App component	`boolean`	`true`
nextRoot	Absolute path to Next's root folder	`string`	auto detected

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

Error: Not implemented: window.scrollTo

Next.js Link components invoke 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.

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

Todo's

Consider adding custom Document support
Consider reusing Next.js code parts (not only types)
Consider supporting Next.js trailingSlash option