Package Exports

next-page-tester

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (next-page-tester) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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

Options

Property	Description	type	Default
route (mandatory)	Next route (must start with `/`)	`string`	-
req	Enhance default mocked request object	`res => res`	-
res	Enhance default mocked response object	`req => req`	-
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

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

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

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