Vitest

https://vitest.dev/
Admin
Vitest is a fast, Vite-native, and Jest-compatible testing framework that supports ESM, TypeScript,...
Tokens:625,273
Snippets:4,925
Trust Score:9.9
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Provide values from global setup file

Source: https://vitest.dev/api/advanced/test-project

Example of using the provide method in a global setup file. The setup function receives provide and can supply values to tests.

```js
export default function setup({ provide }) {
  provide('wsPort', 3000)
}
```

--------------------------------

### Initialize browser mode with vitest init

Source: https://vitest.dev/guide/browser

Run the setup command with your preferred package manager. This installs required dependencies and creates browser configuration.

```bash
npx vitest init browser
```

```bash
yarn exec vitest init browser
```

```bash
pnpx vitest init browser
```

```bash
bunx vitest init browser
```

--------------------------------

### Passing data from global setup to tests (example.test.ts)

Source: https://vitest.dev/config/globalsetup

Shows how to read data provided by a global setup file in a test file. The 'inject' function is imported from 'vitest' and used to access the provided value. This example checks that the provided 'wsPort' equals 3000.

```ts
import { inject } from 'vitest'

inject('wsPort') === 3000
```

--------------------------------

### Key-value domain snapshot adapter with matcher setup and tests

Source: https://vitest.dev/guide/snapshot

Complete key-value domain snapshot adapter example: adapter implementation, matcher setup, and usage tests. The adapter stores objects as key=value lines, supports regex patterns (delimited by slashes) and subset key matching. Setup extends Vitest matchers with toMatchKvSnapshot and toMatchKvInlineSnapshot using Snapshots.toMatchDomainSnapshot and Snapshots.toMatchDomainInlineSnapshot. The test file demonstrates both snapshot and inline snapshot usage, with the inline snapshot containing a regex pattern for the score field.

```ts
import type { DomainMatchResult, DomainSnapshotAdapter } from 'vitest'

type KVCaptured = Record<string, string>
type KVExpected = Record<string, string | RegExp>

function renderKV(obj: Record<string, unknown>) {
  return `\n${Object.entries(obj).map(([k, v]) => `${k}=${v}`).join('\n')}\n`
}

export const kvAdapter: DomainSnapshotAdapter<KVCaptured, KVExpected> = {
  name: 'kv',

  capture(received: unknown): KVCaptured {
    if (received && typeof received === 'object') {
      return Object.fromEntries(
        Object.entries(received).map(([k, v]) => [k, String(v)]),
      )
    }
    throw new TypeError('kv adapter expects a plain object')
  },

  render(captured: KVCaptured): string {
    return renderKV(captured)
  },

  parseExpected(input: string): KVExpected {
    const entries = input.trim().split('\n').map((line) => {
      const eq = line.indexOf('=')
      const key = line.slice(0, eq)
      const raw = line.slice(eq + 1)
      const value = (raw.startsWith('/') && raw.endsWith('/') && raw.length > 1)
        ? new RegExp(raw.slice(1, -1))
        : raw
      return [key, value]
    })
    return Object.fromEntries(entries)
  },

  match(captured: KVCaptured, expected: KVExpected): DomainMatchResult {
    const resolvedLines: string[] = []
    let pass = true

    for (const [key, actualValue] of Object.entries(captured)) {
      const expectedValue = expected[key]

      // non-asserted keys are skipped (works as subset match)
      if (typeof expectedValue === 'undefined') {
        continue
      }

      // preserve matched pattern for normalized diff and partial update
      if (expectedValue instanceof RegExp && expectedValue.test(actualValue)) {
        resolvedLines.push(`${key}=/${expectedValue.source}/`)
        continue
      }

      resolvedLines.push(`${key}=${actualValue}`)
      pass &&= actualValue === expectedValue
    }

    return {
      pass,
      message: pass ? undefined : 'KV entries do not match',
      resolved: `\n${resolvedLines.join('\n')}\n`,
      expected: `\n${renderKV(expected)}\n`,
    }
  },
}

```

```ts
import { expect, Snapshots } from 'vitest'
import { kvAdapter } from './kv-adapter'

declare module 'vitest' {
  interface Matchers<R, T> {
    toMatchKvSnapshot: () => R
    toMatchKvInlineSnapshot: (inlineSnapshot?: string) => R
  }
}

expect.extend({
  toMatchKvSnapshot(received: unknown) {
    return Snapshots.toMatchDomainSnapshot.call(this, kvAdapter, received)
  },
  toMatchKvInlineSnapshot(received: unknown, inlineSnapshot?: string) {
    return Snapshots.toMatchDomainInlineSnapshot.call(this, kvAdapter, received, inlineSnapshot)
  },
})

```

```ts
import { expect, test } from 'vitest'

test('user data', () => {
  const user = { name: 'Alice', score: '42' }
  expect(user).toMatchKvSnapshot()
})

test('user data inline', () => {
  const user = { name: 'Alice', age: 100, score: '42' }
  expect(user).toMatchKvInlineSnapshot(`
    name=Alice
    score=/\d+/
  `)
})

```

--------------------------------

### Manual install for the preview provider

Source: https://vitest.dev/guide/browser

Install the preview provider and Vitest. Use this when you only want to preview how tests look; for CI you must install Playwright or WebdriverIO instead.

```bash
npm install -D vitest @vitest/browser-preview
```

```bash
yarn add -D vitest vite @vitest/browser-preview
```

```bash
pnpm add -D vitest @vitest/browser-preview
```

```bash
bun add -D vitest @vitest/browser-preview
```

--------------------------------

### beforeEach async setup example

Source: https://vitest.dev/api/hooks

Example of using beforeEach to clear mocks and add test data before each test. The async callback ensures Vitest waits for the promise to resolve before running the test.

```typescript
import { beforeEach } from 'vitest'

beforeEach(async () => {
  // Clear mocks and add some testing data before each test run
  await stopMocking()
  await addUser({ name: 'John' })
})
```

--------------------------------

### OpenTelemetry SDK setup and Vitest configuration

Source: https://vitest.dev/config/experimental

These two files work together to enable OpenTelemetry in Vitest. The `otel.js` file creates and starts an OpenTelemetry SDK instance, while `vitest.config.js` enables the feature and points to the SDK file. The SDK file must be a module that exports a started SDK instance as default.

```js
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto'
import { NodeSDK } from '@opentelemetry/sdk-node'

const sdk = new NodeSDK({
  serviceName: 'vitest',
  traceExporter: new OTLPTraceExporter(),
  instrumentations: [getNodeAutoInstrumentations()],
})

sdk.start()
export default sdk
```

```js
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    experimental: {
      openTelemetry: {
        enabled: true,
        sdkPath: './otel.js',
      },
    },
  },
})
```

--------------------------------

### vitest.config.ts - Sharing Vite server across projects

Source: https://vitest.dev/config/sharedviteserver

Example configuration showing how to define projects that share the root Vite server. Projects without server-changing options (like define) share the server, while projects with alias get their own server. The example also includes a tip about hoisting plugins to the declaring config.

```ts
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    projects: [
      // these projects share the root Vite server
      { test: { name: 'unit', include: ['**/*.unit.test.ts'] } },
      { test: { name: 'integration', include: ['**/*.integration.test.ts'] } },
      // `define` doesn't create a new server, so this project also shares it
      { define: { __DEV__: 'true' }, test: { name: 'dev' } },
      // this project resolves its own Vite config because of `alias`
      { test: { name: 'aliased', alias: { lib: './src/lib' } } },
    ],
  },
})
```

```ts
import react from '@vitejs/plugin-react'
import { defineConfig } from 'vitest/config'

export default defineConfig({
  // hoisted: instantiated once on the shared server
  plugins: [react()],
  test: {
    projects: [
      { test: { name: 'unit', include: ['**/*.unit.test.ts'] } },
      { test: { name: 'integration', include: ['**/*.integration.test.ts'] } },
    ],
  },
})
```

--------------------------------

### Global setup with named exports (setup/teardown)

Source: https://vitest.dev/config/globalsetup

Defines a global setup file using named exports 'setup' and 'teardown'. The setup function receives a test project as the first argument and is called before test workers are created, only if at least one test is queued. Teardown runs after all test files finish, or before process exit in watch mode.

```js
export function setup(project) {
  console.log('setup')
}

export function teardown() {
  console.log('teardown')
}
```

--------------------------------

### vi.defineHelper example output

Source: https://vitest.dev/api/vi

Example output from the vi.defineHelper example, showing the error stack trace pointing to the call site.

```js
FAIL  example.test.ts > example
AssertionError: expected 'left' to deeply equal 'right'

Expected: "right"
Received: "left"

 ❯ example.test.ts:8:3
      7| test('example', () => {
      8|   assertPair('left', 'right')
       |   ^
      9| })
```

--------------------------------

### Guard setup initialization with globalThis flag

Source: https://vitest.dev/config/setupfiles

Use this setup file pattern when isolation is disabled to avoid repeating heavy initialization. It guards setup with a global flag, registers a cleanup hook, and sets a global variable for tests. Note that the setup file runs again before each test file, so the guard prevents redundant work.

```ts
import { config } from '@some-testing-lib'

if (!globalThis.setupInitialized) {
  config.plugins = [myCoolPlugin]
  computeHeavyThing()
  globalThis.setupInitialized = true
}

// hooks reset before each test file
afterEach(() => {
  cleanup()
})

globalThis.resetBeforeEachTest = true
```

--------------------------------

### Vitest run output with time metrics

Source: https://vitest.dev/guide/profiling-test-performance

Example output from running Vitest showing the reported time metrics: transform, setup, import, tests, and environment. The comment '# Time metrics ^^' points to the Duration line where these metrics are displayed.

```bash
RUN  v2.1.1 /x/vitest/examples/profiling

✓ test/prime-number.test.ts (1) 4517ms
  ✓ generate prime number 4517ms

Test Files  1 passed (1)
     Tests  1 passed (1)
  Start at  09:32:53
  Duration  4.80s (transform 44ms, setup 0ms, import 35ms, tests 4.52s, environment 0ms)
  # Time metrics ^^

```

--------------------------------

### globalSetup.ts: setup and teardown functions

Source: https://vitest.dev/guide/lifecycle

Defines global setup and teardown functions in a globalSetup file. The setup function runs once before all tests and can share data with tests via project.provide(). The teardown function runs once after all tests. Global setup runs in a different global scope from tests, so variables defined here are not accessible in tests.

```ts
export function setup(project) {
  // Runs once before all tests
  console.log('Global setup')

  // Share data with tests
  project.provide('apiUrl', 'http://localhost:3000')
}

export function teardown() {
  // Runs once after all tests
  console.log('Global teardown')
}
```

--------------------------------

### Install @vitest/ui

Source: https://vitest.dev/guide/ui

Install the optional Vitest UI package as a dev dependency.

```bash
npm i -D @vitest/ui
```

--------------------------------

### Install OpenTelemetry packages

Source: https://vitest.dev/guide/open-telemetry

Install the required OpenTelemetry packages for the Vitest integration.

```shell
npm i @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node @opentelemetry/exporter-trace-otlp-proto
```

--------------------------------

### vi.setConfig example

Source: https://vitest.dev/api/vi

Example of vi.setConfig with supported options. Only options that affect the current test file are supported.

```ts
vi.setConfig({
  allowOnly: true,
  testTimeout: 10_000,
  hookTimeout: 10_000,
  clearMocks: true,
  restoreMocks: true,
  fakeTimers: {
    now: new Date(2021, 11, 19),
    // supports the whole object
  },
  maxConcurrency: 10,
  sequence: {
    hooks: 'stack'
    // supports only "sequence.hooks"
  }
})
```

--------------------------------

### assert.match example

Source: https://vitest.dev/api/assert

Asserts that a string value matches a regular expression. The example checks that 'foobar' starts with 'foo' and includes a custom message.

```ts
import { assert, test } from 'vitest'

test('assert.match', () => {
  assert.match('foobar', /^foo/, 'regexp matches')
})
```

--------------------------------

### Alternative using beforeAll with cleanup

Source: https://vitest.dev/api/hooks

Shows the recommended alternative when only setup and teardown are needed, using beforeAll with a cleanup return function.

```ts
beforeAll(async () => {
  await server.start()
  return async () => {
    await server.stop()
  }
})
```

--------------------------------

### One-Time Setup with beforeAll and afterAll

Source: https://vitest.dev/guide/learn/setup-teardown

Uses beforeAll and afterAll to create a database connection once for the entire file and close it after all tests, sharing the connection across tests to avoid expensive repeated setup.

```js
import { afterAll, beforeAll, expect, test } from 'vitest'

let db

beforeAll(async () => {
  db = await connectToDatabase()
})

afterAll(async () => {
  await db.close()
})

test('can query users', async () => {
  const users = await db.query('SELECT * FROM users')
  expect(users.length).toBeGreaterThan(0)
})

test('can query products', async () => {
  const products = await db.query('SELECT * FROM products')
  expect(products.length).toBeGreaterThan(0)
})
```

--------------------------------

### mock.invocationCallOrder usage example

Source: https://vitest.dev/api/mock

Shows that invocationCallOrder returns the order of execution, shared across mocks. The first mock called first and third gets [1,3], the second mock called second gets [2].

```js
const fn1 = vi.fn()
const fn2 = vi.fn()

fn1()
fn2()
fn1()

fn1.mock.invocationCallOrder === [1, 3]
fn2.mock.invocationCallOrder === [2]
```

--------------------------------

### createVitest

Source: https://vitest.dev/guide/advanced

Creates a Vitest instance without starting tests or validating installed packages. Returns the same Vitest instance as startVitest.

```APIDOC
## createVitest

### Description
Creates a Vitest instance without starting tests or validating installed packages. Returns the same Vitest instance as `startVitest`.

### Method
Function

### Signature
```ts
function createVitest(
  options: CliOptions,
  viteOverrides: ViteUserConfig = {},
  vitestOptions: VitestOptions = {},
): Promise<Vitest>
```

### Parameters
- **options** (CliOptions) - Required - CLI options for Vitest.
- **viteOverrides** (ViteUserConfig) - Optional - Vite configuration overrides.
- **vitestOptions** (VitestOptions) - Optional - Additional Vitest options.

### Returns
- **Promise<Vitest>** - A promise that resolves to a Vitest instance.

### Example
```js
import { createVitest } from 'vitest/node'

const vitest = await createVitest('test', {
  watch: false,
})
```
```

--------------------------------

### onTestRunStart example

Source: https://vitest.dev/api/advanced/reporters

Example implementation of onTestRunStart in a custom reporter. Logs the number of test files that will run. Import types from 'vitest/node' and export a reporter instance.

```ts
import type { Reporter, TestSpecification } from 'vitest/node'

class MyReporter implements Reporter {
  onTestRunStart(specifications: TestSpecification[]) {
    console.log(specifications.length, 'test files will run')
  }
}

export default new MyReporter()
```

--------------------------------

### Define example.js module

Source: https://vitest.dev/guide/mocking/modules

Defines a module that exports the `answer` function and the `variable` constant. Used as the target for mocking examples in this guide.

```js
export function answer() {
  // ...
  return 42
}

export const variable = 'example'
```

--------------------------------

### Reporter example using onInit

Source: https://vitest.dev/api/advanced/reporters

Example reporter that stores the Vitest instance in onInit and logs the number of test files and the config root in onTestRunStart. Shows how to access the vitest instance from a reporter.

```ts
import type { Reporter, TestSpecification, Vitest } from 'vitest/node'

class MyReporter implements Reporter {
  private vitest!: Vitest

  onInit(vitest: Vitest) {
    this.vitest = vitest
  }

  onTestRunStart(specifications: TestSpecification[]) {
    console.log(
      specifications.length,
      'test files will run in',
      this.vitest.config.root,
    )
  }
}

export default new MyReporter()
```

--------------------------------

### createVitest function signature

Source: https://vitest.dev/guide/advanced

Type signature for the createVitest function. It returns the same Vitest instance as startVitest but does not start tests or validate installed packages.

```ts
function createVitest(
  options: CliOptions,
  viteOverrides: ViteUserConfig = {},
  vitestOptions: VitestOptions = {},
): Promise<Vitest>
```

--------------------------------

### GraphQL Setup with MSW

Source: https://vitest.dev/guide/mocking/requests

Sets up MSW's Node server in a Vitest setup file to mock GraphQL queries. Uses `graphql.query` to handle the 'ListPosts' query and returns mock data with `HttpResponse.json`.

```js
import { afterAll, afterEach, beforeAll } from 'vitest'
import { setupServer } from 'msw/node'
import { graphql, HttpResponse } from 'msw'

const posts = [
  {
    userId: 1,
    id: 1,
    title: 'first post title',
    body: 'first post body',
  },
  // ...
]

const graphqlHandlers = [
  graphql.query('ListPosts', () => {
    return HttpResponse.json({
      data: { posts },
    })
  }),
]

const server = setupServer(...graphqlHandlers)

// Start server before all tests
beforeAll(() => server.listen({ onUnhandledRequest: 'error' }))

// Close server after all tests
afterAll(() => server.close())

// Reset handlers after each test for test isolation
afterEach(() => server.resetHandlers())
```

--------------------------------

### Providing data from global setup (globalSetup.ts)

Source: https://vitest.dev/config/globalsetup

Shows how to provide serializable data to tests from a global setup file. The setup function receives a TestProject instance and uses its 'provide' method to pass a value. Also includes TypeScript module augmentation to type the provided context.

```ts
import type { TestProject } from 'vitest/node'

export default function setup(project: TestProject) {
  project.provide('wsPort', 3000)
}

declare module 'vitest' {
  export interface ProvidedContext {
    wsPort: number
  }
}
```

--------------------------------

### toMatchScreenshot comparatorOptions type inference

Source: https://vitest.dev/api/browser/assertions

Two TypeScript examples showing the need to explicitly set comparatorName to get proper type inference for comparatorOptions. The first example omits comparatorName and TypeScript cannot infer the correct options, potentially causing errors when new comparators are added. The second example sets comparatorName to 'pixelmatch' so TypeScript knows these are pixelmatch options.

```ts
// ❌ TypeScript can't infer the correct options
await expect.element(button).toMatchScreenshot({
  comparatorOptions: {
    // might error when new comparators are added
    allowedMismatchedPixelRatio: 0.01,
  },
})
```

```ts
// ✅ TypeScript knows these are pixelmatch options
await expect.element(button).toMatchScreenshot({
  comparatorName: 'pixelmatch',
  comparatorOptions: {
    allowedMismatchedPixelRatio: 0.01,
  },
})
```

--------------------------------

### Global setup with default function returning teardown

Source: https://vitest.dev/config/globalsetup

Defines a global setup file using a default function that returns a teardown function. The setup function receives a test project as the first argument. The returned teardown is called after all test files finish, or before process exit in watch mode.

```js
export default function setup(project) {
  console.log('setup')

  return function teardown() {
    console.log('teardown')
  }
}
```

--------------------------------

### Using asLocator()

Source: https://vitest.dev/api/browser/locators

Example of using asLocator() to get a human-readable locator string for diagnostic output. The returned string is not meant to be re-used to query elements.

```ts
import { page } from 'vitest/browser'

const button = page.getByRole('button', { name: 'Submit' })
button.asLocator() // "getByRole('button', { name: 'Submit' })"
```

--------------------------------

### Creating the Vitest CLI with createCLI

Source: https://vitest.dev/guide/advanced

Example of creating the Vitest CLI instance using createCLI.

```ts
import { createCLI } from 'vitest/node'

const cli = createCLI()
```

--------------------------------

### Repeating Setup with beforeEach and afterEach

Source: https://vitest.dev/guide/learn/setup-teardown

Uses beforeEach and afterEach to reset an array before each test and clear it after, ensuring tests start with a known state and preventing mutations from leaking between tests.

```js
import { afterEach, beforeEach, expect, test } from 'vitest'

let items

beforeEach(() => {
  items = ['apple', 'banana', 'cherry']
})

afterEach(() => {
  items = []
})

test('items starts with 3 fruits', () => {
  expect(items).toHaveLength(3)
})

test('can remove an item', () => {
  items.pop()
  expect(items).toHaveLength(2)
})

test('can add an item', () => {
  items.push('date')
  expect(items).toHaveLength(4)
  // beforeEach reset the array to 3 items before this test ran,
  // proving that mutations from the previous test do not leak.
})
```

--------------------------------

### assert.includeDeepOrderedMembers

Source: https://vitest.dev/api/assert

Asserts that `subset` is included in `superset` in the same order starting from the first element, using deep equality. The example shows a passing case where the first two objects match.

```ts
import { assert, test } from 'vitest'

test('assert.includeDeepOrderedMembers', () => {
  assert.includeDeepOrderedMembers([{ a: 1 }, { b: 2 }, { c: 3 }], [{ a: 1 }, { b: 2 }], 'include deep ordered members')
})
```

--------------------------------

### Different setups with custom names and provide values

Source: https://vitest.dev/guide/browser/multiple-setups

Configuration for two Chromium instances with different names and `provide` values. The first instance also runs a setup file. The test file uses `inject('ratio')` and a global setup modifier to verify the ratio. A custom `name` is required when using the same browser to avoid project name conflicts.

```ts
import { defineConfig } from 'vitest/config'
import { playwright } from '@vitest/browser-playwright'

export default defineConfig({
  test: {
    browser: {
      enabled: true,
      provider: playwright(),
      headless: true,
      instances: [
        {
          browser: 'chromium',
          name: 'chromium-1',
          setupFiles: ['./ratio-setup.ts'],
          provide: {
            ratio: 1,
          },
        },
        {
          browser: 'chromium',
          name: 'chromium-2',
          provide: {
            ratio: 2,
          },
        },
      ],
    },
  },
})
```

```ts
import { expect, inject, test } from 'vitest'
import { globalSetupModifier } from './example.js'

test('ratio works', () => {
  expect(inject('ratio') * globalSetupModifier).toBe(14)
})
```

--------------------------------

### startVitest: Run tests and inspect results

Source: https://vitest.dev/guide/advanced/tests

Initiates Vitest, validates packages, runs tests immediately, and returns a Vitest instance. Use the returned instance's state to get test modules and check pass/fail status.

```ts
import { startVitest } from 'vitest/node'

const vitest = await startVitest(
  [], // CLI filters
  {}, // override test config
  {}, // override Vite config
  {}, // custom Vitest options
)
const testModules = vitest.state.getTestModules()
for (const testModule of testModules) {
  console.log(testModule.moduleId, testModule.ok() ? 'passed' : 'failed')
}
```

--------------------------------

### beforeAll usage example

Source: https://vitest.dev/api/hooks

Example of using beforeAll to set up mock data before all tests run. The callback is async and awaits startMocking().

```typescript
import { beforeAll } from 'vitest'

beforeAll(async () => {
  await startMocking() // called once before all tests run
})
```

--------------------------------

### assert.includeOrderedMembers example

Source: https://vitest.dev/api/assert

Asserts that the subset is included in the superset in the same order, starting with the first element of the superset, using strict equality (===). The optional message parameter is used for assertion failure reporting.

```ts
import { assert, test } from 'vitest'

test('assert.includeOrderedMembers', () => {
  assert.includeOrderedMembers([1, 2, 3], [1, 2], 'include ordered members')
})
```

--------------------------------

### assert.notIncludeOrderedMembers

Source: https://vitest.dev/api/assert

Asserts that `subset` is not included in `superset` in the same order starting from the first element, using strict equality (===). The example shows two failing cases: [2,1] and [2,3] are not ordered subsets of [1,2,3].

```ts
import { assert, test } from 'vitest'

test('assert.notIncludeOrderedMembers', () => {
  assert.notIncludeOrderedMembers([1, 2, 3], [2, 1], 'not include ordered members')
  assert.notIncludeOrderedMembers([1, 2, 3], [2, 3], 'not include ordered members')
})
```

--------------------------------

### Example module for vi.mocked (example.ts)

Source: https://vitest.dev/api/vi

Example module used to demonstrate vi.mocked. Defines add, fetchSomething, and getUser functions with different return types.

```ts
export function add(x: number, y: number): number {
  return x + y
}

export function fetchSomething(): Promise<Response> {
  return fetch('https://vitest.dev/')
}

export function getUser(): { name: string; address: { city: string; zip: string } } {
  return { name: 'John', address: { city: 'New York', zip: '10001' } }
}
```

--------------------------------

### Extend BaseReporter with onTestRunEnd

Source: https://vitest.dev/api/advanced/reporters

Extends the built-in BaseReporter to customize the onTestRunEnd hook. The example logs the number of test modules and then calls the parent implementation. Use this as a starting point for creating a custom reporter.

```ts
import { BaseReporter } from 'vitest/node'

export default class CustomReporter extends BaseReporter {
  onTestRunEnd(testModules, errors) {
    console.log(testModule.length, 'tests finished running')
    super.onTestRunEnd(testModules, errors)
  }
}
```

--------------------------------

### Start Vitest UI with token authentication

Source: https://vitest.dev/guide/migration

Starts the Vitest UI server and prints a URL with a token. The browser must be authenticated via this token before the direct /__vitest__/ URL works.

```bash
vitest --ui
# UI started at http://localhost:51204/__vitest__/?token=...
```

--------------------------------

### Access built-in test context in test fixture

Source: https://vitest.dev/guide/test-context

Test-scoped fixtures have access to the built-in test context, such as task, expect, skip, etc. This example uses the task context to get the test name.

```ts
const test = baseTest
  .extend('testInfo', ({ task }) => {
    return { name: task.name }
  })
```

--------------------------------

### Full example of tag definitions

Source: https://vitest.dev/config/tags

Complete example showing tags with descriptions, timeouts, retries, priority, and conditional skip based on CI environment.

```ts
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    tags: [
      {
        name: 'unit',
        description: 'Unit tests.',
      },
      {
        name: 'e2e',
        description: 'End-to-end tests.',
        timeout: 60_000,
      },
      {
        name: 'flaky',
        description: 'Flaky tests that need retries.',
        retry: process.env.CI ? 3 : 0,
        priority: 1,
      },
      {
        name: 'slow',
        description: 'Slow tests.',
        timeout: 120_000,
      },
      {
        name: 'skip-ci',
        description: 'Tests to skip in CI.',
        skip: !!process.env.CI,
      },
    ],
  },
})
```

--------------------------------

### toHaveBeenNthCalledWith: Assert nth call arguments

Source: https://vitest.dev/api/expect

Shows how to use `toHaveBeenNthCalledWith` to assert the arguments of a specific invocation of a spy. The count starts at 1, so the example checks the first call. Requires a spy function passed to `expect`.

```ts
import { expect, test, vi } from 'vitest'

const market = {
  buy(subject: string, amount: number) {
    // ...
  },
}

test('first call of spy function called with right params', () => {
  const buySpy = vi.spyOn(market, 'buy')

  market.buy('apples', 10)
  market.buy('apples', 20)

  expect(buySpy).toHaveBeenNthCalledWith(1, 'apples', 10)
})
```

--------------------------------

### Configure setupFiles and extend expect with custom matchers

Source: https://vitest.dev/guide/learn/setup-teardown

Configure Vitest to run a setup file before every test file. The setup file extends the expect API with custom matchers. Setup files run in a separate phase before test collection, unlike beforeAll which runs once per file.

```javascript
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    setupFiles: ['./test/setup.js'],
  },
})
```

```javascript
// This runs before every test file
import { expect } from 'vitest'
import { customMatchers } from './custom-matchers.js'

expect.extend(customMatchers)
```

--------------------------------

### assert.notIncludeDeepOrderedMembers

Source: https://vitest.dev/api/assert

Asserts that `subset` is not included in `superset` in the same order starting from the first element, using deep equality. The example shows three failing cases: mismatched object, reversed order, and a subset that is actually included in order.

```ts
import { assert, test } from 'vitest'

test('assert.includeDeepOrderedMembers', () => {
  assert.notIncludeDeepOrderedMembers([{ a: 1 }, { b: 2 }, { c: 3 }], [{ a: 1 }, { f: 5 }], 'not include deep ordered members')
  assert.notIncludeDeepOrderedMembers([{ a: 1 }, { b: 2 }, { c: 3 }], [{ b: 2 }, { a: 1 }], 'not include deep ordered members')
  assert.notIncludeDeepOrderedMembers([{ a: 1 }, { b: 2 }, { c: 3 }], [{ b: 2 }, { c: 3 }], 'not include deep ordered members')
})
```

--------------------------------

### Solid example with @testing-library/solid

Source: https://vitest.dev/guide/browser

Example for Solid using @testing-library/solid. Renders a component with routes and asserts that the params are displayed correctly.

```tsx
// based on @testing-library/solid API
// https://testing-library.com/docs/solid-testing-library/api

import { render } from '@testing-library/solid'

it('uses params', async () => {
  const App = () => (
    <>
      <Route
        path="/ids/:id"
        component={() => (
          <p>
            Id:
            {useParams()?.id}
          </p>
        )}
      />
      <Route path="/" component={() => <p>Start</p>} />
    </>
  )
  const { baseElement } = render(() => <App />, { location: 'ids/1234' })
  const screen = page.elementLocator(baseElement)

  await expect.screen(screen.getByText('Id: 1234')).toBeInTheDocument()
})
```

--------------------------------

### userEvent.setup

Source: https://vitest.dev/api/browser/interactivity

Creates a new user event instance. This is useful if you need to keep the state of keyboard to press and release buttons correctly.

```APIDOC
## userEvent.setup

### Description
Creates a new user event instance. This is useful if you need to keep the state of keyboard to press and release buttons correctly.

### Method
setup

### Endpoint
userEvent.setup

### Parameters
None

### Request Example
```ts
import { userEvent } from 'vitest/browser'

const user = userEvent.setup()
```

### Response
#### Success Response
- **UserEvent** - A new user event instance.

#### Response Example
```ts
const user = userEvent.setup()
```
```

--------------------------------

### Type-Safe Scope Access with Object Syntax

Source: https://vitest.dev/guide/test-context

Use the object syntax with $worker, $file, and $test keys to explicitly declare fixture scopes and get compile-time type safety. This example shows worker-scoped config, file-scoped database, and test-scoped user fixtures.

```ts
const test = baseTest.extend<{
  $worker: { config: Config }
  $file: { database: Database }
  $test: { user: User }
}>({
  config: [async ({}, use) => {
    await use(loadConfig())
  }, { scope: 'worker' }],

  database: [async ({ config }, use) => {
    const db = await createDatabase(config)
    await use(db)
    await db.close()
  }, { scope: 'file' }],

  user: async ({ database }, use) => {
    const user = await database.createUser()
    await use(user)
    await database.deleteUser(user.id)
  },
})
```

--------------------------------

### Using userEvent.fill and locator.fill in a test

Source: https://vitest.dev/api/browser/interactivity

Example test that imports page and userEvent from 'vitest/browser', gets an input element by role, and fills it with various strings. It also shows the direct locator.fill method. The fill method focuses the element, fills it, and triggers an input event. An empty string clears the field.

```ts
import { page, userEvent } from 'vitest/browser'

test('update input', async () => {
  const input = page.getByRole('input')

  await userEvent.fill(input, 'foo') // input.value == foo
  await userEvent.fill(input, '{{a[[') // input.value == {{a[[
  await userEvent.fill(input, '{Shift}') // input.value == {Shift}

  // or you can access it directly on the locator
  await input.fill('foo') // input.value == foo
})
```

--------------------------------

### HTTP Setup with MSW

Source: https://vitest.dev/guide/mocking/requests

Sets up MSW's Node server in a Vitest setup file to mock HTTP requests. Uses `http.get` and `HttpResponse.json` to return mock data, and configures `onUnhandledRequest: 'error'` to fail tests on unmocked requests.

```js
import { afterAll, afterEach, beforeAll } from 'vitest'
import { setupServer } from 'msw/node'
import { http, HttpResponse } from 'msw'

const posts = [
  {
    userId: 1,
    id: 1,
    title: 'first post title',
    body: 'first post body',
  },
  // ...
]

export const restHandlers = [
  http.get('https://rest-endpoint.example/path/to/posts', () => {
    return HttpResponse.json(posts)
  }),
]

const server = setupServer(...restHandlers)

// Start server before all tests
beforeAll(() => server.listen({ onUnhandledRequest: 'error' }))

// Close server after all tests
afterAll(() => server.close())

// Reset handlers after each test for test isolation
afterEach(() => server.resetHandlers())
```

--------------------------------

### Example DEBUG=vitest:projects output

Source: https://vitest.dev/guide/projects

Example log output showing how Vitest logs project resolution details, including glob matches, project sharing, filtering, and Vite server creation.

```text
vitest:projects resolving 3 project definitions declared by <root>/vitest.config.ts
vitest:projects projects glob "packages/*" matched 2 paths
vitest:projects inline project "unit" shares the Vite server of <root>/vitest.config.ts
vitest:projects project "e2e" is dropped by the --project filter: unit
vitest:projects resolved projects: "unit", "pkg-a", "pkg-b"
vitest:projects creating a Vite server for project "pkg-a"
```

--------------------------------

### Initialize browser configuration

Source: https://vitest.dev/guide/cli

Initializes project configuration for the browser mode. Currently only supports the 'browser' value.

```bash
vitest init browser
```

--------------------------------

### WebSocket Setup with MSW

Source: https://vitest.dev/guide/mocking/requests

Sets up MSW's Node server in a Vitest setup file to mock WebSocket connections. Uses `ws.link` to define a WebSocket endpoint and listens for connection and message events, echoing received messages back to the client.

```js
import { afterAll, afterEach, beforeAll } from 'vitest'
import { setupServer } from 'msw/node'
import { ws } from 'msw'

const chat = ws.link('wss://chat.example.com')

const wsHandlers = [
  chat.addEventListener('connection', ({ client }) => {
    client.addEventListener('message', (event) => {
      console.log('Received message from client:', event.data)
      // Echo the received message back to the client
      client.send(`Server received: ${event.data}`)
    })
  }),
]

const server = setupServer(...wsHandlers)

// Start server before all tests
beforeAll(() => server.listen({ onUnhandledRequest: 'error' }))

// Close server after all tests
afterAll(() => server.close())

// Reset handlers after each test for test isolation
afterEach(() => server.resetHandlers())
```

--------------------------------

### element() non-throwing examples

Source: https://vitest.dev/api/browser/locators

Examples of element() calls that do not throw an error.

```ts
page.getByText('Hello World').element() // ✅
page.getByText('Hello Germany').element() // ✅
page.getByText('World').element() // ✅
page.getByText('Hello', { exact: true }).element() // ✅
```

--------------------------------

### Install happy-dom or jsdom for DOM mocking

Source: https://vitest.dev/guide/features

Install happy-dom or jsdom as dev dependencies to enable DOM and browser API mocking. These packages are not included with Vitest and must be installed separately.

```bash
$ npm i -D happy-dom
```

```bash
$ npm i -D jsdom
```

--------------------------------

### HTML element for toHaveTextContent example

Source: https://vitest.dev/api/browser/assertions

HTML element used in the toHaveTextContent example.

```html
<span data-testid="text-content">Text Content</span>
```

--------------------------------

### Example module with answer()

Source: https://vitest.dev/guide/mocking/modules

Example module that uses an imported function `answer()` to return a question. Used to illustrate mocking behavior in Vitest.

```ts
import { answer } from './example.js'

export function question() {
  if (answer() === 42) {
    return 'Ultimate Question of Life, the Universe, and Everything'
  }

  return 'Unknown Question'
}

```
Tokens:
Raw