@vitest-agent/mcp 1.0.1 → 1.2.0

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

@@ -1,277 +0,0 @@
-# Using Matchers
-
-Vitest uses `expect` with "matchers" to assert that values meet certain conditions. This page covers the matchers you'll use most often. For the complete list, see the [Expect API Reference](/api/expect).
-
-## Common Matchers
-
-The simplest way to test a value is with exact equality. When you write `expect(2 + 2).toBe(4)`, the [`toBe`](/api/expect#tobe) matcher checks that the value is exactly `4` using [`Object.is`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is).
-
-```js
-import { expect, test } from 'vitest'
-
-test('two plus two is four', () => {
-  expect(2 + 2).toBe(4)
-})
-```
-
-This works great for primitive values like numbers, strings, and booleans. But when you're comparing objects, `toBe` checks *identity* (whether they're the exact same object in memory), not whether they have the same shape. That's where [`toEqual`](/api/expect#toequal) comes in. It recursively compares every field of an object or element of an array, ignoring object identity:
-
-```js
-test('object assignment', () => {
-  const data = { one: 1 }
-  data.two = 2
-
-  expect(data).toEqual({ one: 1, two: 2 })
-})
-```
-
-Here's an example that shows the difference more clearly. Two objects with the same content are `toEqual` but not `toBe`:
-
-```js
-test('toBe vs toEqual', () => {
-  const a = { name: 'Alice' }
-  const b = { name: 'Alice' }
-
-  // These are different objects in memory
-  expect(a).not.toBe(b)
-
-  // But they have the same structure
-  expect(a).toEqual(b)
-})
-```
-
-There's also [`toStrictEqual`](/api/expect#tostrictequal), which is stricter than `toEqual` in three ways: it checks `undefined` properties, distinguishes sparse arrays from `undefined` values, and verifies that objects have the same type (not just the same shape):
-
-```js
-test('toEqual vs toStrictEqual', () => {
-  // toEqual ignores undefined properties
-  expect({ a: 1 }).toEqual({ a: 1, b: undefined })
-
-  // toStrictEqual catches them
-  expect({ a: 1 }).not.toStrictEqual({ a: 1, b: undefined })
-
-  // toEqual doesn't check object types
-  class User {
-    constructor(name) {
-      this.name = name
-    }
-  }
-  expect(new User('Alice')).toEqual({ name: 'Alice' })
-  expect(new User('Alice')).not.toStrictEqual({ name: 'Alice' })
-})
-```
-
-::: tip
-A good rule of thumb: use `toBe` for primitives (numbers, strings, booleans), `toEqual` for comparing structure, and `toStrictEqual` when you also care about types and explicit `undefined` values.
-:::
-
-You can also negate any matcher by inserting `.not` before it. This is useful when you want to verify that something is *not* the case:
-
-```js
-test('adding positive numbers is not zero', () => {
-  expect(1 + 2).not.toBe(0)
-})
-```
-
-## Truthiness
-
-In tests you sometimes need to distinguish between `undefined`, `null`, and `false`. Other times you don't care about the exact value and just want to know if something is truthy or falsy. Vitest provides matchers for both situations:
-
-- [`toBeNull`](/api/expect#tobenull) matches only `null`
-- [`toBeUndefined`](/api/expect#tobeundefined) matches only `undefined`
-- [`toBeDefined`](/api/expect#tobedefined) is the opposite of `toBeUndefined`. It passes for anything that isn't `undefined`
-- [`toBeTruthy`](/api/expect#tobetruthy) matches anything that an `if` statement would treat as true
-- [`toBeFalsy`](/api/expect#tobefalsy) matches anything that an `if` statement would treat as false
-
-You should pick the matcher that most precisely describes what you're checking. Using `toBeTruthy` when you really mean `toBeDefined` can hide bugs, because `0` and `""` are both defined but falsy.
-
-```js
-test('null checks', () => {
-  const n = null
-
-  expect(n).toBeNull()
-  expect(n).toBeDefined()
-  expect(n).toBeFalsy()
-  expect(n).not.toBeTruthy()
-  expect(n).not.toBeUndefined()
-})
-
-test('zero', () => {
-  const z = 0
-
-  expect(z).toBeDefined() // passes: 0 is defined
-  expect(z).toBeFalsy() // passes: 0 is falsy
-  expect(z).not.toBeNull() // passes: 0 is not null
-})
-```
-
-## Numbers
-
-Most number comparisons are straightforward. Vitest provides the matchers you'd expect for greater-than, less-than, and equality checks:
-
-```js
-test('number comparisons', () => {
-  const value = 2 + 2
-
-  expect(value).toBeGreaterThan(3)
-  expect(value).toBeGreaterThanOrEqual(3.5)
-  expect(value).toBeLessThan(5)
-  expect(value).toBeLessThanOrEqual(4.5)
-
-  // For exact equality, both toBe and toEqual work the same for numbers
-  expect(value).toBe(4)
-  expect(value).toEqual(4)
-})
-```
-
-There is one common gotcha with floating point arithmetic. In JavaScript, `0.1 + 0.2` doesn't equal `0.3` exactly (it's `0.30000000000000004`). This means a `toBe(0.3)` check will fail. Use [`toBeCloseTo`](/api/expect#tobecloseto) instead, which compares numbers within a small rounding error:
-
-```js
-test('adding floating point numbers', () => {
-  const value = 0.1 + 0.2
-
-  // This won't work because of floating point rounding
-  // expect(value).toBe(0.3)
-
-  // This works
-  expect(value).toBeCloseTo(0.3)
-})
-```
-
-## Strings
-
-You can test strings against regular expressions with [`toMatch`](/api/expect#tomatch). This is especially handy when you care about a pattern rather than an exact value, like checking that an error message contains a certain word or that a URL matches a particular format:
-
-```js
-test('there is no I in team', () => {
-  expect('team').not.toMatch(/I/)
-})
-
-test('version string matches semver format', () => {
-  expect('vitest@1.0.0').toMatch(/vitest@\d+\.\d+\.\d+/)
-})
-```
-
-## Arrays and Iterables
-
-[`toContain`](/api/expect#tocontain) checks that an array (or any iterable, like a `Set`) includes a particular item. It uses `===` for comparison, so it works well for primitives:
-
-```js
-test('the shopping list has milk in it', () => {
-  const shoppingList = ['milk', 'bread', 'eggs', 'butter']
-
-  expect(shoppingList).toContain('milk')
-  expect(new Set(shoppingList)).toContain('milk')
-})
-```
-
-If you need to check that an array contains an object with a particular structure, use [`toContainEqual`](/api/expect#tocontainequal) instead. It works like `toEqual` but for individual items inside an array.
-
-## Objects
-
-When testing objects, you often want to check only a few important fields without specifying every property. [`toMatchObject`](/api/expect#tomatchobject) lets you do exactly that. It verifies that the object contains at least the properties you specify, and ignores any additional ones:
-
-```js
-test('user has expected fields', () => {
-  const user = {
-    id: 1,
-    name: 'Alice',
-    email: 'alice@example.com',
-    createdAt: '2024-01-01'
-  }
-
-  // We only care about name and email here
-  expect(user).toMatchObject({
-    name: 'Alice',
-    email: 'alice@example.com',
-  })
-})
-```
-
-For checking individual properties, especially nested ones, [`toHaveProperty`](/api/expect#tohaveproperty) is more readable. You pass a dot-separated path and optionally an expected value:
-
-```js
-test('object has property', () => {
-  const user = {
-    name: 'Alice',
-    address: { city: 'Paris', zip: '75001' }
-  }
-
-  expect(user).toHaveProperty('name')
-  expect(user).toHaveProperty('name', 'Alice')
-  expect(user).toHaveProperty('address.city', 'Paris')
-  expect(user).toHaveProperty('address.zip')
-})
-```
-
-## Asymmetric Matchers
-
-Sometimes you don't know the exact value, but you know its type or shape. Asymmetric matchers let you describe what a value should *look like* without pinning down the exact content. They work inside any matcher that does deep comparison, like `toEqual` or `toMatchObject`:
-
-```js
-test('user has the right shape', () => {
-  const user = createUser('Alice')
-
-  expect(user).toEqual({
-    id: expect.any(Number),
-    name: 'Alice',
-    email: expect.stringContaining('@'),
-    roles: expect.arrayContaining(['viewer']),
-  })
-})
-```
-
-The most common asymmetric matchers are:
-
-- [`expect.any(Constructor)`](/api/expect#expect-any) matches any value created with the given constructor (e.g., `Number`, `String`, `Array`)
-- [`expect.stringContaining(str)`](/api/expect#expect-stringcontaining) matches a string that includes the given substring
-- [`expect.stringMatching(regex)`](/api/expect#expect-stringmatching) matches a string against a regular expression
-- [`expect.arrayContaining(arr)`](/api/expect#expect-arraycontaining) matches an array that includes all items in the expected array (order doesn't matter, extra items are allowed)
-- [`expect.objectContaining(obj)`](/api/expect#expect-objectcontaining) matches an object that includes at least the specified properties
-
-## Exceptions
-
-To verify that a function throws an error, use [`toThrow`](/api/expect#tothrow). You need to wrap the call in another function so that Vitest can catch the error instead of letting it crash the test:
-
-```js
-function compileCode(code) {
-  if (code === '') {
-    throw new Error('Cannot compile empty string')
-  }
-  return code
-}
-
-test('compiling an empty string throws', () => {
-  // Check that it throws at all
-  expect(() => compileCode('')).toThrow()
-
-  // Check the error message
-  expect(() => compileCode('')).toThrow('Cannot compile empty string')
-
-  // Check the message with a regex
-  expect(() => compileCode('')).toThrow(/empty string/)
-})
-```
-
-::: tip
-The wrapping function `() => compileCode('')` is important. If you wrote `expect(compileCode('')).toThrow()`, the error would be thrown *before* `expect` gets a chance to catch it, and the test would fail with an unhandled error instead.
-:::
-
-## Soft Assertions
-
-Normally, a failing assertion stops the test immediately. That's useful most of the time, but sometimes you want to check several independent things and see all the failures at once rather than fixing them one by one.
-
-[`expect.soft`](/api/expect#soft) does exactly that. It records the failure but lets the test keep running:
-
-```js
-test('check multiple fields', () => {
-  const user = { name: 'Alice', age: 30, role: 'admin' }
-
-  expect.soft(user.name).toBe('Alice')
-  expect.soft(user.age).toBe(25) // this fails but execution continues
-  expect.soft(user.role).toBe('admin')
-  // the test report will show that age didn't match
-})
-```
-
-This is especially useful for validating the shape of an API response or a complex object where multiple fields might be wrong at the same time.

package/public/vendor/vitest-docs/guide/learn/mock-functions.md

@@ -1,277 +0,0 @@
-# Mock Functions
-
-When writing tests, you often need to replace a real function or module with a controlled version. This is called **mocking**. There are several reasons you might want to do this: maybe the real function makes network requests that would slow down your tests, or maybe you need to simulate an error that's hard to trigger with real code. Mock functions let you control what a dependency returns, observe how it was called, and isolate the code under test from side effects.
-
-Vitest provides mocking utilities through the [`vi`](/api/vi) object.
-
-## Creating Mock Functions
-
-The simplest way to create a mock is with [`vi.fn()`](/api/vi#vi-fn). This gives you a function that does nothing by default (returns `undefined`), but tracks every call made to it:
-
-```js
-import { expect, test, vi } from 'vitest'
-
-test('mock function basics', () => {
-  const getApples = vi.fn()
-
-  // Call it
-  getApples()
-
-  // Check it was called
-  expect(getApples).toHaveBeenCalled()
-  expect(getApples).toHaveBeenCalledTimes(1)
-
-  // By default, a mock returns undefined
-  expect(getApples()).toBeUndefined()
-})
-```
-
-## Mock Return Values
-
-A mock that always returns `undefined` isn't very useful on its own. You'll usually want to control what it returns so you can test how your code reacts to different values:
-
-```js
-import { expect, test, vi } from 'vitest'
-
-test('mock return values', () => {
-  const getApples = vi.fn()
-
-  // Always return this value
-  getApples.mockReturnValue(10)
-  expect(getApples()).toBe(10)
-
-  // Return this value only once, then fall back to the default
-  getApples.mockReturnValueOnce(20)
-  expect(getApples()).toBe(20) // 20 (one-time)
-  expect(getApples()).toBe(10) // back to default
-})
-```
-
-If the function you're mocking is async, use [`mockResolvedValue`](/api/mock#mockresolvedvalue) and [`mockRejectedValue`](/api/mock#mockrejectedvalue) to control the promise outcome:
-
-```js
-test('mock async return values', async () => {
-  const fetchUser = vi.fn()
-
-  fetchUser.mockResolvedValue({ name: 'Alice' })
-  const user = await fetchUser()
-  expect(user.name).toBe('Alice')
-
-  fetchUser.mockRejectedValue(new Error('Not found'))
-  await expect(fetchUser()).rejects.toThrow('Not found')
-})
-```
-
-## Mock Implementation
-
-Sometimes you need more than a fixed return value. You want the mock to actually do something with its arguments. [`mockImplementation`](/api/mock#mockimplementation) lets you provide a full replacement function:
-
-```js
-import { expect, test, vi } from 'vitest'
-
-test('mock with custom implementation', () => {
-  const add = vi.fn()
-  add.mockImplementation((a, b) => a + b)
-
-  expect(add(1, 2)).toBe(3)
-  expect(add(10, 20)).toBe(30)
-})
-```
-
-As a shorthand, you can pass the implementation directly to `vi.fn()`:
-
-```js
-const add = vi.fn((a, b) => a + b)
-```
-
-## Inspecting Calls
-
-One of the most powerful things about mock functions is that they remember every call made to them. You can assert on how many times a function was called, what arguments it received, and what it returned:
-
-```js
-import { expect, test, vi } from 'vitest'
-
-test('inspecting mock calls', () => {
-  const greet = vi.fn()
-
-  greet('Alice')
-  greet('Bob', 'Charlie')
-
-  // Number of calls
-  expect(greet).toHaveBeenCalledTimes(2)
-
-  // Check specific arguments
-  expect(greet).toHaveBeenCalledWith('Alice')
-  expect(greet).toHaveBeenCalledWith('Bob', 'Charlie')
-
-  // Check the arguments of a specific call by position
-  expect(greet).toHaveBeenNthCalledWith(1, 'Alice')
-  expect(greet).toHaveBeenLastCalledWith('Bob', 'Charlie')
-
-  // Access the raw call data
-  expect(greet.mock.calls).toEqual([
-    ['Alice'],
-    ['Bob', 'Charlie'],
-  ])
-})
-```
-
-The `.mock` property gives you full access to the call history. In addition to `.mock.calls`, you can also inspect `.mock.results` to see what the mock returned (or threw) on each call:
-
-```js
-const double = vi.fn(x => x * 2)
-
-double(5)
-double(10)
-
-expect(double.mock.results).toEqual([
-  { type: 'return', value: 10 },
-  { type: 'return', value: 20 },
-])
-```
-
-::: warning
-`.mock.calls` stores references to the arguments, not copies. If you pass an object to a mock and then mutate it afterwards, the recorded call will reflect the mutated state, not the state at the time of the call:
-
-```js
-const fn = vi.fn()
-const obj = { count: 1 }
-
-fn(obj)
-obj.count = 2
-
-// ❌ This fails! mock.calls[0][0].count is now 2, not 1
-expect(fn).toHaveBeenCalledWith({ count: 1 })
-```
-
-If you need to assert on the original values, you can use `mockImplementation` to capture a clone at call time:
-
-```js
-const calls = []
-const fn = vi.fn((obj) => {
-  calls.push(structuredClone(obj))
-})
-
-const obj = { count: 1 }
-fn(obj)
-obj.count = 2
-
-expect(calls[0]).toEqual({ count: 1 }) // ✅ passes
-```
-
-Alternatively, you can make your assertion before the mutation happens.
-:::
-
-## Spying on Methods
-
-[`vi.spyOn`](/api/vi#vi-spyon) is different from `vi.fn()` in an important way. Instead of creating a brand new function, it wraps an *existing* method on an object. The original implementation still works by default, but you can observe every call and optionally override the behavior:
-
-```js
-import { expect, test, vi } from 'vitest'
-
-const calculator = {
-  add(a, b) {
-    return a + b
-  },
-}
-
-test('spy on a method', () => {
-  const spy = vi.spyOn(calculator, 'add')
-
-  // The original implementation still works
-  expect(calculator.add(1, 2)).toBe(3)
-
-  // But we can observe calls
-  expect(spy).toHaveBeenCalledWith(1, 2)
-  expect(spy).toHaveBeenCalledTimes(1)
-})
-
-test('spy can override implementation', () => {
-  const spy = vi.spyOn(calculator, 'add')
-  spy.mockReturnValue(42)
-
-  expect(calculator.add(1, 2)).toBe(42)
-})
-```
-
-This is particularly useful when you want to verify that your code calls a method correctly without replacing the method's behavior entirely.
-
-## Resetting Mocks
-
-Mock functions accumulate state as tests run. They remember every call, every return value, and any custom implementation you've set. If you don't reset them between tests, this state can leak and cause confusing failures. Vitest provides three levels of cleanup:
-
-- **[`mockClear()`](/api/mock#mockclear)** clears the recorded call history and return values, but keeps any custom implementation you've set
-- **[`mockReset()`](/api/mock#mockreset)** does everything `mockClear` does, and also removes any custom implementation, returning the mock to its default state
-- **[`mockRestore()`](/api/mock#mockrestore)** is specifically for spies created with `vi.spyOn`. It restores the original object method, effectively undoing the spy. On `vi.fn()` mocks, it behaves the same as `mockReset`
-
-In practice, the easiest approach is to restore all mocks automatically after each test:
-
-```js
-import { afterEach, expect, test, vi } from 'vitest'
-
-const calculator = {
-  add: (a, b) => a + b,
-}
-
-afterEach(() => {
-  vi.restoreAllMocks()
-})
-
-test('spy is restored after the test', () => {
-  const spy = vi.spyOn(calculator, 'add').mockReturnValue(42)
-  expect(calculator.add(1, 2)).toBe(42)
-  // afterEach will restore calculator.add to the original implementation
-})
-```
-
-Even better, you can configure this globally with the [`restoreMocks`](/config/restoremocks) option so you don't need the `afterEach` at all:
-
-```js [vitest.config.js]
-import { defineConfig } from 'vitest/config'
-
-export default defineConfig({
-  test: {
-    restoreMocks: true,
-  },
-})
-```
-
-## Mocking Modules
-
-Sometimes you need to replace an [entire module](/guide/mocking/modules) rather than a single function. For example, a database client or a logger that you don't want running during tests. [`vi.mock`](/api/vi#vi-mock) lets you replace a module's exports with mock implementations:
-
-```js
-import { expect, test, vi } from 'vitest'
-import { getUser } from './db.js'
-
-vi.mock(import('./db.js'), () => ({
-  getUser: vi.fn(),
-}))
-
-test('mock a module', () => {
-  vi.mocked(getUser).mockReturnValue({ name: 'Alice' })
-
-  const user = getUser(1)
-  expect(user.name).toBe('Alice')
-  expect(getUser).toHaveBeenCalledWith(1)
-})
-```
-
-::: warning
-[`vi.mock`](/api/vi#vi-mock) calls are hoisted to the top of the file. They run before any imports. This means the mocked version is in place by the time your test code runs.
-:::
-
-::: warning
-Always pass `import('./db.js')` rather than a plain string `'./db.js'`. When you use `import()`, TypeScript can infer the module's types, so the factory function's return value is type-checked and `importOriginal` returns the correctly typed module. As a bonus, if you rename or move the file in your IDE, the import path will be updated automatically. If you use a string, you lose both the type safety and the automatic refactoring.
-:::
-
-Vitest has comprehensive guides for specific mocking scenarios:
-
-- [Mocking Functions](/guide/mocking/functions)
-- [Mocking Modules](/guide/mocking/modules)
-- [Mocking Timers](/guide/mocking/timers)
-- [Mocking Dates](/guide/mocking/dates)
-- [Mocking Globals](/guide/mocking/globals)
-- [Mocking Requests](/guide/mocking/requests)
-- [Mocking the File System](/guide/mocking/file-system)
-- [Mocking Classes](/guide/mocking/classes)