joshuakgoldberg / mock-react-redux

Mocks out Redux actions and selectors for clean React Jest tests. 🎭

🎭 mock-react-redux

Mocks out Redux actions and selectors for clean React Jest tests.

Tired of setting up, updating, and debugging through complex Redux states in your React tests? Use this package if you'd like your React component tests to not take dependencies on your full Redux store.

See FAQs for more backing information. 📚

Usage

import { mockReactRedux } from "mock-react-redux";

mock-react-redux stubs out connect and the two common Redux hooks used with React components. Call mockReactRedux() before your render/mount logic in each test.

Mocking State

mockReactRedux().state({
  title: "Hooray!",
});

Sets a root state to be passed to your component's selectors.

it("displays the title when there is a title", () => {
  mockReactRedux().state({
    title: "Hooray!",
  });

  // state => state.title
  const view = render(<RendersTitle />);

  view.getByText("Hooray!");
});

See Selectors for more documentation or Heading for a code example.

Mocking Selectors

mockReactRedux()
  .give(valueSelector, "Hooray!")
  .giveMock(fancySelector, jest.fn().mockReturnValueOnce("Just the once."));

Provide results to the useSelector function for individual selectors passed to it. These work similarly to Jest mocks: .give takes in the return value that will always be passed to the selector.

it("displays the title when there is a title", () => {
  mockReactRedux().give(selectTitle, "Hooray!");

  // state => state.title
  const view = render(<RendersTitle />);

  view.getByText("Hooray!");
});

If you'd like more control over the return values, you can use .giveMock to provide a Jest mock.

See Selectors for more documentation or Heading for a code example.

Dispatch Spies

const { dispatch } = mockReactRedux();

The dispatch function returned by useDispatch will be replaced by a jest.fn() spy. You can then assert against it as with any Jest mock in your tests:

it("dispatches the pageLoaded action when rendered", () => {
  const { dispatch } = mockReactRedux();

  // dispatch(pageLoaded())
  render(<DispatchesPageLoaded />);

  expect(dispatch).toHaveBeenCalledWith(pageLoaded());
});

See Dispatches for more documentation or Clicker for a code example.

Gotchas

• The first mock-react-redux import must come before the first react-redux import in your test files.
• .give and .giveMock will only apply when selectors are passed directly to useSelector (e.g. useSelector(selectValue)).
  • See FAQs for more tips and tricks.
• Thunks often create new functions per dispatch that make toBeCalledWith-style checks difficult. See the Thunks docs for details.

Hybrid Usage

You don't have to use mock-react-redux in every test file in your repository. Only the test files that import mock-react-redux will have react-redux stubbed out.

TypeScript Usage

mock-react-redux is written in TypeScript and generally type safe.

• mockReactRedux() has an optional <State> type which sets the type of the root state passed to .state.
• .give return values must match the return types of their selectors.
• .giveMock mocks must match the return types of their selectors.

Heck yes. 🤘

Development

Requires:

• Node.js >12
• Yarn

After forking the repo from GitHub:

git clone https://github.com/<your-name-here>/mock-react-redux
cd mock-react-redux
yarn

Contribution Guidelines

We'd love to have you contribute! Check the issue tracker for issues labeled accepting prs to find bug fixes and feature requests the community can work on. If this is your first time working with this code, the good first issue label indicates good introductory issues.

Please note that this project is released with a Contributor Covenant. By participating in this project you agree to abide by its terms. See CODE_OF_CONDUCT.md.