Mocking Services with Vitest

import { it } from 'vitest';
import { render, screen } from '@testing-library/react';
import App from './App';

it('shows the schedule year', () => {
  render(<App />);
  screen.getByText(/2018-2019/);
});

import React, { useState} from 'react';
import './App.css';

const UserList = ({data}) => (
  !data ? <p>No users loaded</p> :
  data.error ? <p>Error: {data.error}</p> :
  data.loading ? <p>Loading...</p> :
  <ul>
    { data.users.map(user => <li key={user.id}>{user.name}</li>) }
  </ul>
);

const App = () => {
  const [data, setData] = useState(null);

  const fetchData = async () => {
    setData({loading: true});
    try {
      const response = await fetch('https://jsonplaceholder.typicode.com/users');
      if (!response.ok) {
        setData({ error: response.statusText });
      } else {
        const users = await response.json();
        setData({loaded: true, users});
      }
    } catch (e) {
      setData({ error: e.message });
    }
  };

  return (
    <div>
      <h1>Users</h1>
      
      <button onClick={fetchData}>
        Fetch Users
      </button>

      <UserList data={data} />
    </div>
  );
}

export default App;

import { http, HttpResponse } from 'msw';
import { setupServer } from 'msw/node';

const handlers = [
  http.get('https://jsonplaceholder.typicode.com/users', (info) => {
    return HttpResponse.json([
      { "id": 1, "name": "Test user 1" },
      { "id": 2, "name": "Test user 2" }
    ])
  })
];

export const server = setupServer(...handlers);

import {describe, test} from 'vitest';
import {fireEvent, render, screen} from '@testing-library/react';
import { server } from './mocks/server';
import App from './App';

beforeAll(() => server.listen());
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

describe('users load only when requested', () => {
    
  test("no users on launch should be 0 at the start", () => {
    render(<App />);
    screen.getByText(/loading/i);
  });
  
  test("users appear when button clicked", async () => {
    render(<App />);
    const counter = screen.getByRole('button');
    fireEvent.click(counter);
    await screen.findByText(/Test user 1/i);
  });

});

...
import { useData, useUserState }from './firebase';
...
vi.mock('./firebase');
...
const mockSchedule = {
  "title": "CS Courses for 1850-1851",
  "courses": { }
};

When you mock a module, Vitest will replace every exported function with a mock definition that, by default, does nothing and returns undefined. It uses vi.fn() to create an empty mock function for every function exported from the module.

For each test, we can assign specific behavior to the mocked functions. We have to mock every function that is called by the component we are rendering, including functions called by any subcomponents. Otherwise, your code will probably break when it calls a mocked function that returns undefined.

There are many ways to define what a mocked function should do, but the two simplest are:

• Use mocked-function.mockReturnValue(value) to specify the return value of a normal function.
• Use mocked-function.mockResolvedValue(value) to specify the return value for an async function, i.e., a function that returns a promise.

In this case, we want the test shows the schedule year to verify what is rendered when the schedule is first loaded. To do that, we need to specify a return value for useData(). We also need to specify a return value for useUserState() because the app always checks to see if there is a user logged in. We do not need to define values for any other functions in firebase.js because they are not called in the test.

The real useData() returns an array of three values: (1) the schedule, if available, (2) a boolean that is true if the data is still being loaded, and (3) an error object, if something went wrong. Our mock return value must fit that pattern. useData() is not asynchronous, i.e., it does not return a promise, so we use mockReturnValue to specify its behavior

Since we don't need a user for our test, we can define the return value of useUserState() to be null.

it('shows the schedule year', () => {
  useData.mockReturnValue([mockSchedule, false, null]);
  useUserState.mockReturnValue(null);
  render(<App />);
  const title = screen.getByText(/1850-1851/i);
  expect(title).toBeInTheDocument();
};

Note that the unit tests can use getByText() because there is no asynchronous code involved.

Mocking a Firebase store

If your app stores data on Firebase, two things happen. First, a Firebase method such as set() or update() is called. Then your Firebase hook that listens for changes to the data is called and your component re-renders. If you mock the update to Firebase, then there will be no actual to the data, your hook will not be called, and no re-render will occur.

That storing data on Firebase triggers a call to your hook is not something you test. That's Firebase's job. You just need to test that your code is passing the correct data to Firebase, and that when that data is sent from Firebase to your code, the correct data is displayed.

You've already seen how to test the right data is displayed when the database hook is called. To test that the right data is sent to Firebase, you need to mock the Firebase method that sends the data, and then verify that it was called with the right data.

For example, this React sample code defines a hook useDbUpdate() that returns an array of two values: a function to update the database and an object that contains information about the update, such as whether there was an error. So we can mock useDbUpdate() to return another mock function that we can spy on.

Assume that useDbUpdate() is defined in src/firebase.js. Then the basic elements for mocking the update call, and then spying on the results, are as follows:

import { useDbData, useDbUpate } from './firebase.js';
  ...
vi.mock('./firebase.js');
...
const mockUpdate = vi.fn();
useDbUpate.mockReturnValue([mockUpdate, { error: null }]);
...
// some test that causes data to be stored
...
expect(mockUpdate).toHaveBeenCalledTimes(1);
expect(mockUpdate).toHaveBeenCalledWith({ some: 'data' });

This code creates a mock function mockUpdate and assigns it to the return value of useDbUpdate(). The test then verifies that mockUpdate was called once and that it was called with the correct data.

If you have multiple update tests, then you need to reset the mock functions between tests to clear the spy data. You can do this by calling mockReset() on the mock function.

Mocking a logged in user

Most apps require user authentication for certain functionality. They may do different things depending on what role a user has. This kind of code is important to test, but tricky to write and run. We don't want our test code to have user names and passwords in it. We don't want our unit tests to have to wait for an authentication service to process a log in. With mocks, we can simulate having a user with none of these issues.

For example, the Quick, React app shows a Sign In button when no user is logged in, and a Sign Out button when there is a user. The code to do this uses the hook useUserState() defined in ./firebase.js.

const TermSelector = ({term, setTerm}) => {
  const [user] = useUserState();
  return (
    <div>
      ...
      { user ? <SignOutButton /> : <SignInButton /> }
    </div>
  );
};

Let's add tests to verify that the proper buttons appear when a user is and is not logged in. To test for what happens when there is a user, we mock the return value of useUserState() to be a dummy Firebase User object. While there are many properties for the Firebase user object, all the Quick, React app needs is displayName.

it('shows Sign In if not logged in', () => {
  useData.mockReturnValue([mockSchedule, false, null]);
  useUserState.mockReturnValue([null]);
  render(<App />);
  const button = screen.getByText(/Sign In/i);
  expect(button).toBeInTheDocument();
});
  
it('shows Sign Out if logged in', () => {
  useData.mockReturnValue([mockSchedule, false, null]);
  useUserState.mockReturnValue([{ displayName: 'Joe' }]);
  render(<App />);
  const button = screen.getByText(/Sign Out/i);
  expect(button).toBeInTheDocument();
});

Add this test and verify that all the tests pass. Change what it expects and verify that it fails.

If your app has a login screen, be sure that your app skips that if the user is already logged in. Forcing a login when the user is known not only makes testing difficult, it makes the app annoying for real users. The normal way to do this is to have your entry URL go to the login page if there is no user, otherwise it goes to your main content page. Here's an example using React Router,

const [user] = useUserState();
...
<Route exact path="/">
  {user ? <Redirect to="/dashboard" /> : <LoginPage />}
</Route>

Verifying proper calls with spies

So far, we have just used our mock functions as stubs, that simulate getting values from some service. Mocks have another important function: they are spies that record every time they are called. That lets us write unit tests to make sure that our code calls a service correctly, the right number of times, with the right data. Vitest provides several expect() methods to make it easy to test how often a mock function was called and with what arguments.

For example, here is a test to verify that App calls useData() once, when rendered, and when it does, it passes the string '/schedule' and some function.

it('asks for data once with a schedule path', () => {
  useData.mockReturnValue([mockSchedule, false, null]);
  useUserState.mockReturnValue([null]);
  render(<App />);
  expect(useData).toHaveBeenCalledTimes(1);
  expect(useData).toHaveBeenCalledWith('/schedule', expect.any(Function)));
});

As before, we define return values for the two mocked methods and then render App. Instead of looking at what's rendered, we test that useData() was called just once, and that when it was called, it was passed the proper arguments.

Add this test to App.test.jsx. Verify that all the tests pass. Try changing what's expected and verify that it fails.

Resetting mocks

Unit tests should be independent. That means that they can run in any order. No test should depend on another test running first or affect the results of any test running later. Some testing frameworks enforce this by running tests in a random order.

Using mocks to avoid calls to a database helps keep tests independent but the mock operations themselves have side effects. If a mock function is changed or called in a test, that can affect how the same mock behaves in another test.

You can call Vitest functions to clear, reset, or restore all mocks in your test code, but an even simpler thing is to configure Vitest to do this automatically by adding the following to vite.config.js:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  test: {
    globals: true,
    environment: 'jsdom',
    mockReset: true
  }
});

Vitest tips and pitfalls

Tip: While Vitest expect() is very useful, the following test is overkill.

expect(screen.getByText(/welcome/i)).toBeDefined();

To check for the existence of some element, just ask for it.

screen.getByText(/welcome/i);

Pitfall: A test like the following will usually fail.

screen.getByText('welcome');

This test only passes if some item has exactly welcome, no more or less. To look for elements that contain some text, ignoring case, use regular expressions.

screen.getByText(/welcome/i);

Pitfall: The following test will always pass, no matter what's on the page.

screen.findByText(/welcome/i);

That's because findByText() is asynchronous and always returns a promise. You can't tell if it failed unless you await the result.

await screen.findByText(/welcome/i);

Test coverage

An important characteristic of any test suite is code coverage. This measures what percentage of your code has been executed by at least one test. If code coverage is less than 100%, it means there are lines of code that your tests never execute. Unexecuted lines of code can be time bombs, waiting to fail in real use.

Vitest makes it fairly easy to evaluate your test code coverage. First, add the following script to your package.json file.

    "scripts": {
      ...
      "test": "vitest --ui",
      "coverage": "vitest run --coverage",
      ...

The vitest run part says to run Vitest just once, rather than running and waiting for changes. Collecting code coverage data is a slow process so you don't normally do it repeatedly.

Add the following to your vite.config.js file:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  test: {
    globals: true,
    environment: 'jsdom',
    mockReset: true
    coverage: {
      reporter: ['text', 'html'],
    },
  }
});

This tell Vitest to print the code coverage data in the console and also create an interactive HTML file to explore what is and isn't covered.

To get coverage date,

npm run coverage

Vitest will ask if you want to install c8, if it's not already installed. This is a code coverage library that Vitest uses. Say yes.

When it finishes, a table will be printed that summarizes how much code was covered in each component file. Even better, there will be an HTML file in the coverage directory that you can open in a browser to see exactly what pieces of code were and were not executed by the tests.

100% code coverage does not mean you have tested everything. It just means that every line of code was executed at least once. Most code has conditionals. That means that there's more than one possible path through the code. Many bugs only occur when certain paths are taken. Path coverage measures how many of these paths are tested. It's much harder to get 100% path coverage than 100% code coverage.

Final Notes

There's a lot more to unit testing and Vitest. For example, most unit testing should be on components of the app, not the entire app itself. There's an art to writing tests that focus on how the app is used, but aren't so fragile that they break with every small change in the interface. There are many pages on this topic.

There are many other functions to help define mock function behavior. For the above examples, we only needed the Vitest method mockReturnValue(). If the return value depends on the arguments passed to the mocked function, use mockImplementation(). If we need to simulate a sequence of return values, use mockReturnValueOnce(). For more ways to get elements from a page, see types of queries.

Sources

Documentation on how to do this was surprisingly hard to find. Most pages on mocking with Jest or Vitest only show how to mock individual functions and modules that export a single class component. None of that is useful here.

Richard Kotze's Mocking React hooks when unit testing using Jest was particularly helpful for writing this tutorial.