Migrating to Vitest from Jest

A Straightforward Process

Migrating to Vitest from Jest is pretty straight forward as Vitest retains much of Jest’s API.

Here is a broad outline of the steps you’ll need to follow:

Replace Jest Mocks & Functions

1. jest.fn() ➡️ vi.fn().
2. jest.mock() ➡️ vi.mock().
3. jest.mocked() ➡️ vi.mocked().
4. jest.requireActual() ➡️ vi.importActual().
5. jest.clearAllMocks() ➡️ vi.clearAllMocks().

Add Necessary Imports

1
import { vi } from "vitest";
2
import "@testing-library/jest-dom/vitest";

Errors You May Encounter

Global Matchers

This was the first error I encountered after making the above replacements.

Bah, humbug. Unlike Jest, Vitest does not export its matchers globally and we need update the vitest.config, per the official documentation. I should reference [[New Project Setup#Vitest]].

By default, vitest does not provide global APIs for explicitness. If you prefer to use the APIs globally like Jest, you can pass the --globals option to CLI or add globals: true in the config.

Configuring Vitest

1
import { defineConfig } from 'vitest/config';
2

3
export default defineConfig({
4
  test: {
5
    ...
6
    globals: true,
7
  },
8
});

Custom Window Object

The error occurs because our app extends the global window object with custom properties. To fix this, we need to override the window object in the test environment. This issue isn’t specific to Vitest, we make the same accommodation for Jest. The solution:

1
...
2

3
declare global {
4
  interface Window {
5
    CONQA_CONFIG: ReturnType<typeof config.getProperties>;
6
  }
7
}
8

9
window.CONQA_CONFIG = config.getProperties();
10

11
...

Interesting Observations

No act() Wrapping Needed

I found that migrating to Vitest allowed me to remove all the unnecessary wrapping of user events with act. I am not entirely sure why this worked.

It’s surprising because, based on a quick Google search, migrating to Vitest should have caused more act() warnings.

React Testing Library checks if the IS_REACT_ACT_ENVIRONMENT flag is set on the global self object. If it’s true, it suppresses act() warnings; if not, the warnings show up.

Explicitly Mocks For Default Exports

I had to update mocking of the react-hot-toast library to explicitly mock the default export.

When mocking a module in Jest, the factory argument’s return value is the default export. In Vitest, the factory argument has to return an object with each export explicitly defined. For example, the following jest.mock would have to be updated as follows:

Module Mocks

1
jest.mock("./some-path", () => "hello");
2

3
vi.mock("./some-path", () => ({
4
  default: "hello",
5
}));

Ignore Polyfilling Fetch

Since both Jest and Vitest run in Node and we’re using Node 18 for the project, I realised I can remove whatwg-fetch as a test dependency.

JSX Exports To Have Proper Extension

I got errors for components importing JSX from .js or .ts files.

1
Error: Failed to parse source for import analysis because the content contains invalid JS syntax. If you are using JSX, make sure to name the file with the .jsx or .tsx extension.
2
  Plugin: vite:import-analysis
3
  File: /Users/jackwilliammorris/Code/conqa/explorer/src/components/LoadingSpinner/LoadingSpinner.js:12:21
4
  10 |      style={style}
5
  11 |    >
6
  12 |      <p>{message}</p>
7
     |                      ^
8
  13 |      <Spinner size={5} className="tw-mt-2 tw-inline-block" />
9
  14 |    </div>

While Vitest uses Vite under the hood, Jest doesn’t. This means the test runners use different strategies for resolving imports, with Vitest seeming to be a little more opinionated than Jest.

The issue was valid and fixing it was as simple as adding the correct file extension.

AWS SDK Mocking

I got this error for components that were using the aws-sdk-client-mock.

1
 FAIL  src/settings/components/User/tests/UserMfaStatus.test.tsx > UserMfaStatus > should call GetUserCommand with correct parameters
2
Error: Invalid Chai property: toHaveReceived. Did you mean "toHaveResolved"?

Specifically, for this code:

1
await waitFor(() => {
2
  expect(cognitoMock).toHaveReceivedCommandWith(GetUserCommand, {
3
    AccessToken: TEST_ACCESS_TOKEN,
4
  });
5
});

The aws-sdk-client-mock adds its own custom matchers that extend upon the Jest matcher API. However, we are no longer using Jest. And although Vitest is largely Jest consistent, the custom matcher needs to be explicitly added to Vitests expect API.

I found that there is a separate package for Vitest matchers called aws-sdk-client-mock-vitest

1
import { expect } from "vitest";
2
import { allCustomMatcher } from "aws-sdk-client-mock-vitest";
3

4
expect.extend(allCustomMatcher);