Configuring Vitest

Write this test in a fresh Vue project and run it:

import { mount } from '@vue/test-utils'
import Button from '@/components/Button.vue'

it('renders the label', () => {
  expect(mount(Button, { props: { label: 'Save' } }).text()).toBe('Save')
})

Under Jest you get Cannot find module '@/components/Button.vue' or, worse, a raw SFC file that Node cannot parse. The fix is a pile of duplication: babel-jest, @vue/babel-preset-js, moduleNameMapper for the @ alias, vue-jest for single-file components, plus jest.mock configuration — and every alias, plugin, or CSS-module rule you add to vite.config.ts has to be mirrored by hand. That mirror is where test setups rot: the app compiles one way, the tests compile another, and the first divergence shows up as a test that passes in CI and fails when a developer runs it locally.

Vitest removes the mirror because it runs your tests through the same Vite pipeline the app uses. Same resolve.alias, same @vitejs/plugin-vue compiling SFCs, same define, same PostCSS and CSS-module handling. If it builds in the app, it builds in the test — no second resolver to keep in sync.

The setup itself is three packages plus a config block:

npm install -D vitest @vue/test-utils jsdom
npm install -D @vitest/coverage-v8   # only if you want coverage reports

/// <reference types="vitest" />
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { fileURLToPath, URL } from 'node:url'

export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: { '@': fileURLToPath(new URL('./src', import.meta.url)) },
  },
  test: {
    environment: 'jsdom',
    globals: true,
    include: ['src/**/__tests__/*.{spec,test}.ts'],
  },
})

The test key is a Vitest extension to Vite's config: TypeScript picks it up through the /// <reference> comment, and Vite itself ignores the unknown key during vite build. You do not need a separate Jest config file ever again.

There is a second-order benefit worth knowing before an interviewer probes: Vitest executes test files as native ESM through Vite's transform server, so there is no Babel round-trip and no jest.config transform list. A test that imports a .vue file, a .ts module, and a raw .json asset all go through the same request-based transform the dev server already serves, which is also why a cold suite starts in roughly the time the dev server takes to boot rather than a full Babel compile per file.

Two structurally different situations exist. When vite.config.ts already holds your aliases and plugins — the normal app — put test there and inherit everything for free. When you deliberately want test configuration isolated from the build (a plugin that must not run under Vitest, or a monorepo package with no Vite config), create vitest.config.ts and merge instead of redeclaring:

import { defineConfig, mergeConfig } from 'vitest/config'
import viteConfig from './vite.config'

export default mergeConfig(viteConfig, defineConfig({
  test: { environment: 'node' },
}))

mergeConfig copies aliases and plugins from the Vite config and lets the test block override only what differs. Recreating the alias list by hand in a second file is exactly the duplication you were escaping.

Interviewers ask about this more than you would expect — "why Vitest over Jest for Vue?" has one strong answer: one transform pipeline means the code under test is compiled by the same plugins, aliases, and define values as production, so configuration drift cannot make tests lie. Once this runs, Mounting Components in Tests can assume mount() works in every file, and the config you just wrote is what makes that true.

You arrived here from JavaScript Transition Hooks; nothing in that topic is assumed beyond knowing what a component file is.

The config above contains two lines that decide whether component tests run at all. Remove environment: 'jsdom' and your first mount() produces:

ReferenceError: document is not defined
  at Object.<anonymous> src/components/__tests__/Button.spec.ts:5:24

The test file compiled fine — the failure is environmental. Vitest runs each test file in a Node process, and Node has no DOM: no document, no window, no event dispatch, no getComputedStyle. The jsdom environment installs a JavaScript implementation of those APIs before your file runs, which is what mount() needs to build and patch real DOM nodes. jsdom is not a browser: it has no layout engine, no rendering, and no navigation, so anything that measures pixel geometry will mislead you.

The node option is worth adopting deliberately: a composable test that only touches ref and fetch boots noticeably faster without a DOM, and the restriction is a feature — it proves the logic does not secretly depend on window. You can switch per file with a docblock comment at the top of a single spec:

// @vitest-environment node
import { useCounter } from '@/composables/useCounter'

jsdom also decides which browser APIs your tests can fake. It implements localStorage, sessionStorage, History, and event dispatch, but it deliberately omits several APIs that real UI libraries reach for — window.matchMedia is a common one, and any component using a responsive-directive mixin throws TypeError: window.matchMedia is not a function in tests while working perfectly in the browser. The setupFiles entry discussed below is where you polyfill exactly those gaps:

// src/test/setup.ts
window.matchMedia ??= ((query: string) => ({
  matches: false, media: query, addEventListener() {}, removeEventListener() {},
})) as typeof window.matchMedia

Polyfilling in setup rather than in the component keeps the production code honest: the component still calls the real API, and the test environment supplies the missing piece once for every file.

The second config line, globals: true, makes describe, it, expect, vi, and beforeEach available without importing them in every file. It matches the Jest muscle memory most teams bring over, but it has a real cost: the file no longer shows where its test API comes from, and TypeScript only accepts the bare identifiers when tsconfig.json lists "types": ["vitest/globals"]. Import explicitly instead if you prefer tests where dependencies are visible on line one:

import { describe, it, expect, vi } from 'vitest'

Both styles pass the suite; pick one per repository and never mix them, because a file that imports it alongside a global it shadows confusingly and linters flag the inconsistency.

Two more config keys pay for themselves early. setupFiles: ['src/test/setup.ts'] runs once per file before the test body — the standard place for enableAutoUnmount(afterEach) so wrappers never leak between tests, and for stubbing browser APIs you do not want to repeat. And css: false tells Vitest to skip processing component styles: unless a test genuinely asserts on CSS classes defined only in a scoped stylesheet, turning stylesheet parsing off shaves time from every file without changing what you can assert on class names.

The environment decision also sets up the next topic: with jsdom in place, mount() has a DOM to render into, and every query you run against that DOM — find, text, classes — depends on jsdom having created it.

A test setup that is awkward to run gets skipped, and skipped tests are worse than no tests. The command surface is small, but each mode exists for a reason.

vitest (usually wired as "test": "vitest") starts watch mode: it discovers files, then keeps the process alive and re-runs only the files affected by each edit. That is the local loop — save a file, see its results in a few hundred milliseconds, without re-running the suite. The trap is CI: watch mode never exits, so a pipeline using npm test sits until the job timeout and reports a failure your tests never caused. The one-shot form is the run flag or the subcommand:

{
  "scripts": {
    "test": "vitest",
    "test:unit": "vitest run",
    "test:coverage": "vitest run --coverage",
    "test:ui": "vitest --ui"
  }
}

Speed in CI comes from filtering, not from skipping tests entirely. Three filters cover the daily cases:

vitest run src/components/__tests__/Cart.spec.ts   # one file
vitest run -t "applies the discount code"          # test names, substring match
vitest run --changed=HEAD~1                        # only files touched since a commit

--changed is the one people miss: it asks Git which source files your last commit or working-tree edit modified and runs only the tests that could be affected, which turns a 400-test suite into a 12-test local check while still being a real run.

The other half of the CI story is making the exit code mean something. Coverage with the V8 provider is the common gate:

export default defineConfig({
  test: {
    coverage: {
      provider: 'v8',
      reporter: ['text', 'lcov'],
      thresholds: { lines: 80, branches: 70 },
    },
  },
})

Now a pull request that drops below 80% lines fails the job with a readable report instead of slipping through. Add CI=true when a script might still fall back to watch, plus --reporter=junit --outputFile=junit.xml so the platform can render per-test results, and --passWithNoTests in a monorepo package where the glob legitimately matches nothing on some runs — without it, Vitest exits non-zero on an empty match.

Scale comes from sharding. Vitest splits files across isolated workers, and for a large suite you can split the run across CI machines instead of one long job:

vitest run --shard=1/3   # machine A
vitest run --shard=2/3   # machine B
vitest run --shard=3/3   # machine C

Each shard reports its own exit code and artifacts, and the gate is the AND of the three — wall-clock time drops roughly in proportion to the shard count, at the price of three runners to provision. Before reaching for shards, check the cheap wins first: --reporter=dot for compact output, dropping css processing, and exclude entries so generated files and fixtures are never collected as tests.

Determinism is the requirement people forget: a suite that flakes in watch mode but passes on re-run trains the team to ignore red. Real timers, shared module state, and un-flushed promises are the usual causes, and each gets a specific fix in Testing Async Updates.

With npm test for the loop and npm run test:unit for the gate, the environment is configured. Mounting Components in Tests starts where this leaves off: a mount() call that actually renders.