How to Do Unit Testing with Vitest on Claude Code

5 min read
In this article

To run unit tests with Vitest on Claude Code, use the /test slash command or ask Claude to run npx vitest run directly in your project. Claude Code handles test execution, interprets failures, and iterates on fixes without leaving your terminal. For developers using Vite-based stacks (Vue, React, SvelteKit), Vitest is the natural testing choice because it shares Vite's config and runs at native ESM speed.

  • Vitest runs 2-20x faster than Jest on equivalent Vite projects due to shared transform pipeline (Vitest docs)
  • Claude Code can scaffold, execute, and fix tests in a single session — no manual context switching
  • Long test sessions consume Claude usage; Usagebar shows live consumption from the macOS menu bar so you never hit a 5-hour lockout mid-PR

What is Vitest and why use it with Claude Code?

Vitest is a Vite-native unit testing framework built by the Vite team. It reuses your existing vite.config.ts for transforms, aliases, and plugins, which means zero duplicate configuration. Tests run in an isolated worker thread pool with native ESM support and a Jest-compatible API, so migration from Jest is often a one-line change in package.json.

Claude Code pairs well with Vitest because Claude understands the full project context (imports, module aliases, TypeScript paths) that Vitest inherits from Vite. When a test fails, Claude can read the stack trace, locate the source, and propose a fix all in the same turn — faster than reading docs and editing manually.

How to set up Vitest in your project before asking Claude

If Vitest is not already installed, the fastest path is to let Claude scaffold it. Open Claude Code in your project root and say:

"Add Vitest to this project. Configure it in vite.config.ts and add a sample test for the utils module."

Claude will run the install, patch the config, and generate a working test file. If you prefer to do it manually first, the official Vitest getting started guide covers the three-step setup: install, add a test script, and define the test environment in vite.config.ts.

Minimal vitest config

// vite.config.ts
import { defineConfig } from 'vite'

export default defineConfig({
  test: {
    environment: 'node', // or 'jsdom' for browser APIs
    globals: true,
  },
})

With globals: true, you can use describe, it, expect without imports, matching the Jest API that Claude already knows well.

How to run Vitest tests inside Claude Code

There are three practical ways to trigger Vitest inside a Claude Code session, depending on what you need.

1. Use the /test slash command

The /test slash command is the most direct path. Type:

/test

Claude Code will look for the test script in package.json and execute it. If your script is vitest run, Claude runs a single-pass test suite and reports results inline. For watch mode during active development, ask Claude to run npx vitest --reporter=verbose instead.

2. Ask Claude to run a specific command

For targeted runs on a single file or test pattern, phrase it naturally:

"Run vitest on src/utils/format.test.ts and fix any failing tests."

Claude executes npx vitest run src/utils/format.test.ts, reads the output, diffs the failing assertion, and patches the implementation or the test depending on what is wrong.

3. Use /run with an explicit command

If you want full control over flags, use the /run command:

/run npx vitest run --coverage

This is useful for CI parity — running with the same flags your GitHub Actions pipeline would use. See the Claude Code CI/CD guide for wiring this into automated workflows.

Getting Claude to write Vitest tests from scratch

Beyond running existing tests, Claude Code excels at generating them. A well-scoped prompt produces useful output immediately:

  • For a utility function: "Write Vitest unit tests for src/lib/currency.ts. Cover edge cases: negative values, zero, and non-numeric strings."
  • For a Vue/React component: "Add Vitest tests for the LoginForm component using @testing-library/vue. Test submit behavior and validation errors."
  • For a coverage gap: "Run vitest coverage and write tests for any function below 80% coverage."

Claude reads the source, infers types, and writes tests that match the real behavior rather than inventing a fake API. The result is tests you'd actually commit, not boilerplate.

Comparison: running tests manually vs. via Claude Code

TaskManualVia Claude Code
Run all testsnpx vitest run in terminal/test or natural language
Fix a failing testRead error, locate file, edit, re-runClaude reads error and patches inline
Write tests for a new moduleWrite from scratch manuallyAsk Claude, review and commit
Coverage reportnpx vitest run --coverageAsk Claude to run and summarize gaps

Common Vitest issues Claude Code can solve

  • Module alias resolution failures: Vitest inherits Vite aliases but sometimes needs explicit resolve.alias entries. Claude can patch vite.config.ts when it reads a "cannot find module" error.
  • jsdom vs. happy-dom environment: Browser API tests fail in the default node environment. Ask Claude to switch to jsdom or add @vitest/browser for component tests.
  • TypeScript path errors: If your tsconfig.json uses paths, Vitest needs vite-tsconfig-paths plugin. Claude installs and wires it automatically when it encounters the error.
  • ESM-only packages breaking tests: Claude knows which packages need transformMode overrides or server.deps.inline entries and adds them without guesswork.

Watch your Claude usage while running long test sessions

Iterating on tests — especially fixing cascading failures or improving coverage — can burn through a lot of Claude usage quickly. Each test run, error analysis, and fix cycle consumes tokens. If you are on a Pro or Max plan, Claude Code usage counts against your plan limits.

You can check your current consumption with the /usage command inside Claude Code, or visit claude.ai/settings/usage. But checking manually breaks your flow.

Usagebar sits in your macOS menu bar and shows your usage percentage at a glance, with smart alerts at 50%, 75%, and 90% so you know when to pace yourself before hitting a 5-hour lockout at the worst possible moment (mid-PR, mid-test-suite). Credentials are stored securely in macOS Keychain. It's free for students, and pay-what-you-want for everyone else.

For more on managing usage effectively, see how to reduce Claude Code token usage and when Claude Code usage resets.

Key takeaways

  1. Use /test in Claude Code to run your package.json test script directly — works immediately if Vitest is already set up.
  2. For targeted runs, ask Claude naturally: "Run vitest on this file and fix failures" — Claude handles the shell command and the fix in one turn.
  3. For initial setup, ask Claude to install and configure Vitest — it patches vite.config.ts and writes a sample test correctly.
  4. For coverage-driven test writing, ask Claude to run vitest --coverage and fill in gaps below a target threshold.
  5. Monitor your Claude usage during long sessions with Usagebar to avoid being locked out while fixing a test suite.

Sources

Never Get Locked Out Mid-Task Again

Never hit your usage limits unexpectedly. Usagebar lives in your menu bar and shows your 5-hour and weekly limits at a glance.

Get Usagebar

$9 — one-time, lifetime updates