Required dependencies

npm install vite@^6.0.0 @vitest/expect @vitest/runner @vitest/utils pathe tinybench
npm install --save-dev typescript @types/node

Optional environment packages (install only what you need):

npm install jsdom          # for jsdom environment
npm install happy-dom      # for happy-dom environment
npm install @edge-runtime/vm  # for edge-runtime environment
npm install @vitest/coverage-v8    # v8 coverage
npm install @vitest/coverage-istanbul  # istanbul coverage
npm install @vitest/ui     # UI reporter

No native build steps are required. Node >= 20.0.0 is mandatory.

Project setup

1. Drop the source — copy the source/ directory into your project, e.g. src/vitest-core/.

2. Alias in tsconfig.json:

{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "target": "ES2022",
    "module": "ESNext",
    "paths": {
      "vitest-core/*": ["./src/vitest-core/*"]
    }
  }
}

3. Point Vite at the source — in vite.config.ts:

import { defineConfig } from 'vite'

export default defineConfig({
  resolve: {
    alias: {
      'vitest-core': '/src/vitest-core',
    },
  },
})

4. Environment variables — no required env vars. Optional:

   • VITEST_MAX_THREADS — override default thread count
   • VITEST_SEGFAULT_RETRY — retry count on segfault

5. Node version check — assert process.version >= 20.0.0 before bootstrapping.

Public API

createExpect

import type { Test, TaskPopulated } from '@vitest/runner'
import type { ExpectStatic } from '@vitest/expect'

function createExpect(test?: Test | TaskPopulated): ExpectStatic

Creates a scoped expect instance bound to an optional test task. The returned object is fully compatible with Jest's expect API. Use this when building a custom test runner that needs assertion counting and snapshot state isolated per test.

environments

import type { Environment } from './types/environment'

const environments: {
  'node': Environment
  'jsdom': Environment
  'happy-dom': Environment
  'edge-runtime': Environment
}

const envs: string[] = Object.keys(environments)

A map of all built-in test environment adapters keyed by their canonical name. Use environments when implementing a custom project loader that must resolve which DOM/runtime environment to boot for a given test file.

VitestCache

class VitestCache {
  results: ResultsCache
  stats: FilesStatsCache

  constructor(logger: Logger)

  getFileTestResults(key: string): SuiteResultCache | undefined
  getFileStats(key: string): { size: number } | undefined

  static resolveCacheDir(
    root: string,
    dir?: string,
    projectName?: string
  ): string
}

Manages persisted test results and file-stat caches across runs. resolveCacheDir computes a deterministic, project-name-hashed subdirectory under node_modules/.vite/vitest/. Use this to implement cache invalidation or to query prior run results without launching the full runner.

VitestPlugin

import type { Plugin as VitePlugin } from 'vite'
import type { UserConfig } from './node/types/config'
import { Vitest } from './node/core'

async function VitestPlugin(
  options?: UserConfig,
  vitest?: Vitest
): Promise<VitePlugin[]>

Returns the full array of Vite plugins that constitute the Vitest build pipeline. Use this when you need to compose Vitest's transform and resolve behaviour into a custom Vite server or plugin chain.

ReportersMap

const ReportersMap: {
  'default': typeof DefaultReporter
  'agent': typeof AgentReporter
  'minimal': typeof AgentReporter
  'blob': typeof BlobReporter
  'verbose': typeof VerboseReporter
  'dot': typeof DotReporter
  'json': typeof JsonReporter
  'tap': typeof TapReporter
  'tap-flat': typeof TapFlatReporter
  'junit': typeof JUnitReporter
  // ...
}

A string-keyed registry of all built-in reporter constructors. Use this when implementing a reporter loader that resolves reporter names from user config strings to class instances.

Working examples

Scenario - Standalone expect with assertion counting

A script that exercises createExpect outside of the full test runner, suitable for embedding assertion logic in a CI check tool.

import { createExpect } from './src/vitest-core/integrations/chai/index'

const expect = createExpect()

expect.setState({ assertionCalls: 0 })

expect(1 + 1).toEqual(2)
expect('vitest').toContain('test')

const { assertionCalls } = expect.getState()
console.log(`Assertions executed: ${assertionCalls}`) // 2

Scenario - Querying the test result cache

Inspect cached results for a file without starting the runner, e.g. in a pre-push hook.

import { resolve } from 'pathe'
import { VitestCache } from './src/vitest-core/node/cache/index'
import type { Logger } from './src/vitest-core/node/logger'

// Minimal logger shim
const logger = {
  log: console.log,
  error: console.error,
} as unknown as Logger

const root = resolve(process.cwd())
const cacheDir = VitestCache.resolveCacheDir(root, undefined, 'my-project')
console.log('Cache directory:', cacheDir)

const cache = new VitestCache(logger)
await cache.results.readFromCache(cacheDir)

const results = cache.getFileTestResults('src/utils/format.test.ts')
if (results) {
  console.log('Last result:', results)
} else {
  console.log('No cached result for this file.')
}

Scenario - Selecting a test environment by name

Resolve an environment adapter from a user config string and read its name.

import { environments, envs } from './src/vitest-core/integrations/env/index'

console.log('Available environments:', envs)
// ['node', 'jsdom', 'happy-dom', 'edge-runtime']

const envName = (process.env.TEST_ENV ?? 'node') as keyof typeof environments
const env = environments[envName]

if (!env) {
  throw new Error(`Unknown environment "${envName}". Valid: ${envs.join(', ')}`)
}

console.log(`Using environment: ${env.name}`)
// Boot the environment for a test suite:
// const ctx = await env.setup(global, options)

Scenario - Instantiating a JSON reporter programmatically

Build a custom run pipeline that collects test output as JSON without the CLI.

import { JsonReporter } from './src/vitest-core/node/reporters/index'
import type { Reporter } from './src/vitest-core/node/types/reporter'

const reporter: Reporter = new JsonReporter({ outputFile: 'results.json' })

// Wire into your custom Vitest instance:
// const vitest = await createVitest('test', { reporters: [reporter] })
// await vitest.start()

File walkthrough

• api/ — Defines the typed RPC channel (check.ts validates the connection, setup.ts registers handlers, types.ts holds shared message types).
• create/ — Browser project creation wizard: creator.ts scaffolds config, examples.ts provides template strings.
• integrations/chai/ — Wraps @vitest/expect / chai into the Vitest expect API; poll.ts provides expect.poll for retrying assertions.
• integrations/css/ — Generates deterministic scoped class names for CSS Modules in tests.
• integrations/env/ — One file per built-in environment; index.ts exports the keyed map and envs array.
• integrations/mock/ — date.ts mocks Date; timers.ts implements fake timers via @sinonjs/fake-timers.
• integrations/snapshot/ — Chai snapshot plugin and environment-aware snapshot resolver.
• integrations/vi.ts — Implements the vi helper object exposed to test files.
• integrations/wait.ts — waitFor / waitUntil polling utilities.
• node/cache/ — VitestCache wraps ResultsCache and FilesStatsCache for incremental runs.
• node/cli/ — CLI option definitions and the startVitest entry-point wiring.
• node/config/ — Resolves and validates UserConfig into ResolvedConfig.
• node/plugins/ — Assembles the Vite plugin array (VitestPlugin) including transform, mock, optimizer plugins.
• node/pools/ — Thread, fork, and VM-based worker pools.
• node/reporters/ — All built-in reporters plus ReportersMap registry.
• node/core.ts — Vitest class: owns the Vite server, projects, reporters, and test lifecycle.
• node/logger.ts — Logger abstraction used throughout node-side code.
• node/state.ts — Mutable global runner state shared between orchestrator and pools.
• constants.ts — defaultPort and other compile-time constants.
• defaults.ts — configDefaults: the baseline UserConfig applied before user config.
• paths.ts — Canonical path resolution helpers used across the codebase.

Common pitfalls and fixes

• Node version below 20 — Vitest uses --experimental-vm-modules and modern structuredClone; enforce engines: { node: ">=20" } in your package.json.
• ESM / CJS interop — The source is ESM-first; if your project uses CommonJS, set "type": "module" or transpile with esbuild/tsup targeting esm.
• Missing @vitest/expect or @vitest/runner — These are separate workspace packages; install them explicitly — they are not bundled into the source block.
• jsdom / happy-dom not found at runtime — Environment adapters do a dynamic import(); install the matching package or the environment will throw a module-not-found error at test startup.
• VitestPlugin requires Vite >= 6 — Passing it to a Vite 5 server will produce type and runtime mismatches; pin vite@^6.0.0.
• Cache directory collisions in monorepos — VitestCache.resolveCacheDir hashes the projectName; always pass a unique, stable project name per workspace package to avoid result cache bleed-through.

Vibe-coding prompt template

I have dropped the Vitest core source into `src/vitest-core/` in my project.
The integration guide is in `USAGE.md` at the project root.
The upstream package is `@vitest/monorepo` (vitest 5.0.0-beta.1).

Please help me integrate this source step by step:

1. Read `USAGE.md` for the full API reference and working examples.
2. Read `src/vitest-core/node/core.ts` to understand the `Vitest` orchestrator class.
3. Read `src/vitest-core/integrations/chai/index.ts` for `createExpect` usage.
4. Read `src/vitest-core/node/reporters/index.ts` for available reporters.
5. Based on the above, wire up a programmatic Vitest run in `scripts/run-tests.ts`
   that: resolves config from `vitest.config.ts`, uses `VitestPlugin` in a Vite
   server, selects `JsonReporter` as the output reporter, and writes results to
   `test-results.json`.
6. Show me the full `scripts/run-tests.ts` file with correct imports from
   `src/vitest-core/`, respecting the ESM-first module system.
7. List any additional `npm install` commands needed beyond what is in `USAGE.md`.

License and credit

Vitest is released under the MIT License — see source/LICENSE if present, or the canonical copy at github.com/vitest-dev/vitest. Upstream package: vitest / @vitest/monorepo@5.0.0-beta.1.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.