@vitest-agent/mcp 1.0.1 → 1.2.0

package/public/vendor/vitest-docs/guide/learn/setup-teardown.md

@@ -1,240 +0,0 @@
-# Setup and Teardown
-
-Often while writing tests, you need to do some work before tests run (initialize data, connect to a database, start a server) and clean up afterwards. Rather than duplicating this code in every test, Vitest provides lifecycle hooks that run automatically at the right time.
-
-## Repeating Setup for Each Test
-
-The most common hooks are [`beforeEach`](/api/hooks#beforeeach) and [`afterEach`](/api/hooks#aftereach). As the names suggest, `beforeEach` runs before every test in the file, and `afterEach` runs after every test, even if the test fails. This makes them perfect for ensuring each test starts with a known state.
-
-```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 add an item', () => {
-  items.push('date')
-  expect(items).toHaveLength(4)
-  // afterEach will reset items for the next test,
-  // so this mutation won't leak into other tests
-})
-```
-
-Without these hooks, the second test's `push` would affect any test that runs after it, which is a classic source of flaky tests. The hooks guarantee clean state for every test.
-
-## One-Time Setup
-
-Some setup is too expensive to repeat for every test. If you need to connect to a database, start a server, or load a large file, doing that before every test would slow your suite down dramatically. That's what [`beforeAll`](/api/hooks#beforeall) and [`afterAll`](/api/hooks#afterall) are for. They run once for the entire file:
-
-```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)
-})
-```
-
-The database connection is created once, shared across all tests, and then closed when the file finishes running.
-
-## Scoping with `describe`
-
-Hooks defined inside a `describe` block only apply to the tests within that block. Top-level hooks apply to every test in the file. This lets you set up different state for different groups of tests:
-
-```js
-import { beforeEach, describe, expect, test } from 'vitest'
-
-describe('math operations', () => {
-  let value
-
-  beforeEach(() => {
-    value = 0
-  })
-
-  test('can add', () => {
-    value += 5
-    expect(value).toBe(5)
-  })
-
-  test('can subtract', () => {
-    value -= 3
-    expect(value).toBe(-3) // value was reset to 0 by beforeEach
-  })
-})
-
-describe('string operations', () => {
-  let text
-
-  beforeEach(() => {
-    text = 'hello'
-  })
-
-  test('can uppercase', () => {
-    expect(text.toUpperCase()).toBe('HELLO')
-  })
-})
-```
-
-Each `describe` block has its own `beforeEach` that only affects the tests inside it. The string tests don't know or care about the `value` variable, and vice versa.
-
-## Execution Order
-
-When you have hooks at multiple levels, it's helpful to understand the order they run in. Top-level hooks wrap around inner hooks, forming a nesting structure:
-
-```js
-import { afterAll, afterEach, beforeAll, beforeEach, describe, test } from 'vitest'
-
-beforeAll(() => console.log('1 - beforeAll'))
-afterAll(() => console.log('8 - afterAll'))
-beforeEach(() => console.log('2 - beforeEach'))
-afterEach(() => console.log('5 - afterEach'))
-
-describe('suite', () => {
-  beforeEach(() => console.log('3 - inner beforeEach'))
-  afterEach(() => console.log('4 - inner afterEach'))
-
-  test('first test', () => {
-    console.log('  first test')
-  })
-
-  test('second test', () => {
-    console.log('  second test')
-  })
-})
-```
-
-This produces the following output:
-
-```
-1 - beforeAll
-2 - beforeEach
-3 - inner beforeEach
-  first test
-4 - inner afterEach
-5 - afterEach
-2 - beforeEach
-3 - inner beforeEach
-  second test
-4 - inner afterEach
-5 - afterEach
-8 - afterAll
-```
-
-Notice the pattern: `beforeAll` and `afterAll` run once for the entire suite, while `beforeEach` and `afterEach` repeat for every test. Within each test, outer `beforeEach` runs first (setting up the broadest context), then inner `beforeEach` runs (narrowing the context). After the test, the order reverses: inner `afterEach` cleans up the narrow context first, then outer `afterEach` handles the broader cleanup.
-
-## Cleanup with `onTestFinished`
-
-Sometimes you create a resource inside a test that needs to be cleaned up afterwards. You could use `afterEach`, but that means the cleanup is separated from the setup, which can make the test harder to follow. [`onTestFinished`](/api/hooks#ontestfinished) lets you register a cleanup function right where you create the resource:
-
-```js
-import { expect, onTestFinished, test } from 'vitest'
-
-test('creates a temporary file', () => {
-  const file = createTempFile()
-  onTestFinished(() => {
-    deleteTempFile(file)
-  })
-
-  expect(file.exists()).toBe(true)
-})
-```
-
-A similar pattern works with `beforeEach`. You can return a cleanup function and Vitest will call it after each test. This is especially nice when the setup and teardown are closely related:
-
-```js
-import { beforeEach } from 'vitest'
-
-beforeEach(() => {
-  const server = startServer()
-  return () => {
-    server.close()
-  }
-})
-```
-
-## Fixtures with `test.extend`
-
-The examples above use `let` variables and `beforeEach` to set up shared state. This works, but it has some downsides: the variable declarations are separated from the initialization, the types require explicit annotation, and it's easy to forget to clean up.
-
-Vitest offers a better pattern for this with [`test.extend`](/guide/test-context#extend-test-context). You define reusable **fixtures** that are automatically created for each test and cleaned up afterwards:
-
-```js [my-test.js]
-import { test as baseTest } from 'vitest'
-
-export const test = baseTest
-  .extend('db', async ({}, { onCleanup }) => {
-    const db = await createDatabase()
-    onCleanup(() => db.close())
-    return db
-  })
-  .extend('user', async ({ db }) => {
-    return await db.createUser({ name: 'Alice' })
-  })
-```
-
-```js [my-test.test.js]
-import { expect } from 'vitest'
-import { test } from './my-test.js'
-
-test('user is created', ({ db, user }) => {
-  expect(user.name).toBe('Alice')
-})
-```
-
-Fixtures are only initialized when a test actually uses them (by destructuring them from the context), and they can depend on each other. This makes them a great alternative to `beforeEach`/`afterEach` for most setup and teardown patterns.
-
-See the [Test Context](/guide/test-context) guide for the full details on fixtures, scoping, and overrides.
-
-## Setup Files
-
-If you have setup code that should run before every test file in your project (things like polyfills, global configuration, or custom matchers), you can put it in a setup file and point to it with the [`setupFiles`](/config/setupfiles) config option:
-
-```js [vitest.config.js]
-import { defineConfig } from 'vitest/config'
-
-export default defineConfig({
-  test: {
-    setupFiles: ['./test/setup.js'],
-  },
-})
-```
-
-```js [test/setup.js]
-// This runs before every test file
-import { expect } from 'vitest'
-import { customMatchers } from './custom-matchers.js'
-
-expect.extend(customMatchers)
-```
-
-Unlike `beforeAll`, which runs once per file, setup files run in a separate phase before the test file even starts being collected. This makes them the right place for things like extending the `expect` API or configuring global polyfills.
-
-::: tip
-For advanced cases where your test needs to run *inside* a wrapping context (like a database transaction or a tracing span), see the [`aroundEach`](/api/hooks#aroundeach) and [`aroundAll`](/api/hooks#aroundall) hooks. For the complete lifecycle picture, see [Test Run Lifecycle](/guide/lifecycle).
-:::

package/public/vendor/vitest-docs/guide/learn/snapshots.md

@@ -1,166 +0,0 @@
-# Snapshot Testing
-
-Snapshot tests capture the output of a piece of code and save it to a file. On subsequent runs, the output is compared against the saved snapshot. If the output changes, the test fails. Either the change is a bug, or the snapshot needs to be updated.
-
-This approach is particularly useful when you're testing something that produces structured output: a function that returns a complex object, a component that renders HTML, or an error formatter that produces multi-line messages. Writing manual assertions for every field or line would be tedious and fragile. Instead, you capture the entire output once, and let Vitest tell you if it ever changes.
-
-## Your First Snapshot
-
-To create a snapshot test, pass a value to [`toMatchSnapshot()`](/api/expect#tomatchsnapshot):
-
-```js
-import { expect, test } from 'vitest'
-
-function generateGreeting(name) {
-  return {
-    message: `Hello, ${name}!`,
-    timestamp: null,
-    version: 2,
-  }
-}
-
-test('generates a greeting', () => {
-  expect(generateGreeting('Alice')).toMatchSnapshot()
-})
-```
-
-The first time you run this test, there's no existing snapshot to compare against, so Vitest creates one. It stores the snapshot in a `__snapshots__` directory next to your test file:
-
-```
-__snapshots__/
-  example.test.js.snap
-```
-
-If you open that file, you'll see a serialized representation of the value:
-
-```js
-exports['generates a greeting 1'] = `
-{
-  "message": "Hello, Alice!",
-  "timestamp": null,
-  "version": 2,
-}
-`
-```
-
-From now on, every time you run this test, Vitest serializes the output of `generateGreeting('Alice')` and compares it character-by-character against this stored snapshot. If the output changes (say, someone modifies the message format or bumps the version number), the test fails and shows a clear diff of what changed.
-
-::: tip
-Commit your snapshot files to version control. They serve as a record of the expected output and should be reviewed in code review just like any other test assertion.
-:::
-
-## Inline Snapshots
-
-External snapshot files work well, but they mean you have to jump to a different file to see what the expected output actually looks like. For smaller values, it's often more convenient to keep the snapshot right in your test file with [`toMatchInlineSnapshot()`](/api/expect#tomatchinlinesnapshot).
-
-Start by writing the assertion without any argument:
-
-```js
-test('generates a greeting', () => {
-  expect(generateGreeting('Alice')).toMatchInlineSnapshot()
-})
-```
-
-When you run the test, Vitest will **automatically fill in** the snapshot as a string argument:
-
-```js
-test('generates a greeting', () => {
-  expect(generateGreeting('Alice')).toMatchInlineSnapshot(`
-    {
-      "message": "Hello, Alice!",
-      "timestamp": null,
-      "version": 2,
-    }
-  `)
-})
-```
-
-Now the expected output lives right next to the code that produces it. You can read the test and immediately understand what `generateGreeting` is expected to return. When the output changes, Vitest updates the string in place, so you don't need to manage separate snapshot files.
-
-Inline snapshots are great for small, focused values. For large outputs (like a full HTML page), external snapshots or file snapshots are a better fit.
-
-::: tip
-Unlike external snapshots, inline snapshots don't create separate `.snap` files. The expected value is stored directly in your test file as the argument to `toMatchInlineSnapshot()`, so there's nothing extra to commit.
-:::
-
-## Updating Snapshots
-
-When you intentionally change the output of your code, existing snapshots will be outdated and the tests will fail. This is by design; it's the whole point of snapshot testing. But once you've verified that the new output is correct, you need to update the snapshots.
-
-There are several ways to do this:
-
-- **In watch mode**: press `u` in the terminal to update all failed snapshots
-- **From the CLI**: run `vitest -u` or `vitest --update` to update snapshots and exit
-- **In VS Code**: use the "Update Snapshots" command on the test gutter icon from the [Vitest extension](https://vitest.dev/vscode)
-
-```bash
-vitest -u
-```
-
-For inline snapshots, Vitest modifies your test file directly with the new values. For external snapshots, it rewrites the `.snap` file.
-
-::: warning
-Be careful when updating snapshots. Always review the diff to confirm the changes are intentional and not a bug. It's easy to accidentally accept a broken output by blindly pressing `u`.
-:::
-
-## File Snapshots
-
-Sometimes the output you're testing is large enough that even an external `.snap` file feels awkward, or you want to view the snapshot with proper syntax highlighting in your editor. [`toMatchFileSnapshot()`](/api/expect#tomatchfilesnapshot) lets you save the snapshot to a file with any extension you want:
-
-```js
-test('renders the component', async () => {
-  const html = renderComponent()
-  await expect(html).toMatchFileSnapshot('./fixtures/component.html')
-})
-```
-
-The snapshot is stored as a plain `.html` file that you can open in a browser, view with syntax highlighting, or diff with standard tools. This works well for HTML, SVG, CSS, generated code, or any output where the file format matters for readability.
-
-## When to Use Snapshots
-
-Snapshots shine when you're working with structured, serializable output that would be painful to assert on manually. Some common use cases:
-
-- A function that returns a complex configuration object with many nested fields
-- HTML or markup generated by a rendering function or template engine
-- Error messages that include formatted stack traces or context information
-- CLI output or log messages with specific formatting
-- JSON API responses where you want to catch any unexpected field changes
-
-On the other hand, snapshots are not always the best tool. If the output changes frequently (for instance, it includes timestamps or random IDs), you'll spend more time updating snapshots than they save you. And if you only care about one or two specific fields, a targeted assertion like [`toMatchObject`](/api/expect#tomatchobject) or [`toHaveProperty`](/api/expect#tohaveproperty) expresses your intent more clearly than a snapshot that captures everything.
-
-The general rule: use snapshots when you want to protect against *any* change in the output, and use targeted assertions when you only care about *specific* properties.
-
-## Handling Dynamic Values
-
-If your output includes values that change every run (like timestamps or IDs), you can use property matchers to pin the structure while ignoring volatile fields. Pass an object with asymmetric matchers as the first argument to `toMatchSnapshot()` or `toMatchInlineSnapshot()`:
-
-```js
-test('user snapshot with dynamic fields', () => {
-  const user = createUser('Alice')
-
-  expect(user).toMatchSnapshot({
-    id: expect.any(Number),
-    createdAt: expect.any(Date),
-  })
-})
-```
-
-The `id` and `createdAt` fields are checked against the matchers (any number, any date) instead of being compared to a stored value. All other fields are snapshotted as usual.
-
-## Error Snapshots
-
-A common use of inline snapshots is capturing error messages. [`toThrowErrorMatchingInlineSnapshot`](/api/expect#tothrowerrormatchinginlinesnapshot) combines `toThrow` with `toMatchInlineSnapshot` so you can snapshot the error message without a separate `.snap` file:
-
-```js
-test('throws on invalid input', () => {
-  expect(() => parse('')).toThrowErrorMatchingInlineSnapshot(
-    `[Error: Unexpected end of input at position 0]`
-  )
-})
-```
-
-This is especially handy for verifying that error messages are clear and don't accidentally change. Like other inline snapshots, Vitest fills in the string on the first run and updates it when you press `u`.
-
-::: tip
-For custom snapshot serializers, snapshot matchers, and advanced configuration, see the [Snapshot](/guide/snapshot) guide.
-:::