next-page-tester
Advanced tools
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');
});
});
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:
getServerSideProps, getInitialProps or getStaticProps) if the casenext/router provider initialized with the expected values (to test useRouter and withRouter)_app component_document componentLink, router.push, router.replace| 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 |
req and res objects are mocked with node-mocks-http@types/react-dom and @types/webpack when using Typescript in strict mode due to this bugnext-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 |
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.
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(...) errorRendering 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.
trailingSlash optionThanks 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!
0.10.0
document.cookie available to fetching methods as ctx.req.headers.cookiereferer available to fetching methods as ctx.req.headers.referergetInitialProps context req/res objects when execution happens as a result of client-side navigationFAQs
Enable DOM integration testing on Next.js pages
The npm package next-page-tester receives a total of 4,124 weekly downloads. As such, next-page-tester popularity was classified as popular.
We found that next-page-tester demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Ransomware payment rates hit an all-time low in 2024 as law enforcement crackdowns, stronger defenses, and shifting policies make attacks riskier and less profitable.
Security News
require(esm) backported to Node.js 20, easing the transition to ESM-only packages and reducing complexity for developers as Node 18 nears end-of-life.
Security News
PyPI now supports iOS and Android wheels, making it easier for Python developers to distribute mobile packages.