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

import { render, screen } 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',
      pagesDirectory: process.cwd() + '/src/pages',
    });

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

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

Options

Property	Description	type	Default
route	Next route (must start with /)	-	-
pagesDirectory	Absolute path to Next's /pages folder	-	-
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	-
customApp	Use custom App component	boolean	false
pageExtensions	Custom Page Extensions	string[]	['mdx', 'jsx', 'js', 'ts', 'tsx']

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.

It might be necessary to install @types/react-dom and @types/webpack when using Typescript in strict mode due to this bug.

Todo's

• Make available dynamic api routes under /pages/api
• Consider adding custom Document
• Consider adding a getPage factory
• Consider reusing Next.js code parts (not only types)
• Consider loading pageExtensions option from next.config.js

Changelog

0.4.0

Breaking Changes

• Support custom App's data fetching with getInitialProps
• Throw error when no matching page is found

New Features

• Support custom file extensions via pageExtensions option
• Migrate tests to TS