@vitest-agent/mcp 1.1.0 → 1.2.0

package/vendor/vitest-docs/guide/learn/writing-tests.md

@@ -1,231 +0,0 @@
-# Writing Tests
-
-In the [Getting Started](/guide/) guide, you installed Vitest and ran your first test. This page dives deeper into how to write and organize tests in Vitest.
-
-## Your First Test
-
-A test verifies that a piece of code produces the expected result. In Vitest, you use the [`test`](/api/test) function to define a test, and [`expect`](/api/expect) to make assertions. Each test has a name (a string describing what it checks) and a function that contains one or more assertions. If any assertion fails, the test fails.
-
-```js
-import { expect, test } from 'vitest'
-
-test('Math.sqrt works for perfect squares', () => {
-  expect(Math.sqrt(4)).toBe(2)
-  expect(Math.sqrt(144)).toBe(12)
-  expect(Math.sqrt(0)).toBe(0)
-})
-```
-
-::: details Use `test` or `it`?
-You might also see tests written with [`it`](/api/test) instead of `test`. They behave identically. `it` is just an alias that some people prefer because it reads more naturally with a descriptive name:
-
-```js
-import { expect, it } from 'vitest'
-
-it('should compute square roots', () => {
-  expect(Math.sqrt(4)).toBe(2)
-})
-```
-
-Use whichever you prefer. Both work the same way, and you can mix them freely in a project. If you want to enforce a consistent choice across your codebase, the [`consistent-test-it`](https://github.com/vitest-dev/eslint-plugin-vitest/blob/main/docs/rules/consistent-test-it.md) ESLint rule (also available in [oxlint](https://oxc.rs/docs/guide/usage/linter/rules/jest/consistent-test-it.html)) can help with that.
-:::
-
-## Grouping Tests with `describe`
-
-As your test files grow, you'll want to organize related tests together. [`describe`](/api/describe) creates a test suite, which is a named group of tests:
-
-```js
-import { describe, expect, test } from 'vitest'
-
-describe('Math.sqrt', () => {
-  test('returns the square root of perfect squares', () => {
-    expect(Math.sqrt(4)).toBe(2)
-    expect(Math.sqrt(9)).toBe(3)
-  })
-
-  test('returns NaN for negative numbers', () => {
-    expect(Math.sqrt(-1)).toBeNaN()
-  })
-
-  test('returns 0 for 0', () => {
-    expect(Math.sqrt(0)).toBe(0)
-  })
-})
-```
-
-You can nest `describe` blocks for further organization, but keep nesting shallow. Deeply nested tests are harder to read. A flat list of tests is often enough for simple modules, and `describe` becomes more useful when a file tests multiple functions or methods that each need their own group.
-
-## Test Files
-
-By default, Vitest looks for any file that contains `.test.` or `.spec.` in its name, such as `utils.test.js`, `app.spec.js`, or `math.test.jsx`. It searches in all subdirectories, so it doesn't matter where you place them.
-
-The exact patterns are:
-
-- `**/*.test.{ts,js,mjs,cjs,tsx,jsx}`
-- `**/*.spec.{ts,js,mjs,cjs,tsx,jsx}`
-
-There's no single "right" way to organize your test files. Some teams prefer placing tests right next to the source code they test, while others keep them in a dedicated directory. Vitest will find them either way:
-
-```
-src/
-  utils.js
-  utils.test.js       # co-located with the source
-  __tests__/
-    utils.test.js      # in a test directory
-```
-
-If the default patterns don't work for your project, you can customize which files are included with the [`include`](/config/include) and [`exclude`](/config/exclude) config options.
-
-## Testing TypeScript
-
-Because Vitest runs on top of Vite, TypeScript works out of the box. There's no extra compiler to install, no `ts-jest` to configure, and no separate build step for your tests. Just name your test file `.test.ts` instead of `.test.js` and start writing:
-
-```ts
-import { expect, test } from 'vitest'
-
-interface User {
-  name: string
-  age: number
-}
-
-function createUser(name: string, age: number): User {
-  return { name, age }
-}
-
-test('creates a user with the correct fields', () => {
-  const user = createUser('Alice', 30)
-
-  expect(user).toEqual({ name: 'Alice', age: 30 })
-  expect(user.name).toBe('Alice')
-})
-```
-
-You can import your production types, use generics, and write typed test utilities exactly as you would in the rest of your codebase. Vite transforms TypeScript on the fly, so tests start fast even in large projects.
-
-::: tip
-Vitest transforms TypeScript for execution but does **not** type-check your tests during the test run. This is the same trade-off Vite makes for speed: you get fast feedback in the terminal, and run `tsc` or `vitest typecheck` separately when you want full type checking. See the [Testing Types](/guide/testing-types) guide for more details.
-:::
-
-## Reading Test Output
-
-When you run `vitest` and only a single test file matches, the output is expanded into a tree structure showing `describe` groups and individual tests along with their duration:
-
-<<< ./snippets/test-output-single.ansi
-
-When multiple test files run, Vitest collapses each file into a single line to keep the output manageable:
-
-<<< ./snippets/test-output-multiple.ansi
-
-When a test fails, Vitest shows you exactly what went wrong. You'll see the expected value, the actual value, a diff highlighting the difference, and a code snippet of the surrounding lines with the failing assertion highlighted. It also includes the file and line number so you can jump straight to the source:
-
-<<< ./snippets/test-output-fail.ansi
-
-Between the diff and the code snippet, you can usually understand what went wrong without needing to add extra `console.log` statements or open the file yourself.
-
-## Skipping and Focusing Tests
-
-While developing, you'll often want to run only a subset of tests. Vitest provides modifiers for this:
-
-[`.only`](/api/test#only) tells Vitest to run only this test (or suite) and skip everything else in the file. This is useful when you're working on a specific test and don't want to wait for the entire suite to finish:
-
-```js
-test.only('focus on this test', () => {
-  // only this test runs in the file
-})
-```
-
-[`.skip`](/api/test#skip) does the opposite. It skips a test without removing it, which is handy when a test is temporarily broken or you want to ignore it while you work on something else:
-
-```js
-test.skip('not ready yet', () => {
-  // this test is skipped
-})
-```
-
-[`.todo`](/api/test#todo) lets you mark a placeholder for a test you haven't written yet. Vitest will list it in the output so you won't forget about it:
-
-```js
-test.todo('implement validation later')
-```
-
-These modifiers are great for quick, local changes while developing. For more permanent ways to filter tests (by filename, line number, or tags), see the [Test Filtering](/guide/filtering) guide.
-
-## Parameterized Tests
-
-When you have several test cases that only differ in their inputs and expected outputs, writing a separate `test` for each one gets repetitive. [`test.for`](/api/test#test-for) lets you define the cases as data and run the same test logic for all of them:
-
-```js
-import { expect, test } from 'vitest'
-
-test.for([
-  [1, 1, 2],
-  [1, 2, 3],
-  [2, 1, 3],
-])('add(%i, %i) -> %i', ([a, b, expected]) => {
-  expect(a + b).toBe(expected)
-})
-```
-
-The placeholders `%i`, `%s`, and `%f` in the test name are replaced with the corresponding values from each row, so the output shows `add(1, 1) -> 2`, `add(1, 2) -> 3`, and so on.
-
-If your cases have more than two or three values, passing objects is more readable. Use `$property` in the name to interpolate fields:
-
-```js
-test.for([
-  { a: 1, b: 1, expected: 2 },
-  { a: 1, b: 2, expected: 3 },
-  { a: 2, b: 1, expected: 3 },
-])('add($a, $b) -> $expected', ({ a, b, expected }) => {
-  expect(a + b).toBe(expected)
-})
-```
-
-The second argument to the test function is the [Test Context](/guide/test-context), which gives you access to fixtures, per-test `expect`, and other utilities. This is especially useful with [`test.concurrent`](/api/test#concurrent), where concurrent tests run in parallel and the global `expect` can't reliably associate a snapshot with the right test. The context-scoped `expect` solves this:
-
-```js
-test.concurrent.for([
-  [1, 1],
-  [1, 2],
-  [2, 1],
-])('add(%i, %i)', ([a, b], { expect }) => {
-  expect(a + b).toMatchSnapshot()
-})
-```
-
-[`describe.for`](/api/describe#describe-for) works the same way but creates a suite for each set of parameters, which is useful when multiple tests share the same parameterized setup.
-
-::: tip
-Vitest also provides [`test.each`](/api/test#each), which you may recognize from Jest. It works similarly but spreads array arguments instead of passing them as a single value, and doesn't provide access to the Test Context. It exists mainly for Jest compatibility. Prefer `test.for` in new code.
-:::
-
-## Using Global Imports
-
-By default, you import `test`, `expect`, `describe`, and other functions from `vitest` at the top of every test file. If you'd rather use them as globals without importing (similar to how Jest works), you can enable the [`globals`](/config/globals) option in your config:
-
-```js [vitest.config.js]
-import { defineConfig } from 'vitest/config'
-
-export default defineConfig({
-  test: {
-    globals: true,
-  },
-})
-```
-
-With this enabled, you can write tests without the import line:
-
-```js
-test('no import needed', () => {
-  expect(1 + 1).toBe(2)
-})
-```
-
-::: tip
-If you use TypeScript, add `"types": ["vitest/globals"]` to your `tsconfig.json` `compilerOptions` for proper type support.
-:::
-
-## Running Tests
-
-Vitest runs all test files **in parallel** by default, using [child processes](/config/pool). Each test file runs in its own isolated context, so your test files don't share state with each other. This prevents tests in different files from accidentally interfering.
-
-Tests **within** a single file run sequentially by default, which is usually what you want since tests in the same file often share setup code. If your tests are truly independent, you can opt into running them concurrently with [`test.concurrent`](/api/test#concurrent) to speed things up. See the [Parallelism](/guide/parallelism) guide for more details on controlling test execution.

package/vendor/vitest-docs/guide/lifecycle.md

@@ -1,379 +0,0 @@
-# Test Run Lifecycle
-
-::: tip
-Looking for a practical introduction to `beforeEach`, `afterEach`, and other hooks? See the [Setup and Teardown](/guide/learn/setup-teardown) tutorial.
-:::
-
-Understanding the test run lifecycle is essential for writing effective tests, debugging issues, and optimizing your test suite. This guide explains when and in what order different lifecycle phases occur in Vitest, from initialization to teardown.
-
-## Overview
-
-A typical Vitest test run goes through these main phases:
-
-1. **Initialization:** Configuration loading and project setup
-2. **Global Setup:** One-time setup before any tests run
-3. **Worker Creation:** Test workers are spawned based on the [pool](/config/pool) configuration
-4. **Test File Collection:** Test files are discovered and organized
-5. **Test Execution:** Tests run with their hooks and assertions
-6. **Reporting:** Results are collected and reported
-7. **Global Teardown:** Final cleanup after all tests complete
-
-Phases 4–6 run once for each test file, so across your test suite they will execute multiple times and may also run in parallel across different files when you use more than [1 worker](/config/maxworkers).
-
-## Detailed Lifecycle Phases
-
-### 1. Initialization Phase
-
-When you run `vitest`, the framework first loads your configuration and prepares the test environment.
-
-**What happens:**
-- [Command-line](/guide/cli) arguments are parsed
-- [Configuration file](/config/) is loaded
-- Project structure is validated
-
-This phase can run again if the config file or one of its imports changes.
-
-**Scope:** Main process (before any test workers are created)
-
-### 2. Global Setup Phase
-
-If you have configured [`globalSetup`](/config/globalsetup) files, they run once before any test workers are created.
-
-**What happens:**
-- `setup()` functions (or exported `default` function) from global setup files execute sequentially
-- Multiple global setup files run in the order they are defined
-
-**Scope:** Main process (separate from test workers)
-
-**Important notes:**
-- Global setup runs in a **different global scope** from your tests
-- Tests cannot access variables defined in global setup (use [`provide`/`inject`](/config/provide) instead)
-- Global setup only runs if there is at least one test queued
-
-```ts [globalSetup.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')
-}
-```
-
-### 3. Worker Creation Phase
-
-After global setup completes, Vitest creates test workers based on your [pool configuration](/config/pool).
-
-**What happens:**
-- Workers are spawned according to the `browser.enabled` or `pool` setting (`threads`, `forks`, `vmThreads`, or `vmForks`)
-- Each worker gets its own isolated environment (unless [isolation](/config/isolate) is disabled)
-- By default, workers are not reused to provide isolation. Workers are reused only if:
-  - [isolation](/config/isolate) is disabled
-  - OR pool is `vmThreads` or `vmForks` because [VM](https://nodejs.org/api/vm.html) provides enough isolation
-
-**Scope:** Worker processes/threads
-
-### 4. Test File Setup Phase
-
-Before each test file runs, [setup files](/config/setupfiles) are executed.
-
-**What happens:**
-- Setup files run in the same process as your tests
-- By default, setup files run in **parallel** (configurable via [`sequence.setupFiles`](/config/sequence#sequence-setupfiles))
-- Setup files execute before **each test file**
-- Any global _state_ or configuration can be initialized here
-
-**Scope:** Worker process (same as your tests)
-
-**Important notes:**
-- If [isolation](/config/isolate) is disabled, setup files still rerun before each test file to trigger side effects, but imported modules are cached
-- Editing a setup file triggers a rerun of all tests in watch mode
-
-```ts [setupFile.ts]
-import { afterEach } from 'vitest'
-
-// Runs before each test file
-console.log('Setup file executing')
-
-// Register hooks that apply to all tests
-afterEach(() => {
-  cleanup()
-})
-```
-
-### 5. Test Collection and Execution Phase
-
-This is the main phase where your tests actually run.
-
-#### Test File Execution Order
-
-Test files are executed based on your configuration:
-
-- **Sequential by default** within a worker
-- Files will run in **parallel** across different workers, configured by [`maxWorkers`](/config/maxworkers)
-- Order can be randomized with [`sequence.shuffle`](/config/sequence#sequence-shuffle) or fine-tuned with [`sequence.sequencer`](/config/sequence#sequence-sequencer)
-- Long-running tests typically start earlier (based on cache) unless shuffle is enabled
-
-#### Within Each Test File
-
-The execution follows this order:
-
-1. **File-level code:** All code outside `describe` blocks runs immediately
-2. **Test collection:** `describe` blocks are processed, and tests are registered as side effects of importing the test file
-3. **[`aroundAll`](/api/hooks#aroundall) hooks:** Wrap around all tests in the suite (must call `runSuite()`)
-4. **[`beforeAll`](/api/hooks#beforeall) hooks:** Run once before any tests in the suite
-5. **For each test:**
-   - [`aroundEach`](/api/hooks#aroundeach) hooks wrap around the test (must call `runTest()`)
-   - `beforeEach` hooks execute (in order defined, or based on [`sequence.hooks`](/config/sequence#sequence-hooks))
-   - Test function executes
-   - `afterEach` hooks execute (reverse order by default with `sequence.hooks: 'stack'`)
-   - [`onTestFinished`](/api/hooks#ontestfinished) callbacks run (always in reverse order)
-   - If test failed: [`onTestFailed`](/api/hooks#ontestfailed) callbacks run
-   - Note: if `repeats` or `retry` are set, all of these steps are executed again
-6. **[`afterAll`](/api/hooks#afterall) hooks:** Run once after all tests in the suite complete
-
-**Example execution flow:**
-
-```ts
-// This runs immediately (collection phase)
-console.log('File loaded')
-
-describe('User API', () => {
-  // This runs immediately (collection phase)
-  console.log('Suite defined')
-
-  aroundAll(async (runSuite) => {
-    // Wraps around all tests in this suite
-    console.log('aroundAll before')
-    await runSuite()
-    console.log('aroundAll after')
-  })
-
-  beforeAll(() => {
-    // Runs once before all tests in this suite
-    console.log('beforeAll')
-  })
-
-  aroundEach(async (runTest) => {
-    // Wraps around each test
-    console.log('aroundEach before')
-    await runTest()
-    console.log('aroundEach after')
-  })
-
-  beforeEach(() => {
-    // Runs before each test
-    console.log('beforeEach')
-  })
-
-  test('creates user', () => {
-    // Test executes
-    console.log('test 1')
-  })
-
-  test('updates user', () => {
-    // Test executes
-    console.log('test 2')
-  })
-
-  afterEach(() => {
-    // Runs after each test
-    console.log('afterEach')
-  })
-
-  afterAll(() => {
-    // Runs once after all tests in this suite
-    console.log('afterAll')
-  })
-})
-
-// Output:
-// File loaded
-// Suite defined
-// aroundAll before
-//   beforeAll
-//   aroundEach before
-//     beforeEach
-//       test 1
-//     afterEach
-//   aroundEach after
-//   aroundEach before
-//     beforeEach
-//       test 2
-//     afterEach
-//   aroundEach after
-//   afterAll
-// aroundAll after
-```
-
-#### Nested Suites
-
-When using nested `describe` blocks, hooks follow a hierarchical pattern. The `aroundAll` and `aroundEach` hooks wrap around their respective scopes, with parent hooks wrapping child hooks:
-
-```ts
-describe('outer', () => {
-  aroundAll(async (runSuite) => {
-    console.log('outer aroundAll before')
-    await runSuite()
-    console.log('outer aroundAll after')
-  })
-
-  beforeAll(() => console.log('outer beforeAll'))
-
-  aroundEach(async (runTest) => {
-    console.log('outer aroundEach before')
-    await runTest()
-    console.log('outer aroundEach after')
-  })
-
-  beforeEach(() => console.log('outer beforeEach'))
-
-  test('outer test', () => console.log('outer test'))
-
-  describe('inner', () => {
-    aroundAll(async (runSuite) => {
-      console.log('inner aroundAll before')
-      await runSuite()
-      console.log('inner aroundAll after')
-    })
-
-    beforeAll(() => console.log('inner beforeAll'))
-
-    aroundEach(async (runTest) => {
-      console.log('inner aroundEach before')
-      await runTest()
-      console.log('inner aroundEach after')
-    })
-
-    beforeEach(() => console.log('inner beforeEach'))
-
-    test('inner test', () => console.log('inner test'))
-
-    afterEach(() => console.log('inner afterEach'))
-    afterAll(() => console.log('inner afterAll'))
-  })
-
-  afterEach(() => console.log('outer afterEach'))
-  afterAll(() => console.log('outer afterAll'))
-})
-
-// Output:
-// outer aroundAll before
-//   outer beforeAll
-//   outer aroundEach before
-//     outer beforeEach
-//       outer test
-//     outer afterEach
-//   outer aroundEach after
-//   inner aroundAll before
-//     inner beforeAll
-//     outer aroundEach before
-//       inner aroundEach before
-//         outer beforeEach
-//           inner beforeEach
-//             inner test
-//           inner afterEach
-//         outer afterEach
-//       inner aroundEach after
-//     outer aroundEach after
-//     inner afterAll
-//   inner aroundAll after
-//   outer afterAll
-// outer aroundAll after
-```
-
-#### Concurrent Tests
-
-When using `test.concurrent` or [`sequence.concurrent`](/config/sequence#sequence-concurrent):
-
-- Tests within the same file can run in parallel
-- Each concurrent test still runs its own `beforeEach` and `afterEach` hooks
-- Use [test context](/guide/test-context) for concurrent snapshots: `test.concurrent('name', async ({ expect }) => {})`
-
-### 6. Reporting Phase
-
-Throughout the test run, reporters receive lifecycle events and display results.
-
-**What happens:**
-- Reporters receive events as tests progress
-- Results are collected and formatted
-- Test summaries are generated
-- Coverage reports are generated (if enabled)
-
-For detailed information about the reporter lifecycle, see the [Reporters](/api/advanced/reporters) guide.
-
-### 7. Global Teardown Phase
-
-After all tests complete, global teardown functions execute.
-
-**What happens:**
-- `teardown()` functions from [`globalSetup`](/config/globalsetup) files run
-- Multiple teardown functions run in **reverse order** of their setup
-- In watch mode, teardown runs before process exit, not between test reruns
-
-**Scope:** Main process
-
-```ts [globalSetup.ts]
-export function teardown() {
-  // Clean up global resources
-  console.log('Global teardown complete')
-}
-```
-
-## Lifecycle in Different Scopes
-
-Understanding where code executes is crucial for avoiding common pitfalls:
-
-| Phase | Scope | Access to Test Context | Runs |
-|-------|-------|----------------------|------|
-| Config File | Main process | ❌ No | Once per Vitest run |
-| Global Setup | Main process | ❌ No (use `provide`/`inject`) | Once per Vitest run |
-| Setup Files | Worker (same as tests) | ✅ Yes | Before each test file |
-| File-level code | Worker | ✅ Yes | Once per test file |
-| `aroundAll` | Worker | ✅ Yes | Once per suite (wraps all tests) |
-| `beforeAll` / `afterAll` | Worker | ✅ Yes | Once per suite |
-| `aroundEach` | Worker | ✅ Yes | Per test (wraps each test) |
-| `beforeEach` / `afterEach` | Worker | ✅ Yes | Per test |
-| Test function | Worker | ✅ Yes | Once (or more with retries/repeats) |
-| Global Teardown | Main process | ❌ No | Once per Vitest run |
-
-## Watch Mode Lifecycle
-
-In watch mode, the lifecycle repeats with some differences:
-
-1. **Initial run:** Full lifecycle as described above
-2. **On file change:**
-   - New [test run](/api/advanced/reporters#ontestrunstart) starts
-   - Only affected test files are re-run
-   - [Setup files](/config/setupfiles) run again for those test files
-   - [Global setup](/config/globalsetup) does **not** re-run (use [`project.onTestsRerun`](/config/globalsetup#handling-test-reruns) for rerun-specific logic)
-3. **On exit:**
-   - Global teardown executes
-   - Process terminates
-
-## Performance Considerations
-
-Understanding the lifecycle helps optimize test performance:
-
-- **Global setup** is ideal for expensive one-time operations (database seeding, server startup)
-- **Setup files** run before each test file - avoid heavy operations here if you have many test files
-- **`beforeAll`** is better than `beforeEach` for expensive setup that doesn't need isolation
-- **Disabling [isolation](/config/isolate)** improves performance, but setup files still execute before each file
-- **[Pool configuration](/config/pool)** affects parallelization and available APIs
-
-For tips on how to improve performance, read the [Improving Performance](/guide/improving-performance) guide.
-
-## Related Documentation
-
-- [Global Setup Configuration](/config/globalsetup)
-- [Setup Files Configuration](/config/setupfiles)
-- [Test Sequencing Options](/config/sequence)
-- [Isolation Configuration](/config/isolate)
-- [Pool Configuration](/config/pool)
-- [Extending Reporters](/guide/advanced/reporters) - for reporter lifecycle events
-- [Test API Reference](/api/hooks) - for hook APIs