npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

qubic-test

v0.0.2

Published

Enable DOM integration testing on Next.js pages

Downloads

5

Readme

Next page tester

Build status Test coverage report Npm version

The missing DOM integration testing tool for Next.js.

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 and data fetching methods.

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

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

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/head, next/link, next/config and environment variables

API

getPage

getPage accepts an option object and returns 4 values:

import { getPage } from 'next-page-tester';

const { render, serverRender, serverRenderToString, page } = await getPage({
  options,
});

render()

Type: () => { nextRoot: HTMLElement<NextRoot> } 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<NextRoot> } 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<AppElement>

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 => req | - | | res | Enhance default mocked response object | res => res | - | | router | Enhance default mocked Next router object | router => router | - | | useApp | Render custom App component | boolean | true | | ~useDocument~ (experimental. Temporarily disabled due to this issue) | Render Document component | boolean | false | | nextRoot | Absolute path to Next.js root folder | string | auto detected | | dotenvFile | Relative path to a .env file holding environment variables | string | - | | wrappers | Absolute path to wrappers file. 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.

Setup JSDOM environment

next-page-tester expects to run into a JSDOM environment. If using Jest add this line to your jest configuration:

"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 like so:

cross-env NPT_SKIP_AUTO_SETUP=true jest

Optional: patching Jest v26

If using Jest v26 you might need to patch it in order to load modules with proper server/client environments. Maintenance efforts will target latest Jest version.

Examples

Under 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 + | |

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

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 and Mirage JS.

Another viable approach might consist of mocking the global fetch object with libraries like 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.

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.

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 or provide your own window.scrollTo mock.

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):

This project follows the all-contributors specification. Contributions of any kind welcome!