Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/next-page-tester/next-page-tester
DEPRECATED - DOM integration testing for Next.js
https://github.com/next-page-tester/next-page-tester
browserless integration-testing nextjs testing
Last synced: 11 days ago
JSON representation
DEPRECATED - DOM integration testing for Next.js
- Host: GitHub
- URL: https://github.com/next-page-tester/next-page-tester
- Owner: next-page-tester
- License: mit
- Created: 2020-09-06T20:02:49.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2022-07-03T08:17:15.000Z (over 2 years ago)
- Last Synced: 2024-10-29T23:52:49.847Z (about 1 month ago)
- Topics: browserless, integration-testing, nextjs, testing
- Language: TypeScript
- Homepage:
- Size: 2.04 MB
- Stars: 622
- Watchers: 8
- Forks: 28
- Open Issues: 18
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
- Awesome-NextJs - next-page-tester - [example](https://github.com/next-page-tester/next-page-tester/tree/master/examples) (Nextjs Plugins)
README
# Next page tester (deprecated)
[](http://github.com/badges/stability-badges)
[![Build status][ci-badge]][ci]
[![Test coverage report][coveralls-badge]][coveralls]
[![Npm version][npm-badge]][npm]
## This project is deprecated
Next.js took a development course which makes the testing approach adopted by this library obsolete. Next page tester maintainers suggest to use browser testing, instead.
## Intro
The missing DOM integration testing tool for [Next.js][next-github].
Given a Next.js route, this library will **render the matching page in JSDOM**, provided with the expected **props** derived from Next.js' [**routing system**][next-docs-routing] and [**data fetching methods**][next-docs-data-fetching].
```js
import { getPage } from 'next-page-tester';
import { screen, fireEvent } from '@testing-library/react';
describe('Blog page', () => {
it('renders blog page', async () => {
const { render } = await getPage({
route: '/blog/1',
});
render();
expect(screen.getByText('Blog')).toBeInTheDocument();
fireEvent.click(screen.getByText('Link'));
await screen.findByText('Linked page');
});
});
```
## Table of contents
- [What](#what)
- [API](#api)
- [Options](#options)
- [Setting up your dev environment](#setting-up-your-dev-environment)
- [Examples](#examples)
- [Next.js versions support](#nextjs-versions-support)
- [FAQ](#faq)
## What
The idea behind this library is to reproduce as closely as possible the way Next.js works without spinning up servers, and render the output in a local JSDOM environment.
In order to provide a valuable testing experience `next-page-tester` replicates the **rendering flow of an actual `next.js` application**:
1. **fetch data** for a given route
2. **render** the server-side rendered result to JSDOM as plain html (including `head` element)
3. **mount/hydrate** the client application to the previously rendered html
The mounted application is **interactive** and can be tested with any DOM testing library (like [`@testing-library/react`](https://testing-library.com/docs/react-testing-library/intro)).
`next-page-tester` will take care of:
- loading and execute modules in the **expected browser or server environments**
- **resolving** provided **routes** into matching page component
- calling **Next.js data fetching methods** (`getServerSideProps`, `getInitialProps` or `getStaticProps`) if the case
- wrapping page with custom `_app` and `_document` components
- emulating **client side navigation** via `Link`, `router.push`, `router.replace`
- handling pages' `redirect` returns
- supporting [`next/router`][next-docs-router], [`next/head`][next-docs-head], [`next/link`][next-docs-link], [`next/config`][next-docs-runtime-config] and environment variables
## API
### getPage
`getPage` accepts an [option object](#options) and returns 4 values:
```js
import { getPage } from 'next-page-tester';
const { render, serverRender, serverRenderToString, page } = await getPage({
options,
});
```
### render()
Type: `() => { nextRoot: HTMLElement }`
Returns: `#__next` root element element.
Unless you have an advanced use-case, you should mostly use this method. Under the hood it calls `serverRender()` and then mounts/hydrates the React application into JSDOM `#__next` root element. This is what users would get/see when they visit a page.
### serverRender()
Type: `() => { nextRoot: HTMLElement }`
Returns: `#__next` root element element.
Inject the output of server side rendering into the DOM but doesn't mount React. Use it to test how Next.js renders in the following scenarios:
- before Reacts mounts
- when JS is disabled
- SEO tests
### serverRenderToString()
Type: `() => { html: string }`
Render the output of server side rendering as HTML string. This is a pure method without side-effects.
### page
Type: `React.ReactElement`
React element of the application.
## Options
| Property | Description | type | Default |
| ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------ | --------------- |
| **route** (mandatory) | Next route (must start with `/`) | `string` | - |
| **req** | Enhance default mocked [request object][req-docs] | `req => req` | - |
| **res** | Enhance default mocked [response object][res-docs] | `res => res` | - |
| **router** | Enhance default mocked [Next router object][next-docs-router] | `router => router` | - |
| **useApp** | Render [custom App component][next-docs-custom-app] | `boolean` | `true` |
| ~**useDocument**~ (experimental. Temporarily disabled due to [this issue](https://github.com/toomuchdesign/next-page-tester/issues/263)) | Render [Document component][next-docs-custom-document] | `boolean` | `false` |
| **nextRoot** | Absolute path to Next.js root folder | `string` | _auto detected_ |
| **dotenvFile** | Relative path to a `.env` file holding [environment variables][next-docs-env-vars] | `string` | - |
| **wrappers** | Absolute path to [wrappers file](./docs/wrappers-file.md). Useful to decorate component tree with mocked providers. | `string` | - |
| **sharedModules** | List of modules that should preserve identity between client and server context. | `string[]` | [] |
## Setting up your dev environment
### Handling special imports
If your pages/components import **file types not natively handled by Node.js** (like style sheets, images, `.svg`, ...), you should configure your testing environment to properly process them. Eg, in case of Jest you might want configuring some [`moduleNameMapper`](https://jestjs.io/docs/en/configuration#modulenamemapper-objectstring-string--arraystring).
### Setup JSDOM environment
`next-page-tester` expects to run into a JSDOM environment. If using Jest add this line to your `jest` configuration:
```js
"testEnvironment": "jsdom",
```
### Skipping Auto Cleanup & Helpers Initialisation
Since Next.js is not designed to run in a JSDOM environment we need to **setup the default JSDOM** to allow a smoother testing experience. By default, `next-page-tester` will:
- Provide `window.scrollTo` and `IntersectionObserver` mocks
- Cleanup DOM after each test
- Setup jest to preserve the identity of some specific modules between "server" and "client" execution
However, you may choose to skip the auto cleanup & helpers initialisation by setting the `NPT_SKIP_AUTO_SETUP` env variable to `true`. You can do this with [`cross-env`](https://www.npmjs.com/package/cross-env) like so:
```js
cross-env NPT_SKIP_AUTO_SETUP=true jest
```
### Optional: patching Jest v26
If using **Jest v26** you might need to [patch it](./docs/patching-jest-v26.md) in order to load modules with [proper server/client environments](#73). Maintenance efforts will target latest Jest version.
## Examples
Under [examples folder][examples-folder] we're documenting the testing cases which `next-page-tester` enables.
## Next.js versions support
`next-page-tester` focuses on supporting only the last version of Next.js and Jest:
| next-page-tester | next.js | Jest |
| ------------------ | ------------------ | ------- |
| v0.1.0 -> v0.7.0 | v9.X.X | v26.X.X |
| v0.8.0 -> v0.22.0 | v10.0.0 -> v10.0.7 | |
| v0.23.0 -> v0.25.X | v10.0.8 -> v11.0.X | |
| v0.26.0 -> v0.27.X | v10.0.8 -> v11.0.X | v27.X.X |
| v0.28.0 -> v0.28.X | v11.1.0 | |
| v0.29.0 + | v11.1.1 -> v11.X | |
| v0.31.0 + | v12.1.0 | |
| v0.32.0 + | v12.1.1 + | |
Since:
- this project is not supported by Next.js team
- this project relies on a few Next.js internals which can change without notice in any version
please note that we cannot guarantee support for future versions of Next.js out of the box. Even patch or minor versions could break. In this case you'll have to wait for a new `next-page-tester` version to be released.
Contributions are very welcome and we do our best to support external contributors.
## Notes
- Data fetching methods' context `req` and `res` objects are mocked with [node-mocks-http][node-mocks-http]
- Next page tester is designed to be used with any testing framework/library but It's currently only tested with Jest and Testing Library. Feel free to open an issue if you had troubles with different setups
- It might be necessary to install `@types/react-dom` and `@types/webpack` when using Typescript in `strict` mode due to [this bug][next-gh-strict-bug]
### Experimental `useDocument` option
`useDocument` option is partially implemented and might be unstable.
## FAQ
### How do I mock API calls in my data fetching methods?
The first suggested way to mock network requests, consists of **mocking at network layer** with libraries like [`Mock service worker`](https://github.com/mswjs/msw) and [`Mirage JS`](https://github.com/miragejs/miragejs).
Another viable approach might consist of **mocking the global `fetch` object** with libraries like [`fetch-mock`](https://www.npmjs.com/package/fetch-mock).
In case you wanted a more traditional approach involving mocking the user land modules responsible for fetching data, you need to consider an extra step: since `next-page-tester` isolates modules between "client" and "server" rendering, those mocks that are created in tests (client context) won't execute in server context (eg. data fetching methods).
To overcome that, we need to "taint" such modules to (preserve/share) their identity between "client" and "server" context by passing them through the `sharedModules` option.
```ts
test('as a user I want to mock a module in client & server environment', async () => {
const stub = jest.spyOn(api, 'getData').mockReturnValue(Promise.resolve('data'))
const { render } = await getPage({
route: '/page',
nextRoot,
sharedModules: [`${process.cwd()}/src/path/to/my/module`],
});
expect(stub).toHaveBeenCalledTimes(1); // this was executed in your data fetching method
}
```
### 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.
```ts
test('authenticated page', async () => {
document.cookie = 'SessionId=super=secret';
document.cookie = 'SomeOtherCookie=SomeOtherValue';
const { render } = await getPage({
route: '/authenticated',
});
render();
});
```
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 [set up your test environment](#set-up-your-test-environment) or provide [your own `window.scrollTo` mock](https://qiita.com/akameco/items/0edfdae02507204b24c8).
### Warning: Text content did not match. Server: "x" Client: "y" error
This warning means that your page renders differently between server and browser. This can be an expected behavior or signal a bug in your code.
### Error: ReferenceError: fetch is not defined
This warning means that your application during rendering process performs some network requests which have not been mocked. You should find them and mock as needed.
## Todo's
- Consider reusing Next.js code parts (not only types)
- Consider supporting Next.js `trailingSlash` option
- Render custom `_error` page
- Provide a `debug` option to log execution info
## Contributors β¨
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
Andrea Carraro
π» π β οΈ π§
Matej Ε nuderl
π» π β οΈ π π€ π
Jason Williams
π€
arelaxend
π
kfazinic
π
Tomasz Rondio
π
Alexander Mendes
π»
Jan Sepke
π
DavidOrchard
π
Doaa Ismael
π
Andrew Hurle
π
massimeddu-sonic
π
Jess Telford
π
Joseph
π π»
Gergo Tolnai
π π»
Brett
π
Vlad Elagin
π
Daniel Stockman
π»
madeuz
π»
Dr. Derek Austin
π π»
Feargal
π
Jan R. Biasi
π π»
OtΓ‘vio Augusto Soares
π
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
[ci]: https://github.com/toomuchdesign/next-page-tester/actions/workflows/ci.yml
[ci-badge]: https://github.com/toomuchdesign/next-page-tester/actions/workflows/ci.yml/badge.svg
[npm]: https://www.npmjs.com/package/next-page-tester
[npm-badge]: https://img.shields.io/npm/v/next-page-tester.svg
[coveralls-badge]: https://coveralls.io/repos/github/toomuchdesign/next-page-tester/badge.svg?branch=master
[coveralls]: https://coveralls.io/github/toomuchdesign/next-page-tester?branch=master
[next-github]: https://nextjs.org/
[req-docs]: https://nodejs.org/api/http.html#http_class_http_clientrequest
[res-docs]: https://nodejs.org/api/http.html#http_class_http_serverresponse
[node-mocks-http]: https://www.npmjs.com/package/node-mocks-http
[next-docs-routing]: https://nextjs.org/docs/routing/introduction
[next-docs-data-fetching]: https://nextjs.org/docs/basic-features/data-fetching
[next-docs-router]: https://nextjs.org/docs/api-reference/next/router
[next-docs-link]: https://nextjs.org/docs/api-reference/next/link
[next-docs-runtime-config]: https://nextjs.org/docs/api-reference/next.config.js/runtime-configuration
[next-docs-head]: https://nextjs.org/docs/api-reference/next/head
[next-docs-custom-app]: https://nextjs.org/docs/advanced-features/custom-app
[next-docs-custom-document]: https://nextjs.org/docs/advanced-features/custom-document
[next-docs-env-vars]: https://nextjs.org/docs/basic-features/environment-variables
[next-gh-strict-bug]: https://github.com/vercel/next.js/issues/16219
[error-log-mock]: src/**tests**/use-document/use-document.test.tsx#L8
[examples-folder]: examples