Vitest

https://main.vitest.dev
Admin
Vitest is a fast, Vite-native next-generation testing framework offering Jest compatibility, smart...
Tokens:615,793
Snippets:4,900
Trust Score:9.9
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Provide value in global setup file

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

Example of using the 'provide' function in a global setup file to supply a custom value to tests. This method is available when the public API cannot be used.

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

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

### Initialize browser mode with vitest init browser

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

Run the interactive setup command to install required dependencies and create browser configuration. Use the command for your package manager.

```bash
npx vitest init browser
```

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

```bash
pnpx vitest init browser
```

```bash
bunx vitest init browser
```

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

### Setup and cleanup with onCleanup

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

Shows how to use onCleanup inside a fixture to register teardown logic that runs after the test completes. The example writes a temporary file and removes it in the cleanup callback.

```ts
import { test as baseTest } from 'vitest'

export const test = baseTest
  .extend('tempFile', async ({}, { onCleanup }) => {
    const filePath = `/tmp/test-${Date.now()}.txt`
    await fs.writeFile(filePath, 'test data')

    // Register cleanup - runs after test completes
    onCleanup(async () => {
      await fs.unlink(filePath)
    })

    return filePath
  })
```

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

### beforeEach async setup example

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

Example of using beforeEach to clear mocks and add testing data before each test run. The callback is async, so Vitest waits for it to complete before running the test.

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

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

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

### One-Time Setup with beforeAll and afterAll

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

Use beforeAll and afterAll for expensive one-time setup, such as connecting to a database. The connection is created once, shared across all tests in the file, and closed after the file finishes. This avoids repeating costly setup for every test.

```javascript
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)
})
```

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

### OpenTelemetry SDK setup and Vitest configuration

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

Shows how to set up OpenTelemetry with Vitest. The otel.js file creates and starts a NodeSDK instance and exports it as the default export; vitest.config.js enables the experimental.openTelemetry option and points sdkPath to that file. The sdkPath is resolved relative to the project root and is not transformed by Vitest.

```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',
      },
    },
  },
})
```

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

### vi.defineHelper example output

Source: https://main.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| })
```

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

### Vitest run output with time metrics

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

Example output from running Vitest, showing the time metrics reported for each test file and the overall run. The metrics include transform, setup, import, tests, and environment times.

```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 ^^

```

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

### Global setup and teardown functions in globalSetup.ts

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

Defines a global setup file that runs once before all tests. The setup function can share data with tests via project.provide(), and the teardown function runs after all tests complete.

```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 WebdriverIO provider

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

Install the WebdriverIO provider for running tests locally using the WebDriver protocol.

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

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

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

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

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

### Example output of vitest list

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

Example output of the 'vitest list' command showing the hierarchical test names.

```txt
describe > some-test
describe > some-test > test 1
describe > some-test > test 2
```

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

### Different setups with provide and setupFiles

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

Configuration and test file for running the same browser with different setups. The first instance runs `./ratio-setup.ts` and injects `ratio: 1`, the second injects `ratio: 2`; the test uses `inject('ratio')` and expects the product with `globalSetupModifier` to be 14. Custom `name` values are required when reusing the same browser name.

```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)
})
```

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

### assert.notIncludeDeepOrderedMembers example

Source: https://main.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: different values, reversed order, and a subset that starts at the second element.

```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')
})
```

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

### Suite location example

Source: https://main.vitest.dev/api/advanced/test-suite

Example showing how the location of a suite is defined, with the suite starting at line 3, column 1.

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

describe('the validation works correctly', () => {
  // ...
})
```

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

### Install preview provider

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

Install the preview provider for local development. Note that the preview provider is not recommended for CI; use 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
```

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

### Initialize browser configuration

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

Sets up project configuration for the browser environment. Currently only supports the 'browser' value.

```bash
vitest init browser
```

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

### Suite ID format example

Source: https://main.vitest.dev/api/advanced/test-suite

Example of a suite ID format. The ID is deterministic, based on project name, module ID, and suite order. Do not parse the ID; it can have a minus at the start.

```text
1223128da3_0_0_0
^^^^^^^^^^ the file hash
           ^ suite index
             ^ nested suite index
               ^ test index
```

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

### assert.includeDeepOrderedMembers example

Source: https://main.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 passes because [{ a: 1 }, { b: 2 }] is a deep ordered subset of the superset.

```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')
})
```

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

### onTestRunStart example reporter

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

Example implementation of onTestRunStart that logs the number of test files scheduled to run. The specifications array is readonly and informational only.

```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()
```

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

### createVitest

Source: https://main.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
createVitest

### 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,
})
```
```

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

### createVitest function signature

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

TypeScript signature for createVitest. It returns a Promise<Vitest> and does not start tests or validate installed packages.

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

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

### assert.notIncludeOrderedMembers example

Source: https://main.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')
})
```

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

### start

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

Initializes reporters, coverage provider, and runs tests with optional filters.

```APIDOC
## start

### Description
Initializes reporters, the coverage provider, and runs tests. Accepts string filters to match test files, same as CLI filters.

### Method
start

### Signature
`function start(filters?: string[]): Promise<TestRunResult>`

### Parameters
- **filters** (string[]) - Optional - Filters to match test files.

### Returns
- **Promise<TestRunResult>** - Resolves when tests complete.

### Notes
- Should not be called if `vitest.standalone()` is also invoked.
- Use `runTestSpecifications` or `rerunTestSpecifications` instead if tests need to run after Vitest was initialized.
- Called automatically by `startVitest` if `config.mergeReports` and `config.standalone` are not set.
```

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

### Using asLocator()

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

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

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

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

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

### globalSetup with default export returning teardown

Source: https://main.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 its first argument. Teardown runs 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')
  }
}
```

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

### Worker-scoped fixture for expensive setup

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

Worker-scoped fixtures are initialized once per worker process. This example loads an expensive configuration once and shares it across tests in the same worker.

```ts
const test = baseTest
  .extend('config', { scope: 'worker' }, () => {
    return await loadExpensiveConfig()
  })
```

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

### GraphQL Setup with MSW

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

Sets up an MSW server in a Vitest setup file to mock GraphQL queries. Uses `graphql.query` and `HttpResponse.json` to return mock data, and configures `onUnhandledRequest: 'error'` to throw on unhandled requests.

```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())
```

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

### Provide custom value from Node.js API

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

Example of using 'project.provide' from a Node.js script to set a custom value before starting Vitest. The value is validated with structuredClone before storage.

```typescript
import { createVitest } from 'vitest/node'

const vitest = await createVitest('test')
const project = vitest.projects.find(p => p.name === 'custom')
project.provide('key', 'value')
await vitest.start()
```

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

### HTTP Setup with MSW

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

Sets up an MSW 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 throw on unhandled 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 environment performance hint output

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

Example output of the environment performance hint. It shows the number of times the DOM environment was created and suggests using `pool: 'vmThreads'` or `isolate: false` to improve performance.

```text
Environment  jsdom was created 40 times · 23.80s total, 79% of tracked time
             create it once per worker with pool: 'vmThreads' (keeps per-file isolation) or isolate: false (shares it across files)
             learn more: https://vitest.dev/guide/improving-performance#test-environments
```

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

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

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

Defines a global setup file using named exports 'setup' and 'teardown'. The setup function receives a test project as its first argument. 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')
}
```

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

### toHaveBeenNthCalledWith spy example

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

Uses vi.spyOn to create a spy on market.buy, then calls it twice and asserts the first call arguments with toHaveBeenNthCalledWith(1, ...). The count starts at 1.

```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 in vitest.config.js and extend expect in test/setup.js

Source: https://main.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.

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

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

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

expect.extend(customMatchers)
```

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

### Run sequential tests after parallel with sequence.groupOrder

Source: https://main.vitest.dev/guide/recipes/parallel-sequential

Force the parallel batch to finish before the sequential batch starts by setting sequence.groupOrder on each project. The parallel project gets groupOrder 0 and the sequential project gets groupOrder 1, keeping total wall clock close to parallel time plus sequential run time.

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

export default defineConfig({
  test: {
    projects: [
      {
        test: {
          name: 'Parallel',
          exclude: ['**.sequential.test.ts'],
          sequence: { groupOrder: 0 },
        },
      },
      {
        test: {
          name: 'Sequential',
          include: ['**.sequential.test.ts'],
          fileParallelism: false,
          sequence: { groupOrder: 1 },
        },
      },
    ],
  },
})
```

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

### Provide data from globalSetup.ts with TypeScript

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

Shows how to provide data to tests from a global setup file using the 'provide' method on the test project. Includes TypeScript module augmentation for 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
  }
}
```

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

### onTestModuleQueued hook signature

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

Signature for the onTestModuleQueued hook, called right before Vitest imports the setup file and the test module. At this point testModule has no children yet, but you can start reporting it as the next test to run.

```ts
function onTestModuleQueued(testModule: TestModule): Awaitable<void>
```

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

### beforeAll usage example

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

Example usage of beforeAll to set up mock data before tests run. The callback can be async; Vitest waits for the returned promise to resolve before running tests.

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

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

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

### Example output showing fsModuleCache performance improvement

Source: https://main.vitest.dev/guide/improving-performance

Example output from running one test file with a huge module graph (>900 modules) twice, showing the performance improvement from the file system module cache.

```shell
# the first run
Duration  8.75s (import 43%, transform 32%, tests 20%, setup 5%)

# the second run
Duration  5.90s (tests 44%, import 35%, transform 13%, setup 8%)
```

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

### Duration summary output

Source: https://main.vitest.dev/guide/improving-performance

Example output from the summary line showing the Duration breakdown as percentages of all tracked time. The percentages are relative to the sum of all tracked phases, not wall-clock time, because phases run in parallel workers. In a multi-project setup the percentages aggregate over all projects.

```text
Duration  3.76s (environment 79%, import 13%, transform 6%, tests 1%, setup 1%)
```

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

### Setup file with afterEach hook in setupFile.ts

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

A setup file that runs before each test file in the same process. It registers an afterEach hook to perform cleanup after every test.

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

// Runs before each test file
console.log('Setup file executing')

// Register hooks that apply to all tests
afterEach(() => {
  cleanup()
})
```

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

### Enable browser mode debugging via CLI and config

Source: https://main.vitest.dev/guide/debugging

These two examples show how to enable browser mode debugging with --inspect-brk. The CLI command runs Vitest with the flag, while the config file sets inspectBrk and fileParallelism. Both are equivalent ways to start debugging in browser mode.

```bash
vitest --inspect-brk --browser --no-file-parallelism
```

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

export default defineConfig({
  test: {
    inspectBrk: true,
    fileParallelism: false,
    browser: {
      provider: playwright(),
      instances: [{ browser: 'chromium' }]
    },
  },
})
```

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

### Full example of tags configuration

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

Comprehensive example defining multiple tags with descriptions, timeouts, retry logic, priority, and skip conditions. Note that `retry.condition` can only be a regexp and tags cannot apply other tags via these options.

```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,
      },
    ],
  },
})
```

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

### Example configuration with reporters array

Source: https://main.vitest.dev/config/reporters

Shows a `vitest.config.js` file that configures reporters, including conditional inclusion based on CI environment and a custom reporter with options.

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

export default defineConfig({
  test: {
    reporters: [
      ...configDefaults.reporters,
      // conditional reporter
      ...(process.env.CI ? ['html'] : []),
      // custom reporter from npm package
      // options are passed down as a tuple
      [
        'vitest-sonar-reporter',
        { outputFile: 'sonar-report.xml' }
      ],
    ]
  }
})
```

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

### Example DEBUG=vitest:projects output

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

Example output from running Vitest with DEBUG=vitest:projects, showing how project definitions are resolved, glob matches, Vite server sharing, and --project filter drops.

```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"
```

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

### toHaveFormValues usage example

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

Example usage of toHaveFormValues with a form element.

```ts
await expect.element(getByTestId('login-form')).toHaveFormValues({
  username: 'jane.doe',
  rememberMe: true,
})
```

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

### toHaveFormValues example HTML

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

HTML form used in the toHaveFormValues example.

```html
<form data-testid="login-form">
  <input type="text" name="username" value="jane.doe" />
  <input type="password" name="password" value="12345678" />
  <input type="checkbox" name="rememberMe" checked />
  <button type="submit">Sign in</button>
</form>
```

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

### Example import performance hint output

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

Example output of the import performance hint. It shows the number of module evaluations and estimates the time saved by setting `isolate: false`.

```text
Import  837 modules were evaluated 16740 times · 15.69s total, 64% of tracked time
        ~850ms faster with isolate: false — shared modules are evaluated once per worker instead of once per file
        learn more: https://vitest.dev/guide/improving-performance#test-isolation
```

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

### WebSocket Setup with MSW

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

Sets up an MSW server in a Vitest setup file to mock WebSocket connections. Uses `ws.link` and event listeners to handle connections and messages, echoing received messages back to the client. Configures `onUnhandledRequest: 'error'` to throw on unhandled requests.

```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())
```

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

### toHaveFocus example HTML

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

HTML element used in the toHaveFocus example.

```html
<div><input type="text" data-testid="element-to-focus" /></div>
```

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

### findElement() successful examples

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

Examples of findElement() calls that resolve successfully.

```ts
await page.getByText('Hello World').findElement() // ✅ HTMLDivElement
await page.getByText('World').findElement() // ✅ HTMLSpanElement
await page.getByText('Hello Germany').findElement() // ✅ HTMLDivElement
```

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

### startVitest: Run tests and inspect results

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

Use `startVitest` to initiate Vitest, validate packages, and run tests immediately. The returned `vitest` instance provides `state.getTestModules()` to inspect test results.

```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')
}
```

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

### Install Vite with Yarn

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

Install Vite explicitly as a dev dependency because Yarn does not install peer dependencies automatically. Vitest 5.0 requires Vite >= 6.4.0 and Node.js >= 22.12.0.

```bash
yarn add -D vite
```

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

### Import module as namespace object

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

Shows how to import the example module as a namespace object, which holds references to all exports.

```javascript
import * as exampleObject from './example.js'
```

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

### Install Chrome via browser-actions in GitHub Actions

Source: https://main.vitest.dev/guide/browser/visual-regression-testing

Use this step to install Chrome version 120 via the browser-actions/setup-chrome action, recommended for WebdriverIO to decouple browser installation.

```yaml
# ...the rest of the workflow
- uses: browser-actions/setup-chrome@v1
  with:
    chrome-version: 120
```

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

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

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

Install happy-dom or jsdom as dev dependencies to mock DOM and browser APIs. 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://main.vitest.dev/api/browser/assertions

HTML element used in the toHaveTextContent examples.

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

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

### Using createCLI to create the CLI

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

Example of using createCLI to create the Vitest command-line interface.

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

const cli = createCLI()
```

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

### toHaveFocus usage example

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

Example usage of toHaveFocus and its negation with focus and blur.

```ts
const input = page.getByTestId('element-to-focus')
input.element().focus()
await expect.element(input).toHaveFocus()
input.element().blur()
await expect.element(input).not.toHaveFocus()
```

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

### Implement BenchmarkProvider with Tinybench

Source: https://main.vitest.dev/guide/advanced/benchmark-provider

Example provider module that wraps Tinybench to implement the `BenchmarkProvider` interface. It must have a default export with an object implementing `BenchmarkProvider`. If you use Tinybench, add it as a direct dependency of your project.

```ts
import type { BenchmarkProvider } from 'vitest'
import { Bench } from 'tinybench'

const provider = {
  async run({ test, config, registrations, options }) {
    const bench = new Bench({
      signal: test.context.signal,
      retainSamples: config.retainSamples,
      ...options,
    })

    for (const { name, fn, fnOpts } of registrations) {
      bench.add(name, fn, fnOpts)
    }

    await bench.run()

    return bench.tasks.map((task) => {
      const result = task.result

      if (result.state === 'errored') {
        throw result.error
      }
      if (result.state !== 'completed') {
        throw new Error(`Benchmark "${task.name}" ended in the "${result.state}" state`)
      }

      return {
        ...result,
        name: task.name,
      }
    })
  },
} satisfies BenchmarkProvider

export default provider
```
Tokens:
Raw