Next.js + Jest + React Testing Library

This is a cheat sheet repo for Next.js + Jest + React Testing Library. Each page is a different topic

Note: Check this page for a quick cheat sheet from the official react testing library docs

How to use

clone this repo and cd into it
run npm install to install dependencies
run npm test to run tests

Create a new Next.js app with Jest and React Testing Library

run mkdir followed by the name of your project and cd into it, then:

npx create-next-app --example with-jest .

make sure to remove the __tests__ folder if already there to clear the example tests
clear the pages/index.js boilerplate code
remove .git folder if you want to start fresh: rm -rf .git
initialize a new git repo: git init (npm test will fail if you don't do this)
run npm test to make sure everything is working

Configure eslint with Jest and React Testing Library

Note: For this to work you should already have eslint installed and configured in your project byt choosing it during the create-next-app setup

install eslint plugins for jest and react-testing-library:

npm install --save-dev eslint-plugin-testing-library eslint-plugin-jest-dom

add the following to your .eslintrc file:

{
  "plugins": ["testing-library", "jest-dom"],
  "extends": ["plugin:testing-library/react"]
}

Note: Check the .eslintrc.json file in this repo for a full example

be sure to have this rule on your settings.json file in vscode:

"editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  }

Note: You can either put this on your global settings or on your project settings by adding a .vscode folder to your project and adding a settings.json file inside it

Run Jest Tests

npm test

Jest commands

jest --watch - run tests in watch mode
jest --watchAll - run all tests in watch mode
jest - run all tests and exit
jest --coverage - run tests with coverage report
jest --watch --coverage - run tests in watch mode with coverage report

Jest watch mode commands

f - run only failed tests
o - run only tests related to changed files
p - filter by a filename regex pattern
t - filter by a test name regex pattern
q - quit watch mode
Enter - trigger a test run
a - run all tests

Jest test.only() and test.skip()

test.only() - run only this test
test.skip() - skip this test

Example:

test.only('should render...', () => {
  // ...
})

How does Jest watch mode work?

Jest will run all tests that have changed since the last commit. If you want to run all tests, you can press a to run all tests.
When a file is saved or a test file is changed, Jest will re-run the tests

Note: If there are no changes since the last commit, no tests will run.

TDD (Test Driven Development)

Write tests before writing code
Write the minimum amount of code to make the tests pass
Refactor code as needed

Note: Its is called "red-green" testing because the test initially fails (red) and then passes (green) after the code is written

Why TDD?

You don't need to manually test your code every time you make a change
You can refactor your code with confidence because you have tests to make sure nothing breaks
Writing tests before the code forces you to think about the code you are writing
Writing tests before the code feels part of the process, instead of a "chore" to do at the end

Unit Testing vs Functional Testing

Unit testing - tests individual units of code

Pros	Cons
Mock dependencies	Further from how users interact
Easy to pinpoint failures	More likely to break in refactoring

Functional testing - tests how the app works from the user's perspective

Pros	Cons
Close to how users interact	More difficult to debug
Robust tests

Note: react-testing-library is a functional testing library

render method

import render

import { render } from '@testing-library/react'
import Component from './Component'

use render

render(<Component />)

Testing Library screen methods

import screen

import { screen } from '@testing-library/react'

use screen

const button = screen.getByRole('button')

Commands

e.g. screen.queryByRole('button') - returns a single element

get - expect an element to be in the DOM
query - expect an element not to be in DOM (useful for popovers etc...), returns null if not found
find - expect an element to be in the DOM, but wait for it to appear (useful for async data)

All

e.g. getAllByRole('button') - returns an array of all buttons in the DOM

Add All to the command to return an array of elements

Query Type

e.g. getByRole('button')

ByRole - query by role
ByLabelText - query by label text
ByPlaceholderText - query by placeholder text
ByText - query by text
ByDisplayValue - query by display value
ByAltText - query by alt text
ByTitle - query by title
ByTestId - query by test id

Testing Library Order of Priority

Testing Library suggest to follow accessibility guidelines when writing tests. This means that you should use the following order of priority when querying the DOM:

getByRole('button', { name: /click me/i })
getByLabelText('First Name')
getByPlaceholderText('Enter your first name')
getByText('Click me')
getByDisplayValue('John')
getByAltText('Profile picture')
getByTitle('Close')
getByTestId('my-element')

Note: You should only use getByTestId as a last resort. Assign data-testid='my-element' to the element that you need to find

Accessibility Roles

alert, alertdialog, application, article, banner, button, checkbox, columnheader, combobox, complementary, contentinfo, definition, dialog, directory, document, form, grid, gridcell, group, heading, img, link, list, listbox, listitem, log, main, marquee, math, menu, menubar, menuitem, menuitemcheckbox, menuitemradio, navigation, none, note, option, presentation, progressbar, radio, radiogroup, region, row, rowgroup, rowheader, scrollbar, search, searchbox, separator, slider, spinbutton, status, tab, tablist, tabpanel, textbox, timer, toolbar, tooltip, tree, treegrid, treeitem

js-dom Custom Matchers

See: https://github.com/testing-library/jest-dom

toBeDisabled
toBeEnabled
toBeEmptyDOMElement
toBeInTheDocument
toBeInvalid
toBeRequired
toBeValid
toBeVisible
toContainElement
toContainHTML
toHaveAccessibleDescription
toHaveAccessibleName
toHaveAttribute
toHaveClass
toHaveFocus
toHaveFormValues
toHaveStyle
toHaveTextContent
toHaveValue
toHaveDisplayValue
toBeChecked
toBePartiallyChecked
toHaveErrorMessage

userEvent

userEvent is a library that provides a set of utilities to simulate user interactions with the DOM. It is a wrapper around fireEvent that provides a more natural API for interacting with the DOM.

Note: userEvent always returns a Promise, so you must use await with it

userEvent Usage

// ... other imports
import userEvent from '@testing-library/user-event'

describe('Component', () => {
  it('should do something', async () => {
    // NOTE: Setup userEvent
    const user = userEvent.setup()

    render(<Component />)
    const button = screen.getByRole('button')

    await user.click(checkbox)
  })
})

Read This for more info: https://testing-library.com/docs/ecosystem-user-event/

userEvent methods

userEvent.click(element) - click an element
userEvent.hover(element) - hover over an element
userEvent.unhover(element) - unhover over an element
userEvent.type(element, text) - type text into an element
userEvent.clear(element) - clear text from an input or textarea
userEvent.selectOptions(element, values) - select options in a select element
userEvent.upload(element, fileOrFiles) - upload a file or files to an element
userEvent.tab() - tab to the next focusable element
userEvent.keyboard(text) - type text using the keyboard

Mock Service Worker

Mock Service Worker (MSW) is a service worker based library that allows you to intercept network requests and mock responses.

Install

See: https://mswjs.io/docs/getting-started/install

npm install msw --save-dev

Setup

See: https://mswjs.io/docs/getting-started/integrate/node

Add the following to jest.setup.js

import { server } from './mocks/server'
// Establish API mocking before all tests.
beforeAll(() => server.listen())

// Reset any request handlers that we may add during the tests,
// so they don't affect other tests.
afterEach(() => server.resetHandlers())

// Clean up after the tests are finished.
afterAll(() => server.close())

// TIP: This file is similar to setupTests.js from create-react-ap

Note: Make sure to have imported jest.setup.js in jest.config.js like so setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],

Usage

See: https://mswjs.io/docs/getting-started/mocks/rest-api

Create a mocks folder in the root of your project
Create a server.js file in the mocks folder
Add the following to server.js

import { setupServer } from 'msw/node'
import { handlers } from './handlers'

// This configures a request mocking server with the given request handlers.
export const server = setupServer(...handlers)

Create a handlers.js file in the mocks folder
Add the following to handlers.js

import { rest } from 'msw'
import { apiURL } from '@/config'

export const handlers = [
  rest.get(`${apiURL}/scoops`, (req, res, ctx) => {
    return res(
      ctx.json([
        { name: 'Chocolate', imagePath: '/images/chocolate.png' },
        { name: 'Vanilla', imagePath: '/images/vanilla.png' },
      ])
    )
  }),
  // ... other handlers
]

Now you can get fetched data from your mock server in your test files by using await and findBy* queries

import { render, screen } from '@testing-library/react'
import Options from './Options'

test('my test', async () => {
  render(<Options optionType='scoops' />)

  const scoopImages = await screen.findAllByRole('img', { name: /scoop$/i })
  expect(scoopImages).toHaveLength(2)

  const altTextArray = scoopImages.map((element: any) => element.alt)
  expect(altTextArray).toEqual(['Chocolate scoop', 'Vanilla scoop'])
})

HOW DOES IT WORK? When we run the test, if the component makes a request to the server, the request will be intercepted by Mock Service Worker (that we setup in jest.setup.js) and it will check if there is a handler for that same request (same url). IF there is, the mock request will be used instead of the real request

Simulate Server Error Response

use server.resetHandlers() to setup a new behavior (e.g. return an error) for a route

import { render, screen, waitFor } from '@testing-library/react'
import { rest } from 'msw'
import { server } from '@/mocks/server'
import { apiURL } from '@/config'
import Component from './Component'

test('test error', async () => {
  // setup the server to return an error for this route
  server.resetHandlers(
    rest.get(`${apiURL}/scoops`, (req, res, ctx) => {
      return res(ctx.status(500))
    })
  )

  render(<Component />)

  // wait for the error message to show up
  await waitFor(async () => {
    const alerts = await screen.findAllByRole('alert')
    expect(alerts).toHaveLength(1)
  })
})

Note: See Mock Service Worker section on this page for more info on how to setup the server

TIP: you still need to add the error handling logic in your component

Test components wrapped in a Provider (context)

To test components that are children of a Provider (components that use context) you need to wrap them with your Provider in your test file during rendering:

render(<Component />, {
  wrapper: MyProvider,
  ...options,
})

Note: Since you would need to do so in every test file, it's better to create a custom render function that does this for you. See test-utils.tsx file in this project for an example

Create a custom render function with wrapped context

See: https://testing-library.com/docs/react-testing-library/setup

Create a test-utils.tsx file in the root of your project or in the src folder

import { render } from '@testing-library/react'
import { OrderDetailsProvider } from '@/contexts/OrderDetails'

const renderWithContext = (ui: any, options?: any) =>
  render(ui, {
    wrapper: OrderDetailsProvider,
    ...options,
  })

// re-export everything
export * from '@testing-library/react'

// override render method with render with context
export { renderWithContext as render }

Now you can import your custom render function in your test files:

// NOTE: you don't need to import render from @testing-library/react anymore
import { render, screen, waitFor } from '@/test-utils'

test('test', () => {
  render(<Component />)

  // ...
})

Note: As you can see the only thing you need to do is to import your custom render function in @/test-utils instead of the one from @testing-library/react

Note: You can also add other providers to your custom render function

Debugging Tips

Use debug() to log the html of the component to the console

import { render, screen } from '@testing-library/react'

test('test', async () => {
  render(<Component />)

  // log the html of the component to the console
  screen.debug()

  // ...
})

Use logRoles(container) to log the roles of the elements in the container to the console

import { render, screen, logRoles } from '@testing-library/react'

test('test', async () => {
  const { container }render(<Component />)

  // log the roles of the elements in the container to the console
  logRoles(container)

  // ...
})

Use console.log() to log the html of the component to the console

import { render, screen } from '@testing-library/react'

test('test', async () => {
  render(<Component />)

  // log the html of the component to the console
  console.log(screen.getByRole('alert'))

  // ...
})

If getBy* fail than it is likely that the element is not rendered yet. Use findBy* instead
userEvent methods always need await
Use test.only() and test.skip() to run only one test or skip a test
Prevent act()... warning from showing up in the test console by using unmount

test('test', async () => {
  const { unmount } = render(<Component />)

  // ...

  unmount()
})

jest.mock()

Use jest.mock() to mock features and avoid errors when running tests

For example, jest.mock() can be used to mock props that are passed to a component

<Component prop={jest.fn()} />

Note: jest.mock() doesn't actually do anything. It just tells jest to mock the prop to avoid errors

Another instance is when mocking modules such as next/router

import { useRouter } from 'next/router'

jest.mock('next/router', () => ({
  useRouter: jest.fn(),
}))

Note: This will prevent errors related to useRouter not being available in the test environment

Resources

Next.js Testing
Testing Library Cheat Sheet
userEvent
Testing Library Queries
Testing Library Order of Priority
w3c Accessibility Roles
getByTestId
Mock Service Worker

License

MIT

Go To Top ⬆️

Files

README.md

Latest commit

History