Getting Started
Overview
Vitest is a blazing fast unit test framework powered by Vite.
You can learn more about the rationale behind the project in the Why Vitest section.
Trying Vitest Online
You can try Vitest online on StackBlitz. It runs Vitest directly in the browser, and it is almost identical to the local setup but doesn't require installing anything on your machine.
Adding Vitest to your Project
// with npm
$ npm install -D vitest
// or with yarn
$ yarn add -D vitest
// or with pnpm
$ pnpm add -D vitest
TIP
Vitest requires Vite >=v2.7.10 and Node >=v14
Configuring Vitest
One of the main advantages of Vitest is its unified configuration with Vite. If present, vitest
will read your root vite.config.ts
to match with the plugins and setup as your Vite app. For example, your Vite resolve.alias and plugins configuration will work out-of-the-box. If you want a different configuration during testing, you can:
- Create
vitest.config.ts
, which will have the higher priority - Pass
--config
option to CLI, e.g.vitest --config ./path/to/vitest.config.ts
- Use
process.
orenv.VITEST mode
property ondefineConfig
(will be set totest
if not overridden) to conditionally apply different configuration invite.config.ts
To configure vitest
itself, add test
property in your Vite config. You'll also need to add a reference to Vitest types using a triple slash command at the top of your config file, if you are importing defineConfig
from vite
itself.
import { defineConfig } from 'vitest/config'
export default defineConfig({
test: {
// ...
},
})
See the list of config options in the Config Reference
Command Line Interface
In a project where Vitest is installed, you can use the vitest
binary in your npm scripts, or run it directly with npx vitest
. Here are the default npm scripts in a scaffolded Vitest project:
{
"scripts": {
"test": "vitest",
"coverage": "vitest run --coverage"
}
}
To run tests once without watching for file changes, use vitest run
. You can specify additional CLI options like --port
or --https
. For a full list of CLI options, run npx vitest --help
in your project.
Commands
vitest watch
Run all test suites but watch for changes and rerun tests when they change. Same as calling
vitest
without a command. In CI environments this command will fallback tovitest run
vitest run
Perform a single run without watch mode.
vitest dev
Run vitest in development mode.
vitest related
Run only tests that cover a list of source files. Works with static lazy imports, but not the dynamic ones. All files should be relative to root folder.
Useful to run with
lint-staged
or with your CI setup.vitest related /src/index.ts /src/hello-world.js
Options
Options | |
---|---|
-v, --version | Display version number |
-r, --root <path> | Define the project root |
-c, --config <path> | Path to config file |
-u, --update | Update snapshots |
-w, --watch | Smart & instant watch mode |
-t, --testNamePattern <pattern> | Run tests with full names matching the pattern |
--dir <path> | Base directory to scan for the test files |
--ui | Enable UI |
--open | Open the UI automatically if enabled (default: true ) |
--api [api] | Serve API, available options: --api.port <port> , --api.host [host] and --api.strictPort |
--threads | Enable Threads (default: true ) |
--silent | Silent console output from tests |
--isolate | Isolate environment for each test file (default: true ) |
--reporter <name> | Select reporter: default , verbose , dot or json |
--outputFile <filename> | Write test results to a file when the --reporter=json option is also specified |
--coverage | Use c8 for coverage |
--run | Do not watch |
--mode <name> | Override Vite mode (default: test ) |
--global | Inject APIs globally deprecated use --globals |
--globals | Inject APIs globally |
--dom | Mock browser api with happy-dom |
--environment <env> | Runner environment (default: node ) |
--passWithNoTests | Pass when no tests found |
--allowOnly | Allow tests and suites that are marked as only (default: false in CI, true otherwise) |
-h, --help | Display available CLI options |
Examples
Example | Source | Playground |
---|---|---|
basic | GitHub | Play Online |
graphql | GitHub | Play Online |
lit | GitHub | Play Online |
mocks | GitHub | Play Online |
puppeteer | GitHub | |
react | GitHub | Play Online |
react-enzyme | GitHub | Play Online |
react-mui | GitHub | Play Online |
react-storybook-testing | GitHub | Play Online |
react-testing-lib | GitHub | Play Online |
react-testing-lib-msw | GitHub | Play Online |
related | GitHub | Play Online |
ruby | GitHub | Play Online |
single-thread | GitHub | Play Online |
svelte | GitHub | Play Online |
testing-lib-react | GitHub | Play Online |
testing-library-jest-dom | GitHub | Play Online |
vitesse | GitHub | Play Online |
vue | GitHub | Play Online |
vue-jsx | GitHub | Play Online |
vue2 | GitHub | Play Online |
Projects using Vitest
- unocss
- unplugin-auto-import
- unplugin-vue-components
- vitesse
- vitesse-lite
- fluent-vue
- vueuse
- milkdown
- gridjs-svelte
- spring-easing
- bytemd
- faker
- million
- Vitamin
- neodrag
- svelte-multiselect
- iconify
Using Unreleased Commits
If you can't wait for a new release to test the latest features, you will need to clone the vitest repo to your local machine and then build and link it yourself (pnpm is required):
git clone https://github.com/vitest-dev/vitest.git
cd vitest
pnpm install
cd packages/vitest
pnpm run build
pnpm link --global # you can use your preferred package manager for this step
Then go to the project where you are using Vitest and run pnpm link --global vitest
(or the package manager that you used to link vitest
globally).
Community
If you have questions or need help, reach out to the community at Discord and GitHub Discussions.