Are you looking to migrate from Jest to Vitest for your React application? Look no further.
I recently migrated the OpenSauced app repository to Vitest. Here's the pull request if you're interested.
chore: migrated to vitest #2296
Description
As discussed on Slack, we're moving to vitest.
What type of PR is this? (check all applicable)
- [ ] π Feature
- [ ] π Bug Fix
- [ ] π Documentation Update
- [ ] π¨ Style
- [x] π§βπ» Code Refactor
- [ ] π₯ Performance Improvements
- [ ] β Test
- [ ] π€ Build
- [ ] π CI
- [x] π¦ Chore (Release)
- [ ] β© Revert
Related Tickets & Documents
Close #2297
Mobile & Desktop Screenshots/Recordings
Steps to QA
The test should pass as we're just moving to another testing framework.
Added to documentation?
- [ ] π README.md
- [ ] π docs.opensauced.pizza
- [ ] π dev.to/opensauced
- [ ] π storybook
- [x] π no documentation needed
[optional] Are there any post-deployment tasks we need to perform?
[optional] What gif best describes this PR or how it makes you feel?
Why move from Jest to Vitest?
Both Jest and Vitest are great testing frameworks, so why bother switching?
Vitest supports ECMAScript modules (ESM), TypeScript out of the box.
Jest requires additional setup for both, although there is experimental support for ESM.
Vitest is also fast. Yes, it depends, but in general, it's faster. (See the Vitest comparison with other test runners)
If you're already using Vite in your project or the meta-framework you're using is based on Vite, using Vitest is a no-brainer as you're already in the Vite ecosystem.
If your project isn't using Vite, e.g. Next.js, it's still a great move.
Vitest makes it effortless to migrate from Jest. It supports the same Jasmine like API.
TLDR; You don't need to update existing tests, as itβs mostly a drop-in replacement for Jest.
Some other niceties are a default watch mode care of Vite instant Hot Module Reload (HMR).
Install Vitest
The first thing you want to do is install Vitest.
vitest-dev / vitest
Next generation testing framework powered by Vite.
Vitest
Next generation testing framework powered by Vite
Documentation | Getting Started | Examples | Why Vitest?
Features
- Vite's config, transformers, resolvers, and plugins. Use the same setup from your app!
- Jest Snapshot
- Chai built-in for assertions, with Jest expect compatible APIs
- Smart & instant watch mode, like HMR for tests!
-
Native code coverage via
v8
oristanbul
. - Tinyspy built-in for mocking, stubbing, and spies.
- JSDOM and happy-dom for DOM and browser API mocking
- Browser Mode for running component tests in the browser
- Components testing (Vue, React, Svelte, Lit, Marko)
- Workers multi-threading via Tinypool (a lightweight fork of Piscina)
- Benchmarking support with Tinybench
- Workspace support
- expect-type for type-level testing
- ESM first, top level await
- Out-of-box TypeScript / JSX support
- Filtering, timeouts, concurrent for suite and tests
- Sharding support
- Run your tests in the browser natively (experimental)
Vitestβ¦
Run npm install vitest -D
in the terminal to install Vitest as a dev dependency.
Next up, create a vitest.config.ts
file in the root of your project. Even if you're not using TypeScript, name it vitest.config.ts
.
In that file, add the following code and save it.
import { defineConfig } from "vite";
// https://vitejs.dev/config/
export default defineConfig({
test: {
// some paths to the files that are test files
include: ["./**/*.test.ts", "./**/*.test.tsx"],
},
});
You can explicitly import describe
, it
/test
, expect
or you can have it work like in Jest where they're all globals. All you need to do is set globals
to true
in the Vitest configuration.
import { defineConfig } from "vite";
// https://vitejs.dev/config/
export default defineConfig({
test: {
include: ["./**/*.test.ts", "./**/*.test.tsx"],
+ globals: true,
},
});
Using Vitest with React
At OpenSauced, we're using Next.js to build out the main application.
Vitest is based off Vite which supports React via their plugin ecosystem, so you'll need to install the Vite React plugin to get React support.
Run npm install @vitejs/plugin-react -D
to install the plugin as a dev dependency.
Update the Vitest configuration to add the React plugin.
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
// https://vitejs.dev/config/
export default defineConfig({
+ plugins: [react()],
test: {
include: ["./**/*.test.ts", "./**/*.test.tsx"],
globals: true,
},
});
React Testing Library
If you happen to be using React Testing Library in your project, you'll need to keep the jsdom dev dependency installed.
Next, add jsdom
to your Vitest configuration.
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
// https://vitejs.dev/config/
export default defineConfig({
plugins: [react()],
test: {
include: ["./**/*.test.ts", "./**/*.test.tsx"],
globals: true,
+ environment: "jsdom",
},
});
Aliases
Your project might be using aliases for paths. For example, in the OpenSauced app repository, components
, lib
, and img
are aliases to folders.
If you need to support aliases, Vitest has you covered.
Here's an example of supporting the above-mentioned aliases.
export default defineConfig({
plugins: [react()],
+ resolve: {
+ alias: {
+ components: fileURLToPath(new URL("./components", import.meta.url)),
+ lib: fileURLToPath(new URL("./lib", import.meta.url)),
+ img: fileURLToPath(new URL("./img", import.meta.url)),
+ },
+ },
test: {
include: ["./**/*.test.ts", "./**/*.test.tsx"],
globals: true,
environment: "jsdom",
},
});
TypeScript Types
If you're using TypeScript, you can add the types for Vitest to the project.
In your tsconfig.json file, add the types in the compiler options section of the TypeScript configuration file.
{
"compilerOptions": {
// . .. other compiler options in your project
+ "types": ["vitest/globals"]
}
// . .. other TypeScript configuration options in your project
}
Running Tests
To run tests using Vitest, you can run vitest
. By default, it will go into watch mode. If you only want to run the test suite once, e.g. for the CI/CD pipeline, run vitest run
.
Removing Jest
If your project is a TypeScript project, you probably have the types for Jest in your project. If you do, run the following to remove the Jest TypeScript types.
npm uninstall -D @types/jest
Uninstall Jest itself.
npm uninstall jest jest-environment-jsdom -D
And that's it! Happy testing!
Stay saucy peeps!
If you would like to know more about my work in open source, follow me on OpenSauced.
Top comments (3)
Definitely interested to see if this solves some of the ESM headaches we have run into with Jest and having to provide custom resolvers.
Awesome stuff! We've been on Vitest for github.com/wasp-lang/wasp since day 1 and it is been amazing experience :)
Noice!