{"componentChunkName":"component---src-templates-docs-js","path":"/docs/testing-recipes.html","result":{"data":{"markdownRemark":{"html":"

Common testing patterns for React components.

\n
\n

Note:

\n

This page assumes you’re using Jest as a test runner. If you use a different test runner, you may need to adjust the API, but the overall shape of the solution will likely be the same. Read more details on setting up a testing environment on the Testing Environments page.

\n
\n

On this page, we will primarily use function components. However, these testing strategies don’t depend on implementation details, and work just as well for class components too.

\n\n
\n

Setup/Teardown

\n

For each test, we usually want to render our React tree to a DOM element that’s attached to document. This is important so that it can receive DOM events. When the test ends, we want to “clean up” and unmount the tree from the document.

\n

A common way to do it is to use a pair of beforeEach and afterEach blocks so that they’ll always run and isolate the effects of a test to itself:

\n
import { unmountComponentAtNode } from \"react-dom\";\n\nlet container = null;\nbeforeEach(() => {\n  // setup a DOM element as a render target\n  container = document.createElement(\"div\");\n  document.body.appendChild(container);\n});\n\nafterEach(() => {\n  // cleanup on exiting\n  unmountComponentAtNode(container);\n  container.remove();\n  container = null;\n});
\n

You may use a different pattern, but keep in mind that we want to execute the cleanup even if a test fails. Otherwise, tests can become “leaky”, and one test can change the behavior of another test. That makes them difficult to debug.

\n
\n

act()

\n

When writing UI tests, tasks like rendering, user events, or data fetching can be considered as “units” of interaction with a user interface. react-dom/test-utils provides a helper called act() that makes sure all updates related to these “units” have been processed and applied to the DOM before you make any assertions:

\n
act(() => {\n  // render components\n});\n// make assertions
\n

This helps make your tests run closer to what real users would experience when using your application. The rest of these examples use act() to make these guarantees.

\n

You might find using act() directly a bit too verbose. To avoid some of the boilerplate, you could use a library like React Testing Library, whose helpers are wrapped with act().

\n
\n

Note:

\n

The name act comes from the Arrange-Act-Assert pattern.

\n
\n
\n

Rendering

\n

Commonly, you might want to test whether a component renders correctly for given props. Consider a simple component that renders a message based on a prop:

\n
// hello.js\n\nimport React from \"react\";\n\nexport default function Hello(props) {\n  if (props.name) {\n    return <h1>Hello, {props.name}!</h1>;\n  } else {\n    return <span>Hey, stranger</span>;\n  }\n}
\n

We can write a test for this component:

\n
// hello.test.js\n\nimport React from \"react\";\nimport { render, unmountComponentAtNode } from \"react-dom\";\nimport { act } from \"react-dom/test-utils\";\n\nimport Hello from \"./hello\";\n\nlet container = null;\nbeforeEach(() => {\n  // setup a DOM element as a render target\n  container = document.createElement(\"div\");\n  document.body.appendChild(container);\n});\n\nafterEach(() => {\n  // cleanup on exiting\n  unmountComponentAtNode(container);\n  container.remove();\n  container = null;\n});\n\nit(\"renders with or without a name\", () => {\n  act(() => {    render(<Hello />, container);  });  expect(container.textContent).toBe(\"Hey, stranger\");\n  act(() => {\n    render(<Hello name=\"Jenny\" />, container);\n  });\n  expect(container.textContent).toBe(\"Hello, Jenny!\");\n\n  act(() => {\n    render(<Hello name=\"Margaret\" />, container);\n  });\n  expect(container.textContent).toBe(\"Hello, Margaret!\");\n});
\n
\n

Data Fetching

\n

Instead of calling real APIs in all your tests, you can mock requests with dummy data. Mocking data fetching with “fake” data prevents flaky tests due to an unavailable backend, and makes them run faster. Note: you may still want to run a subset of tests using an “end-to-end” framework that tells whether the whole app is working together.

\n
// user.js\n\nimport React, { useState, useEffect } from \"react\";\n\nexport default function User(props) {\n  const [user, setUser] = useState(null);\n\n  async function fetchUserData(id) {\n    const response = await fetch(\"/\" + id);\n    setUser(await response.json());\n  }\n\n  useEffect(() => {\n    fetchUserData(props.id);\n  }, [props.id]);\n\n  if (!user) {\n    return \"loading...\";\n  }\n\n  return (\n    <details>\n      <summary>{user.name}</summary>\n      <strong>{user.age}</strong> years old\n      <br />\n      lives in {user.address}\n    </details>\n  );\n}
\n

We can write tests for it:

\n
// user.test.js\n\nimport React from \"react\";\nimport { render, unmountComponentAtNode } from \"react-dom\";\nimport { act } from \"react-dom/test-utils\";\nimport User from \"./user\";\n\nlet container = null;\nbeforeEach(() => {\n  // setup a DOM element as a render target\n  container = document.createElement(\"div\");\n  document.body.appendChild(container);\n});\n\nafterEach(() => {\n  // cleanup on exiting\n  unmountComponentAtNode(container);\n  container.remove();\n  container = null;\n});\n\nit(\"renders user data\", async () => {\n  const fakeUser = {    name: \"Joni Baez\",    age: \"32\",    address: \"123, Charming Avenue\"  };  jest.spyOn(global, \"fetch\").mockImplementation(() =>    Promise.resolve({      json: () => Promise.resolve(fakeUser)    })  );\n  // Use the asynchronous version of act to apply resolved promises\n  await act(async () => {\n    render(<User id=\"123\" />, container);\n  });\n\n  expect(container.querySelector(\"summary\").textContent).toBe(fakeUser.name);\n  expect(container.querySelector(\"strong\").textContent).toBe(fakeUser.age);\n  expect(container.textContent).toContain(fakeUser.address);\n\n  // remove the mock to ensure tests are completely isolated  global.fetch.mockRestore();});
\n
\n

Mocking Modules

\n

Some modules might not work well inside a testing environment, or may not be as essential to the test itself. Mocking out these modules with dummy replacements can make it easier to write tests for your own code.

\n

Consider a Contact component that embeds a third-party GoogleMap component:

\n
// map.js\n\nimport React from \"react\";\n\nimport { LoadScript, GoogleMap } from \"react-google-maps\";\nexport default function Map(props) {\n  return (\n    <LoadScript id=\"script-loader\" googleMapsApiKey=\"YOUR_API_KEY\">\n      <GoogleMap id=\"example-map\" center={props.center} />\n    </LoadScript>\n  );\n}\n\n// contact.js\n\nimport React from \"react\";\nimport Map from \"./map\";\n\nexport default function Contact(props) {\n  return (\n    <div>\n      <address>\n        Contact {props.name} via{\" \"}\n        <a data-testid=\"email\" href={\"mailto:\" + props.email}>\n          email\n        </a>\n        or on their <a data-testid=\"site\" href={props.site}>\n          website\n        </a>.\n      </address>\n      <Map center={props.center} />\n    </div>\n  );\n}
\n

If we don’t want to load this component in our tests, we can mock out the dependency itself to a dummy component, and run our tests:

\n
// contact.test.js\n\nimport React from \"react\";\nimport { render, unmountComponentAtNode } from \"react-dom\";\nimport { act } from \"react-dom/test-utils\";\n\nimport Contact from \"./contact\";\nimport MockedMap from \"./map\";\n\njest.mock(\"./map\", () => {  return function DummyMap(props) {    return (      <div data-testid=\"map\">        {props.center.lat}:{props.center.long}      </div>    );  };});\nlet container = null;\nbeforeEach(() => {\n  // setup a DOM element as a render target\n  container = document.createElement(\"div\");\n  document.body.appendChild(container);\n});\n\nafterEach(() => {\n  // cleanup on exiting\n  unmountComponentAtNode(container);\n  container.remove();\n  container = null;\n});\n\nit(\"should render contact information\", () => {\n  const center = { lat: 0, long: 0 };\n  act(() => {\n    render(\n      <Contact\n        name=\"Joni Baez\"\n        email=\"test@example.com\"\n        site=\"http://test.com\"\n        center={center}\n      />,\n      container\n    );\n  });\n\n  expect(\n    container.querySelector(\"[data-testid='email']\").getAttribute(\"href\")\n  ).toEqual(\"mailto:test@example.com\");\n\n  expect(\n    container.querySelector('[data-testid=\"site\"]').getAttribute(\"href\")\n  ).toEqual(\"http://test.com\");\n\n  expect(container.querySelector('[data-testid=\"map\"]').textContent).toEqual(\n    \"0:0\"\n  );\n});
\n
\n

Events

\n

We recommend dispatching real DOM events on DOM elements, and then asserting on the result. Consider a Toggle component:

\n
// toggle.js\n\nimport React, { useState } from \"react\";\n\nexport default function Toggle(props) {\n  const [state, setState] = useState(false);\n  return (\n    <button\n      onClick={() => {\n        setState(previousState => !previousState);\n        props.onChange(!state);\n      }}\n      data-testid=\"toggle\"\n    >\n      {state === true ? \"Turn off\" : \"Turn on\"}\n    </button>\n  );\n}
\n

We could write tests for it:

\n
// toggle.test.js\n\nimport React from \"react\";\nimport { render, unmountComponentAtNode } from \"react-dom\";\nimport { act } from \"react-dom/test-utils\";\n\nimport Toggle from \"./toggle\";\n\nlet container = null;\nbeforeEach(() => {\n  // setup a DOM element as a render target\n  container = document.createElement(\"div\");\n  // container *must* be attached to document so events work correctly.  document.body.appendChild(container);});\n\nafterEach(() => {\n  // cleanup on exiting\n  unmountComponentAtNode(container);\n  container.remove();\n  container = null;\n});\n\nit(\"changes value when clicked\", () => {\n  const onChange = jest.fn();\n  act(() => {\n    render(<Toggle onChange={onChange} />, container);\n  });\n\n  // get ahold of the button element, and trigger some clicks on it\n  const button = document.querySelector(\"[data-testid=toggle]\");\n  expect(button.innerHTML).toBe(\"Turn on\");\n\n  act(() => {\n    button.dispatchEvent(new MouseEvent(\"click\", { bubbles: true }));  });\n\n  expect(onChange).toHaveBeenCalledTimes(1);\n  expect(button.innerHTML).toBe(\"Turn off\");\n\n  act(() => {\n    for (let i = 0; i < 5; i++) {\n      button.dispatchEvent(new MouseEvent(\"click\", { bubbles: true }));    }\n  });\n\n  expect(onChange).toHaveBeenCalledTimes(6);\n  expect(button.innerHTML).toBe(\"Turn on\");\n});
\n

Different DOM events and their properties are described in MDN. Note that you need to pass { bubbles: true } in each event you create for it to reach the React listener because React automatically delegates events to the document.

\n
\n

Note:

\n

React Testing Library offers a more concise helper for firing events.

\n
\n
\n

Timers

\n

Your code might use timer-based functions like setTimeout to schedule more work in the future. In this example, a multiple choice panel waits for a selection and advances, timing out if a selection isn’t made in 5 seconds:

\n
// card.js\n\nimport React, { useEffect } from \"react\";\n\nexport default function Card(props) {\n  useEffect(() => {\n    const timeoutID = setTimeout(() => {\n      props.onSelect(null);\n    }, 5000);\n    return () => {\n      clearTimeout(timeoutID);\n    };\n  }, [props.onSelect]);\n\n  return [1, 2, 3, 4].map(choice => (\n    <button\n      key={choice}\n      data-testid={choice}\n      onClick={() => props.onSelect(choice)}\n    >\n      {choice}\n    </button>\n  ));\n}
\n

We can write tests for this component by leveraging Jest’s timer mocks, and testing the different states it can be in.

\n
// card.test.js\n\nimport React from \"react\";\nimport { render, unmountComponentAtNode } from \"react-dom\";\nimport { act } from \"react-dom/test-utils\";\n\nimport Card from \"./card\";\njest.useFakeTimers();\n\nlet container = null;\nbeforeEach(() => {\n  // setup a DOM element as a render target\n  container = document.createElement(\"div\");\n  document.body.appendChild(container);\n});\n\nafterEach(() => {\n  // cleanup on exiting\n  unmountComponentAtNode(container);\n  container.remove();\n  container = null;\n});\n\nit(\"should select null after timing out\", () => {\n  const onSelect = jest.fn();\n  act(() => {\n    render(<Card onSelect={onSelect} />, container);\n  });\n\n  // move ahead in time by 100ms  act(() => {\n    jest.advanceTimersByTime(100);\n  });\n  expect(onSelect).not.toHaveBeenCalled();\n\n  // and then move ahead by 5 seconds  act(() => {\n    jest.advanceTimersByTime(5000);\n  });\n  expect(onSelect).toHaveBeenCalledWith(null);\n});\n\nit(\"should cleanup on being removed\", () => {\n  const onSelect = jest.fn();\n  act(() => {\n    render(<Card onSelect={onSelect} />, container);\n  });\n  act(() => {\n    jest.advanceTimersByTime(100);\n  });\n  expect(onSelect).not.toHaveBeenCalled();\n\n  // unmount the app\n  act(() => {\n    render(null, container);\n  });\n  act(() => {\n    jest.advanceTimersByTime(5000);\n  });\n  expect(onSelect).not.toHaveBeenCalled();\n});\n\nit(\"should accept selections\", () => {\n  const onSelect = jest.fn();\n  act(() => {\n    render(<Card onSelect={onSelect} />, container);\n  });\n\n  act(() => {\n    container\n      .querySelector(\"[data-testid='2']\")\n      .dispatchEvent(new MouseEvent(\"click\", { bubbles: true }));\n  });\n\n  expect(onSelect).toHaveBeenCalledWith(2);\n});
\n

You can use fake timers only in some tests. Above, we enabled them by calling jest.useFakeTimers(). The main advantage they provide is that your test doesn’t actually have to wait five seconds to execute, and you also didn’t need to make the component code more convoluted just for testing.

\n
\n

Snapshot Testing

\n

Frameworks like Jest also let you save “snapshots” of data with toMatchSnapshot / toMatchInlineSnapshot. With these, we can “save” the rendered component output and ensure that a change to it has to be explicitly committed as a change to the snapshot.

\n

In this example, we render a component and format the rendered HTML with the pretty package, before saving it as an inline snapshot:

\n
// hello.test.js, again\n\nimport React from \"react\";\nimport { render, unmountComponentAtNode } from \"react-dom\";\nimport { act } from \"react-dom/test-utils\";\nimport pretty from \"pretty\";\n\nimport Hello from \"./hello\";\n\nlet container = null;\nbeforeEach(() => {\n  // setup a DOM element as a render target\n  container = document.createElement(\"div\");\n  document.body.appendChild(container);\n});\n\nafterEach(() => {\n  // cleanup on exiting\n  unmountComponentAtNode(container);\n  container.remove();\n  container = null;\n});\n\nit(\"should render a greeting\", () => {\n  act(() => {\n    render(<Hello />, container);\n  });\n\n  expect(    pretty(container.innerHTML)  ).toMatchInlineSnapshot(); /* ... gets filled automatically by jest ... */\n  act(() => {\n    render(<Hello name=\"Jenny\" />, container);\n  });\n\n  expect(\n    pretty(container.innerHTML)\n  ).toMatchInlineSnapshot(); /* ... gets filled automatically by jest ... */\n\n  act(() => {\n    render(<Hello name=\"Margaret\" />, container);\n  });\n\n  expect(\n    pretty(container.innerHTML)\n  ).toMatchInlineSnapshot(); /* ... gets filled automatically by jest ... */\n});
\n

It’s typically better to make more specific assertions than to use snapshots. These kinds of tests include implementation details so they break easily, and teams can get desensitized to snapshot breakages. Selectively mocking some child components can help reduce the size of snapshots and keep them readable for the code review.

\n
\n

Multiple Renderers

\n

In rare cases, you may be running a test on a component that uses multiple renderers. For example, you may be running snapshot tests on a component with react-test-renderer, that internally uses ReactDOM.render inside a child component to render some content. In this scenario, you can wrap updates with act()s corresponding to their renderers.

\n
import { act as domAct } from \"react-dom/test-utils\";\nimport { act as testAct, create } from \"react-test-renderer\";\n// ...\nlet root;\ndomAct(() => {\n  testAct(() => {\n    root = create(<App />);\n  });\n});\nexpect(root).toMatchSnapshot();
\n
\n

Something Missing?

\n

If some common scenario is not covered, please let us know on the issue tracker for the documentation website.

","frontmatter":{"title":"Testing Recipes","next":"testing-environments.html","prev":"testing.html"},"fields":{"path":"content/docs/testing-recipes.md","slug":"docs/testing-recipes.html"}}},"pageContext":{"slug":"docs/testing-recipes.html"}},"staticQueryHashes":[]}