❀Nautical Pirate Moustache
    Wondering what’s next for npm?Check out our public roadmap! Β»

    next-page-tester
    TypeScript icon, indicating that this package has built-in type declarations

    0.24.2Β β€’Β PublicΒ β€’Β Published

    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) 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 -
    wrapper Map of render functions. Useful to decorate component tree with mocked providers. { Page?: NextPage => NextPage } -
    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.

    Optional: patch Jest

    Until Jest v27 is published, you might need to patch jest in order to load modules with proper server/client environments. Don't do this until you actually encounter issues.

    1. Install patch-package and follow its setup instructions
    2. If using the last version of jest (26.6.3), copy this patches folder to your project root and run npx patch-package or yarn patch-package.
    3. If using jest < v26.6.3 update manually node_modules/jest-runtime/build/index.js file replicating this commit and run npx patch-package jest-runtime or yarn patch-package jest-runtime

    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

    Examples

    Under examples folder we're documenting the testing cases which next-page-tester enables.

    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.

    Next.js versions support

    next-page-tester focuses on supporting only the last version of Next.js:

    next-page-tester next.js
    v0.1.0 -> v0.7.0 v9.X.X
    v0.8.0 -> v0.22.0 v10.0.0 -> v10.0.7
    v0.23.0 + v10.0.8 +

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


    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

    πŸ›

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

    Install

    npm i next-page-tester

    DownloadsWeekly Downloads

    3,368

    Version

    0.24.2

    License

    ISC

    Unpacked Size

    118 kB

    Total Files

    100

    Last publish

    Collaborators

    • avatar