@vitest-agent/mcp 1.1.0 → 1.2.0

package/vendor/vitest-docs/api/expect.md

@@ -1,2304 +0,0 @@
-# expect
-
-The following types are used in the type signatures below
-
-```ts
-type Awaitable<T> = T | PromiseLike<T>
-```
-
-`expect` is used to create assertions. In this context `assertions` are functions that can be called to assert a statement. Vitest provides `chai` assertions by default and also `Jest` compatible assertions built on top of `chai`. Since Vitest 4.1, for spy/mock testing, Vitest also provides Chai-style assertions (e.g., [`expect(spy).to.have.been.called()`](#called)) alongside Jest-style assertions (e.g., `expect(spy).toHaveBeenCalled()`). Unlike `Jest`, Vitest supports a message as the second argument - if the assertion fails, the error message will be equal to it.
-
-```ts
-export interface ExpectStatic extends Chai.ExpectStatic, AsymmetricMatchersContaining {
-  <T>(actual: T, message?: string): Assertion<T>
-  extend: (expects: MatchersObject) => void
-  anything: () => any
-  any: (constructor: unknown) => any
-  getState: () => MatcherState
-  setState: (state: Partial<MatcherState>) => void
-  not: AsymmetricMatchersContaining
-}
-```
-
-For example, this code asserts that an `input` value is equal to `2`. If it's not, the assertion will throw an error, and the test will fail.
-
-```ts twoslash
-import { expect } from 'vitest'
-
-const input = Math.sqrt(4)
-
-expect(input).to.equal(2) // chai API
-expect(input).toBe(2) // jest API
-```
-
-Technically this example doesn't use [`test`](/api/test) function, so in the console you will see Node.js error instead of Vitest output. To learn more about `test`, please read [Test API Reference](/api/test).
-
-Also, `expect` can be used statically to access matcher functions, described later, and more.
-
-::: warning
-`expect` has no effect on testing types, if the expression doesn't have a type error. If you want to use Vitest as [type checker](/guide/testing-types), use [`expectTypeOf`](/api/expect-typeof) or [`assertType`](/api/assert-type).
-:::
-
-## assert
-
-- **Type:** `Chai.AssertStatic`
-
-Vitest reexports chai's [`assert` API](https://www.chaijs.com/api/assert/) as `expect.assert` for convenience. You can see the supported methods on the [Assert API page](/api/assert).
-
-This is especially useful if you need to narrow down the type, since `expect.to*` methods do not support that:
-
-```ts
-interface Cat {
-  __type: 'Cat'
-  mew(): void
-}
-interface Dog {
-  __type: 'Dog'
-  bark(): void
-}
-type Animal = Cat | Dog
-
-const animal: Animal = { __type: 'Dog', bark: () => {} }
-
-expect.assert(animal.__type === 'Dog')
-// does not show a type error!
-expect(animal.bark()).toBeUndefined()
-```
-
-::: tip
-Note that `expect.assert` also supports other type-narrowing methods (like `assert.isDefined`, `assert.exists` and so on).
-:::
-
-## soft
-
-- **Type:** `ExpectStatic & (actual: any) => Assertions`
-
-`expect.soft` functions similarly to `expect`, but instead of terminating the test execution upon a failed assertion, it continues running and marks the failure as a test failure. All errors encountered during the test will be displayed until the test is completed.
-
-```ts
-import { expect, test } from 'vitest'
-
-test('expect.soft test', () => {
-  expect.soft(1 + 1).toBe(3) // mark the test as fail and continue
-  expect.soft(1 + 2).toBe(4) // mark the test as fail and continue
-})
-// reporter will report both errors at the end of the run
-```
-
-It can also be used with `expect`. if `expect` assertion fails, the test will be terminated and all errors will be displayed.
-
-```ts
-import { expect, test } from 'vitest'
-
-test('expect.soft test', () => {
-  expect.soft(1 + 1).toBe(3) // mark the test as fail and continue
-  expect(1 + 2).toBe(4) // failed and terminate the test, all previous errors will be output
-  expect.soft(1 + 3).toBe(5) // do not run
-})
-```
-
-::: warning
-`expect.soft` can only be used inside the [`test`](/api/test) function.
-:::
-
-## poll
-
-```ts
-interface ExpectPoll extends ExpectStatic {
-  (actual: () => T, options?: { interval?: number; timeout?: number; message?: string }): Promise<Assertions<T>>
-}
-```
-
-`expect.poll` reruns the _assertion_ until it is succeeded. You can configure how many times Vitest should rerun the `expect.poll` callback by setting `interval` and `timeout` options.
-
-If an error is thrown inside the `expect.poll` callback, Vitest will retry again until the timeout runs out.
-
-```ts
-import { expect, test } from 'vitest'
-
-test('element exists', async () => {
-  asyncInjectElement()
-
-  await expect.poll(() => document.querySelector('.element')).toBeTruthy()
-})
-```
-
-::: warning
-`expect.poll` makes every assertion asynchronous, so you need to await it. Since Vitest 3, if you forget to await it, the test will fail with a warning to do so.
-
-`expect.poll` doesn't work with several matchers:
-
-- Snapshot matchers are not supported because they will always succeed. If your condition is flaky, consider using [`vi.waitFor`](/api/vi#vi-waitfor) instead to resolve it first:
-
-```ts
-import { expect, vi } from 'vitest'
-
-const flakyValue = await vi.waitFor(() => getFlakyValue())
-expect(flakyValue).toMatchSnapshot()
-```
-
-- `.resolves` and `.rejects` are not supported. `expect.poll` already awaits the condition if it's asynchronous.
-- `toThrow` and its aliases are not supported because the `expect.poll` condition is always resolved before the matcher gets the value
-:::
-
-## not
-
-Using `not` will negate the assertion. For example, this code asserts that an `input` value is not equal to `2`. If it's equal, the assertion will throw an error, and the test will fail.
-
-```ts
-import { expect, test } from 'vitest'
-
-const input = Math.sqrt(16)
-
-expect(input).not.to.equal(2) // chai API
-expect(input).not.toBe(2) // jest API
-```
-
-## toBe
-
-- **Type:** `(value: any) => Awaitable<void>`
-
-`toBe` can be used to assert if primitives are equal or that objects share the same reference. It is equivalent of calling `expect(Object.is(3, 3)).toBe(true)`. If the objects are not the same, but you want to check if their structures are identical, you can use [`toEqual`](#toequal).
-
-For example, the code below checks if the trader has 13 apples.
-
-```ts
-import { expect, test } from 'vitest'
-
-const stock = {
-  type: 'apples',
-  count: 13,
-}
-
-test('stock has 13 apples', () => {
-  expect(stock.type).toBe('apples')
-  expect(stock.count).toBe(13)
-})
-
-test('stocks are the same', () => {
-  const refStock = stock // same reference
-
-  expect(stock).toBe(refStock)
-})
-```
-
-Try not to use `toBe` with floating-point numbers. Since JavaScript rounds them, `0.1 + 0.2` is not strictly `0.3`. To reliably assert floating-point numbers, use [`toBeCloseTo`](#tobecloseto) assertion.
-
-## toBeCloseTo
-
-- **Type:** `(value: number, numDigits?: number) => Awaitable<void>`
-
-Use `toBeCloseTo` to compare floating-point numbers. The optional `numDigits` argument limits the number of digits to check _after_ the decimal point. The default for `numDigits` is 2. For example:
-
-```ts
-import { expect, test } from 'vitest'
-
-test.fails('decimals are not equal in javascript', () => {
-  expect(0.2 + 0.1).toBe(0.3) // 0.2 + 0.1 is 0.30000000000000004
-})
-
-test('decimals are rounded to 5 after the point', () => {
-  // 0.2 + 0.1 is 0.30000 | "000000000004" removed
-  expect(0.2 + 0.1).toBeCloseTo(0.3, 5)
-  // nothing from 0.30000000000000004 is removed
-  expect(0.2 + 0.1).not.toBeCloseTo(0.3, 50)
-})
-```
-
-## toBeDefined
-
-- **Type:** `() => Awaitable<void>`
-
-`toBeDefined` asserts that the value is not equal to `undefined`. Useful use case would be to check if function _returned_ anything.
-
-```ts
-import { expect, test } from 'vitest'
-
-function getApples() {
-  return 3
-}
-
-test('function returned something', () => {
-  expect(getApples()).toBeDefined()
-})
-```
-
-## toBeUndefined
-
-- **Type:** `() => Awaitable<void>`
-
-Opposite of `toBeDefined`, `toBeUndefined` asserts that the value _is_ equal to `undefined`. Useful use case would be to check if function hasn't _returned_ anything.
-
-```ts
-import { expect, test } from 'vitest'
-
-function getApplesFromStock(stock: string) {
-  if (stock === 'Bill') {
-    return 13
-  }
-}
-
-test('mary doesn\'t have a stock', () => {
-  expect(getApplesFromStock('Mary')).toBeUndefined()
-})
-```
-
-## toBeTruthy
-
-- **Type:** `() => Awaitable<void>`
-
-`toBeTruthy` asserts that the value is true when converted to boolean. Useful if you don't care for the value, but just want to know it can be converted to `true`.
-
-For example, having this code you don't care for the return value of `stocks.getInfo` - it maybe a complex object, a string, or anything else. The code will still work.
-
-```ts
-import { Stocks } from './stocks.js'
-
-const stocks = new Stocks()
-stocks.sync('Bill')
-if (stocks.getInfo('Bill')) {
-  stocks.sell('apples', 'Bill')
-}
-```
-
-So if you want to test that `stocks.getInfo` will be truthy, you could write:
-
-```ts
-import { expect, test } from 'vitest'
-import { Stocks } from './stocks.js'
-
-const stocks = new Stocks()
-
-test('if we know Bill stock, sell apples to him', () => {
-  stocks.sync('Bill')
-  expect(stocks.getInfo('Bill')).toBeTruthy()
-})
-```
-
-Everything in JavaScript is truthy, except `false`, `null`, `undefined`, `NaN`, `0`, `-0`, `0n`, `""` and `document.all`.
-
-## toBeFalsy
-
-- **Type:** `() => Awaitable<void>`
-
-`toBeFalsy` asserts that the value is false when converted to boolean. Useful if you don't care for the value, but just want to know if it can be converted to `false`.
-
-For example, having this code you don't care for the return value of `stocks.stockFailed` - it may return any falsy value, but the code will still work.
-
-```ts
-import { Stocks } from './stocks.js'
-
-const stocks = new Stocks()
-stocks.sync('Bill')
-if (!stocks.stockFailed('Bill')) {
-  stocks.sell('apples', 'Bill')
-}
-```
-
-So if you want to test that `stocks.stockFailed` will be falsy, you could write:
-
-```ts
-import { expect, test } from 'vitest'
-import { Stocks } from './stocks.js'
-
-const stocks = new Stocks()
-
-test('if Bill stock hasn\'t failed, sell apples to him', () => {
-  stocks.syncStocks('Bill')
-  expect(stocks.stockFailed('Bill')).toBeFalsy()
-})
-```
-
-Everything in JavaScript is truthy, except `false`, `null`, `undefined`, `NaN`, `0`, `-0`, `0n`, `""` and `document.all`.
-
-## toBeNull
-
-- **Type:** `() => Awaitable<void>`
-
-`toBeNull` simply asserts if something is `null`. Alias for `.toBe(null)`.
-
-```ts
-import { expect, test } from 'vitest'
-
-function apples() {
-  return null
-}
-
-test('we don\'t have apples', () => {
-  expect(apples()).toBeNull()
-})
-```
-
-## toBeNullable
-
-- **Type:** `() => Awaitable<void>`
-
-`toBeNullable` simply asserts if something is nullable (`null` or `undefined`).
-
-```ts
-import { expect, test } from 'vitest'
-
-function apples() {
-  return null
-}
-
-function bananas() {
-  return undefined
-}
-
-test('we don\'t have apples', () => {
-  expect(apples()).toBeNullable()
-})
-
-test('we don\'t have bananas', () => {
-  expect(bananas()).toBeNullable()
-})
-```
-
-## toBeNaN
-
-- **Type:** `() => Awaitable<void>`
-
-`toBeNaN` simply asserts if something is `NaN`. Alias for `.toBe(NaN)`.
-
-```ts
-import { expect, test } from 'vitest'
-
-let i = 0
-
-function getApplesCount() {
-  i++
-  return i > 1 ? Number.NaN : i
-}
-
-test('getApplesCount has some unusual side effects...', () => {
-  expect(getApplesCount()).not.toBeNaN()
-  expect(getApplesCount()).toBeNaN()
-})
-```
-
-## toBeOneOf
-
-- **Type:** `(sample: Array<any> | Set<any>) => any`
-
-`toBeOneOf` asserts if a value matches any of the values in the provided array or set.
-
-::: warning EXPERIMENTAL
-Providing a `Set` is an experimental feature and may change in a future release.
-:::
-
-```ts
-import { expect, test } from 'vitest'
-
-test('fruit is one of the allowed values', () => {
-  expect(fruit).toBeOneOf(['apple', 'banana', 'orange'])
-})
-```
-
-The asymmetric matcher is particularly useful when testing optional properties that could be either `null` or `undefined`:
-
-```ts
-test('optional properties can be null or undefined', () => {
-  const user = {
-    firstName: 'John',
-    middleName: undefined,
-    lastName: 'Doe'
-  }
-
-  expect(user).toEqual({
-    firstName: expect.any(String),
-    middleName: expect.toBeOneOf([expect.any(String), undefined]),
-    lastName: expect.any(String),
-  })
-})
-```
-
-:::tip
-You can use `expect.not` with this matcher to ensure a value does NOT match any of the provided options.
-:::
-
-## toBeTypeOf
-
-- **Type:** `(c: 'bigint' | 'boolean' | 'function' | 'number' | 'object' | 'string' | 'symbol' | 'undefined') => Awaitable<void>`
-
-`toBeTypeOf` asserts if an actual value is of type of received type.
-
-```ts
-import { expect, test } from 'vitest'
-
-const actual = 'stock'
-
-test('stock is type of string', () => {
-  expect(actual).toBeTypeOf('string')
-})
-```
-
-:::warning
-`toBeTypeOf` uses the native `typeof` operator under the hood with all its quirks, most notably that the value `null` has type `object`.
-
-```ts
-test('toBeTypeOf cannot check for null or array', () => {
-  expect(null).toBeTypeOf('object')
-  expect([]).toBeTypeOf('object')
-})
-```
-:::
-
-## toBeInstanceOf
-
-- **Type:** `(c: any) => Awaitable<void>`
-
-`toBeInstanceOf` asserts if an actual value is instance of received class.
-
-```ts
-import { expect, test } from 'vitest'
-import { Stocks } from './stocks.js'
-
-const stocks = new Stocks()
-
-test('stocks are instance of Stocks', () => {
-  expect(stocks).toBeInstanceOf(Stocks)
-})
-```
-
-## toBeGreaterThan
-
-- **Type:** `(n: number | bigint) => Awaitable<void>`
-
-`toBeGreaterThan` asserts if actual value is greater than received one. Equal values will fail the test.
-
-```ts
-import { expect, test } from 'vitest'
-import { getApples } from './stocks.js'
-
-test('have more then 10 apples', () => {
-  expect(getApples()).toBeGreaterThan(10)
-})
-```
-
-## toBeGreaterThanOrEqual
-
-- **Type:** `(n: number | bigint) => Awaitable<void>`
-
-`toBeGreaterThanOrEqual` asserts if actual value is greater than received one or equal to it.
-
-```ts
-import { expect, test } from 'vitest'
-import { getApples } from './stocks.js'
-
-test('have 11 apples or more', () => {
-  expect(getApples()).toBeGreaterThanOrEqual(11)
-})
-```
-
-## toBeLessThan
-
-- **Type:** `(n: number | bigint) => Awaitable<void>`
-
-`toBeLessThan` asserts if actual value is less than received one. Equal values will fail the test.
-
-```ts
-import { expect, test } from 'vitest'
-import { getApples } from './stocks.js'
-
-test('have less then 20 apples', () => {
-  expect(getApples()).toBeLessThan(20)
-})
-```
-
-## toBeLessThanOrEqual
-
-- **Type:** `(n: number | bigint) => Awaitable<void>`
-
-`toBeLessThanOrEqual` asserts if actual value is less than received one or equal to it.
-
-```ts
-import { expect, test } from 'vitest'
-import { getApples } from './stocks.js'
-
-test('have 11 apples or less', () => {
-  expect(getApples()).toBeLessThanOrEqual(11)
-})
-```
-
-## toEqual
-
-- **Type:** `(received: any) => Awaitable<void>`
-
-`toEqual` asserts if actual value is equal to received one or has the same structure, if it is an object (compares them recursively). You can see the difference between `toEqual` and [`toBe`](#tobe) in this example:
-
-```ts
-import { expect, test } from 'vitest'
-
-const stockBill = {
-  type: 'apples',
-  count: 13,
-}
-
-const stockMary = {
-  type: 'apples',
-  count: 13,
-}
-
-test('stocks have the same properties', () => {
-  expect(stockBill).toEqual(stockMary)
-})
-
-test('stocks are not the same', () => {
-  expect(stockBill).not.toBe(stockMary)
-})
-```
-
-:::warning
-For `Error` objects, non-enumerable properties such as `name`, `message`, `cause` and `AggregateError.errors` are also compared. For `Error.cause`, the comparison is done asymmetrically:
-
-```ts
-// success
-expect(new Error('hi', { cause: 'x' })).toEqual(new Error('hi'))
-
-// fail
-expect(new Error('hi')).toEqual(new Error('hi', { cause: 'x' }))
-```
-
-To test if something was thrown, use [`toThrow`](#tothrow) assertion.
-:::
-
-## toStrictEqual
-
-- **Type:** `(received: any) => Awaitable<void>`
-
-`toStrictEqual` asserts if the actual value is equal to the received one or has the same structure if it is an object (compares them recursively), and of the same type.
-
-Differences from [`.toEqual`](#toequal):
-
--  Keys with `undefined` properties are checked. e.g. `{a: undefined, b: 2}` does not match `{b: 2}` when using `.toStrictEqual`.
--  Array sparseness is checked. e.g. `[, 1]` does not match `[undefined, 1]` when using `.toStrictEqual`.
--  Object types are checked to be equal. e.g. A class instance with fields `a` and `b` will not equal a literal object with fields `a` and `b`.
-
-```ts
-import { expect, test } from 'vitest'
-
-class Stock {
-  constructor(type) {
-    this.type = type
-  }
-}
-
-test('structurally the same, but semantically different', () => {
-  expect(new Stock('apples')).toEqual({ type: 'apples' })
-  expect(new Stock('apples')).not.toStrictEqual({ type: 'apples' })
-})
-```
-
-## toContain
-
-- **Type:** `(received: string) => Awaitable<void>`
-
-`toContain` asserts if the actual value is in an array. `toContain` can also check whether a string is a substring of another string. If you are running tests in a browser-like environment, this assertion can also check if class is contained in a `classList`, or an element is inside another one.
-
-```ts
-import { expect, test } from 'vitest'
-import { getAllFruits } from './stocks.js'
-
-test('the fruit list contains orange', () => {
-  expect(getAllFruits()).toContain('orange')
-})
-
-test('pineapple contains apple', () => {
-  expect('pineapple').toContain('apple')
-})
-
-test('the element contains a class and is contained', () => {
-  const element = document.querySelector('#el')
-  // element has a class
-  expect(element.classList).toContain('flex')
-  // element is inside another one
-  expect(document.querySelector('#wrapper')).toContain(element)
-})
-```
-
-## toContainEqual
-
-- **Type:** `(received: any) => Awaitable<void>`
-
-`toContainEqual` asserts if an item with a specific structure and values is contained in an array.
-It works like [`toEqual`](#toequal) inside for each element.
-
-```ts
-import { expect, test } from 'vitest'
-import { getFruitStock } from './stocks.js'
-
-test('apple available', () => {
-  expect(getFruitStock()).toContainEqual({ fruit: 'apple', count: 5 })
-})
-```
-
-## toHaveLength
-
-- **Type:** `(received: number) => Awaitable<void>`
-
-`toHaveLength` asserts if an object has a `.length` property and it is set to a certain numeric value.
-
-```ts
-import { expect, test } from 'vitest'
-
-test('toHaveLength', () => {
-  expect('abc').toHaveLength(3)
-  expect([1, 2, 3]).toHaveLength(3)
-
-  expect('').not.toHaveLength(3) // doesn't have .length of 3
-  expect({ length: 3 }).toHaveLength(3)
-})
-```
-
-## toHaveProperty
-
-- **Type:** `(key: any, received?: any) => Awaitable<void>`
-
-`toHaveProperty` asserts if a property at provided reference `key` exists for an object.
-
-You can provide an optional value argument also known as deep equality, like the `toEqual` matcher to compare the received property value.
-
-```ts
-import { expect, test } from 'vitest'
-
-const invoice = {
-  'isActive': true,
-  'P.O': '12345',
-  'customer': {
-    first_name: 'John',
-    last_name: 'Doe',
-    location: 'China',
-  },
-  'total_amount': 5000,
-  'items': [
-    {
-      type: 'apples',
-      quantity: 10,
-    },
-    {
-      type: 'oranges',
-      quantity: 5,
-    },
-  ],
-}
-
-test('John Doe Invoice', () => {
-  expect(invoice).toHaveProperty('isActive') // assert that the key exists
-  expect(invoice).toHaveProperty('total_amount', 5000) // assert that the key exists and the value is equal
-
-  expect(invoice).not.toHaveProperty('account') // assert that this key does not exist
-
-  // Deep referencing using dot notation
-  expect(invoice).toHaveProperty('customer.first_name')
-  expect(invoice).toHaveProperty('customer.last_name', 'Doe')
-  expect(invoice).not.toHaveProperty('customer.location', 'India')
-
-  // Deep referencing using an array containing the key
-  expect(invoice).toHaveProperty('items[0].type', 'apples')
-  expect(invoice).toHaveProperty('items.0.type', 'apples') // dot notation also works
-
-  // Deep referencing using an array containing the keyPath
-  expect(invoice).toHaveProperty(['items', 0, 'type'], 'apples')
-  expect(invoice).toHaveProperty(['items', '0', 'type'], 'apples') // string notation also works
-
-  // Wrap your key in an array to avoid the key from being parsed as a deep reference
-  expect(invoice).toHaveProperty(['P.O'], '12345')
-
-  // Deep equality of object property
-  expect(invoice).toHaveProperty('items[0]', { type: 'apples', quantity: 10 })
-})
-```
-
-## toMatch
-
-- **Type:** `(received: string | regexp) => Awaitable<void>`
-
-`toMatch` asserts if a string matches a regular expression or a string.
-
-```ts
-import { expect, test } from 'vitest'
-
-test('top fruits', () => {
-  expect('top fruits include apple, orange and grape').toMatch(/apple/)
-  expect('applefruits').toMatch('fruit') // toMatch also accepts a string
-})
-```
-
-## toMatchObject
-
-- **Type:** `(received: object | array) => Awaitable<void>`
-
-`toMatchObject` asserts if an object matches a subset of the properties of an object.
-
-You can also pass an array of objects. This is useful if you want to check that two arrays match in their number and order of elements, as opposed to `arrayContaining`, which allows for extra elements in the received array.
-
-```ts
-import { expect, test } from 'vitest'
-
-const johnInvoice = {
-  isActive: true,
-  customer: {
-    first_name: 'John',
-    last_name: 'Doe',
-    location: 'China',
-  },
-  total_amount: 5000,
-  items: [
-    {
-      type: 'apples',
-      quantity: 10,
-    },
-    {
-      type: 'oranges',
-      quantity: 5,
-    },
-  ],
-}
-
-const johnDetails = {
-  customer: {
-    first_name: 'John',
-    last_name: 'Doe',
-    location: 'China',
-  },
-}
-
-test('invoice has john personal details', () => {
-  expect(johnInvoice).toMatchObject(johnDetails)
-})
-
-test('the number of elements must match exactly', () => {
-  // Assert that an array of object matches
-  expect([{ foo: 'bar' }, { baz: 1 }]).toMatchObject([
-    { foo: 'bar' },
-    { baz: 1 },
-  ])
-})
-```
-
-## toThrow
-
-- **Type:** `(expected?: any) => Awaitable<void>`
-
-- **Alias:** `toThrowError` <Deprecated />
-
-`toThrow` asserts if a function throws an error when it is called.
-
-You can provide an optional argument to test that a specific error is thrown:
-
-- `RegExp`: error message matches the pattern
-- `string`: error message includes the substring
-- any other value: compare with thrown value using deep equality (similar to `toEqual`)
-
-:::tip
-You must wrap the code in a function, otherwise the error will not be caught, and test will fail.
-
-This does not apply for async calls as [rejects](#rejects) correctly unwraps the promise:
-```ts
-test('expect rejects toThrow', async ({ expect }) => {
-  const promise = Promise.reject(new Error('Test'))
-  await expect(promise).rejects.toThrow()
-})
-```
-:::
-
-For example, if we want to test that `getFruitStock('pineapples')` throws, we could write:
-
-```ts
-import { expect, test } from 'vitest'
-
-function getFruitStock(type: string) {
-  if (type === 'pineapples') {
-    throw new Error('Pineapples are not in stock')
-  }
-
-  // Do some other stuff
-}
-
-test('throws on pineapples', () => {
-  // Test that the error message says "stock" somewhere: these are equivalent
-  expect(() => getFruitStock('pineapples')).toThrow(/stock/)
-  expect(() => getFruitStock('pineapples')).toThrow('stock')
-
-  // Test the exact error message
-  expect(() => getFruitStock('pineapples')).toThrow(
-    /^Pineapples are not in stock$/,
-  )
-
-  expect(() => getFruitStock('pineapples')).toThrow(
-    new Error('Pineapples are not in stock'),
-  )
-  expect(() => getFruitStock('pineapples')).toThrow(expect.objectContaining({
-    message: 'Pineapples are not in stock',
-  }))
-})
-```
-
-:::tip
-To test async functions, use in combination with [rejects](#rejects).
-
-```js
-function getAsyncFruitStock() {
-  return Promise.reject(new Error('empty'))
-}
-
-test('throws on pineapples', async () => {
-  await expect(() => getAsyncFruitStock()).rejects.toThrow('empty')
-})
-```
-:::
-
-:::tip
-You can also test non-Error values that are thrown:
-
-```ts
-test('throws non-Error values', () => {
-  expect(() => { throw 42 }).toThrow(42)
-  expect(() => { throw { message: 'error' } }).toThrow({ message: 'error' })
-})
-```
-:::
-
-:::warning Unhandled Rejections with Fake Timers
-When using fake timers, an async function that rejects _during_ a `vi.advanceTimersByTimeAsync` call will trigger an [unhandled rejection](https://nodejs.org/api/process.html#event-unhandledrejection) — even if you later assert it with `.rejects.toThrow()`. This happens because the error is thrown before the `expect` chain has a chance to catch it.
-
-```ts
-async function foo() {
-  await new Promise(resolve => setTimeout(resolve, 100))
-  throw new Error('boom')
-}
-
-test('rejects', async () => {
-  const result = foo()
-
-  await vi.advanceTimersByTimeAsync(100)
-
-  // The assertion passes, but the error was already "unhandled" during advanceTimersByTimeAsync
-  await expect(result).rejects.toThrow()
-})
-```
-
-To avoid this, prefer [`vi.setTimerTickMode('nextTimerAsync')`](/api/vi#vi-settimertickmode) so that timers tick automatically as promises settle, without needing a manual advance:
-
-```ts
-beforeEach(() => {
-  vi.useFakeTimers()
-  vi.setTimerTickMode('nextTimerAsync')
-})
-
-test('rejects', async () => {
-  // No advanceTimersByTimeAsync needed — the error is caught by rejects.toThrow()
-  await expect(foo()).rejects.toThrow('boom')
-})
-```
-
-Alternatively, set up the `.rejects.toThrow()` assertion _before_ advancing timers so the rejection is handled immediately:
-
-```ts
-test('rejects', async () => {
-  const result = foo()
-  const assertion = expect(result).rejects.toThrow('boom')
-
-  await vi.advanceTimersByTimeAsync(100)
-  await assertion
-})
-```
-:::
-
-## toMatchSnapshot
-
-- **Type:** `<T>(shape?: Partial<T> | string, hint?: string) => void`
-
-This ensures that a value matches the most recent snapshot.
-
-You can provide an optional `hint` string argument that is appended to the test name. Although Vitest always appends a number at the end of a snapshot name, short descriptive hints might be more useful than numbers to differentiate multiple snapshots in a single it or test block. Vitest sorts snapshots by name in the corresponding `.snap` file.
-
-:::tip
-  When a snapshot mismatches and causes the test to fail, if the mismatch is expected, you can press `u` key to update the snapshot once. Or you can pass `-u` or `--update` CLI options to make Vitest always update the tests.
-:::
-
-```ts
-import { expect, test } from 'vitest'
-
-test('matches snapshot', () => {
-  const data = { foo: new Set(['bar', 'snapshot']) }
-  expect(data).toMatchSnapshot()
-})
-```
-
-You can also provide a shape of an object, if you are testing just a shape of an object, and don't need it to be 100% compatible:
-
-```ts
-import { expect, test } from 'vitest'
-
-test('matches snapshot', () => {
-  const data = { foo: new Set(['bar', 'snapshot']) }
-  expect(data).toMatchSnapshot({ foo: expect.any(Set) })
-})
-```
-
-## toMatchInlineSnapshot
-
-- **Type:** `<T>(shape?: Partial<T> | string, snapshot?: string, hint?: string) => void`
-
-This ensures that a value matches the most recent snapshot.
-
-Vitest adds and updates the inlineSnapshot string argument to the matcher in the test file (instead of an external `.snap` file).
-
-```ts
-import { expect, test } from 'vitest'
-
-test('matches inline snapshot', () => {
-  const data = { foo: new Set(['bar', 'snapshot']) }
-  // Vitest will update following content when updating the snapshot
-  expect(data).toMatchInlineSnapshot(`
-    {
-      "foo": Set {
-        "bar",
-        "snapshot",
-      },
-    }
-  `)
-})
-```
-
-You can also provide a shape of an object, if you are testing just a shape of an object, and don't need it to be 100% compatible:
-
-```ts
-import { expect, test } from 'vitest'
-
-test('matches snapshot', () => {
-  const data = { foo: new Set(['bar', 'snapshot']) }
-  expect(data).toMatchInlineSnapshot(
-    { foo: expect.any(Set) },
-    `
-    {
-      "foo": Any<Set>,
-    }
-  `
-  )
-})
-```
-
-## toMatchFileSnapshot {#tomatchfilesnapshot}
-
-- **Type:** `<T>(filepath: string, hint?: string) => Promise<void>`
-
-Compare or update the snapshot with the content of a file explicitly specified (instead of the `.snap` file).
-
-```ts
-import { expect, it } from 'vitest'
-
-it('render basic', async () => {
-  const result = renderHTML(h('div', { class: 'foo' }))
-  await expect(result).toMatchFileSnapshot('./test/basic.output.html')
-})
-```
-
-Note that since file system operation is async, you need to use `await` with `toMatchFileSnapshot()`. If `await` is not used, Vitest treats it like `expect.soft`, meaning the code after the statement will continue to run even if the snapshot mismatches. After the test finishes, Vitest will check the snapshot and fail if there is a mismatch.
-
-## toThrowErrorMatchingSnapshot
-
-- **Type:** `(hint?: string) => void`
-
-The same as [`toMatchSnapshot`](#tomatchsnapshot), but expects the same value as [`toThrow`](#tothrow).
-
-## toThrowErrorMatchingInlineSnapshot
-
-- **Type:** `(snapshot?: string, hint?: string) => void`
-
-The same as [`toMatchInlineSnapshot`](#tomatchinlinesnapshot), but expects the same value as [`toThrow`](#tothrow).
-
-## toMatchAriaSnapshot <Version type="experimental">4.1.4</Version> <Experimental /> {#tomatcharisnapshot}
-
-- **Type:** `() => void`
-
-Captures the accessibility tree of a DOM element and generate a snapshot file or compares it against a stored snapshot. See the [ARIA Snapshots guide](/guide/browser/aria-snapshots) for more details.
-
-```ts
-import { expect, test } from 'vitest'
-
-test('navigation accessibility', () => {
-  document.body.innerHTML = `
-    <nav aria-label="Actions">
-      <button>Save</button>
-      <button>Cancel</button>
-    </nav>
-  `
-  expect(document.querySelector('nav')).toMatchAriaSnapshot()
-})
-```
-
-## toMatchAriaInlineSnapshot <Version type="experimental">4.1.4</Version> <Experimental /> {#tomatchariainlinesnapshot}
-
-- **Type:** `(snapshot?: string) => void`
-
-Same as [`toMatchAriaSnapshot`](#tomatcharisnapshot), but stores the snapshot inline in the test file. See the [ARIA Snapshots guide](/guide/browser/aria-snapshots) for more details.
-
-```ts
-import { expect, test } from 'vitest'
-
-test('user profile', () => {
-  expect(document.body).toMatchAriaInlineSnapshot(`
-    - heading "Dashboard" [level=1]
-    - button /User \\d+/: Profile
-  `)
-})
-```
-
-## toHaveBeenCalled
-
-- **Type:** `() => Awaitable<void>`
-
-This assertion is useful for testing that a function has been called. Requires a spy function to be passed to `expect`.
-
-```ts
-import { expect, test, vi } from 'vitest'
-
-const market = {
-  buy(subject: string, amount: number) {
-    // ...
-  },
-}
-
-test('spy function', () => {
-  const buySpy = vi.spyOn(market, 'buy')
-
-  expect(buySpy).not.toHaveBeenCalled()
-
-  market.buy('apples', 10)
-
-  expect(buySpy).toHaveBeenCalled()
-})
-```
-
-## toHaveBeenCalledTimes
-
-- **Type:** `(amount: number) => Awaitable<void>`
-
-This assertion checks if a function was called a certain amount of times. Requires a spy function to be passed to `expect`.
-
-```ts
-import { expect, test, vi } from 'vitest'
-
-const market = {
-  buy(subject: string, amount: number) {
-    // ...
-  },
-}
-
-test('spy function called two times', () => {
-  const buySpy = vi.spyOn(market, 'buy')
-
-  market.buy('apples', 10)
-  market.buy('apples', 20)
-
-  expect(buySpy).toHaveBeenCalledTimes(2)
-})
-```
-
-## toHaveBeenCalledWith
-
-- **Type:** `(...args: any[]) => Awaitable<void>`
-
-This assertion checks if a function was called at least once with certain parameters. Requires a spy function to be passed to `expect`.
-
-```ts
-import { expect, test, vi } from 'vitest'
-
-const market = {
-  buy(subject: string, amount: number) {
-    // ...
-  },
-}
-
-test('spy function', () => {
-  const buySpy = vi.spyOn(market, 'buy')
-
-  market.buy('apples', 10)
-  market.buy('apples', 20)
-
-  expect(buySpy).toHaveBeenCalledWith('apples', 10)
-  expect(buySpy).toHaveBeenCalledWith('apples', 20)
-})
-```
-
-## toHaveBeenCalledBefore
-
-- **Type:** `(mock: MockInstance, failIfNoFirstInvocation?: boolean) => Awaitable<void>`
-
-This assertion checks if a `Mock` was called before another `Mock`.
-
-```ts
-test('calls mock1 before mock2', () => {
-  const mock1 = vi.fn()
-  const mock2 = vi.fn()
-
-  mock1()
-  mock2()
-  mock1()
-
-  expect(mock1).toHaveBeenCalledBefore(mock2)
-})
-```
-
-## toHaveBeenCalledAfter
-
-- **Type:** `(mock: MockInstance, failIfNoFirstInvocation?: boolean) => Awaitable<void>`
-
-This assertion checks if a `Mock` was called after another `Mock`.
-
-```ts
-test('calls mock1 after mock2', () => {
-  const mock1 = vi.fn()
-  const mock2 = vi.fn()
-
-  mock2()
-  mock1()
-  mock2()
-
-  expect(mock1).toHaveBeenCalledAfter(mock2)
-})
-```
-
-## toHaveBeenCalledExactlyOnceWith
-
-- **Type:** `(...args: any[]) => Awaitable<void>`
-
-This assertion checks if a function was called exactly once and with certain parameters. Requires a spy function to be passed to `expect`.
-
-```ts
-import { expect, test, vi } from 'vitest'
-
-const market = {
-  buy(subject: string, amount: number) {
-    // ...
-  },
-}
-
-test('spy function', () => {
-  const buySpy = vi.spyOn(market, 'buy')
-
-  market.buy('apples', 10)
-
-  expect(buySpy).toHaveBeenCalledExactlyOnceWith('apples', 10)
-})
-```
-
-## toHaveBeenLastCalledWith
-
-- **Type:** `(...args: any[]) => Awaitable<void>`
-
-This assertion checks if a function was called with certain parameters at its last invocation. Requires a spy function to be passed to `expect`.
-
-```ts
-import { expect, test, vi } from 'vitest'
-
-const market = {
-  buy(subject: string, amount: number) {
-    // ...
-  },
-}
-
-test('spy function', () => {
-  const buySpy = vi.spyOn(market, 'buy')
-
-  market.buy('apples', 10)
-  market.buy('apples', 20)
-
-  expect(buySpy).not.toHaveBeenLastCalledWith('apples', 10)
-  expect(buySpy).toHaveBeenLastCalledWith('apples', 20)
-})
-```
-
-## toHaveBeenNthCalledWith
-
-- **Type:** `(time: number, ...args: any[]) => Awaitable<void>`
-
-This assertion checks if a function was called with certain parameters at the certain time. The count starts at 1. So, to check the second entry, you would write `.toHaveBeenNthCalledWith(2, ...)`.
-
-Requires a spy function to be passed to `expect`.
-
-```ts
-import { expect, test, vi } from 'vitest'
-
-const market = {
-  buy(subject: string, amount: number) {
-    // ...
-  },
-}
-
-test('first call of spy function called with right params', () => {
-  const buySpy = vi.spyOn(market, 'buy')
-
-  market.buy('apples', 10)
-  market.buy('apples', 20)
-
-  expect(buySpy).toHaveBeenNthCalledWith(1, 'apples', 10)
-})
-```
-
-## toHaveReturned
-
-- **Type:** `() => Awaitable<void>`
-
-This assertion checks if a function has successfully returned a value at least once (i.e., did not throw an error). Requires a spy function to be passed to `expect`.
-
-```ts
-import { expect, test, vi } from 'vitest'
-
-function getApplesPrice(amount: number) {
-  const PRICE = 10
-  return amount * PRICE
-}
-
-test('spy function returned a value', () => {
-  const getPriceSpy = vi.fn(getApplesPrice)
-
-  const price = getPriceSpy(10)
-
-  expect(price).toBe(100)
-  expect(getPriceSpy).toHaveReturned()
-})
-```
-
-## toHaveReturnedTimes
-
-- **Type:** `(amount: number) => Awaitable<void>`
-
-This assertion checks if a function has successfully returned a value an exact amount of times (i.e., did not throw an error). Requires a spy function to be passed to `expect`.
-
-```ts
-import { expect, test, vi } from 'vitest'
-
-test('spy function returns a value two times', () => {
-  const sell = vi.fn((product: string) => ({ product }))
-
-  sell('apples')
-  sell('bananas')
-
-  expect(sell).toHaveReturnedTimes(2)
-})
-```
-
-## toHaveReturnedWith
-
-- **Type:** `(returnValue: any) => Awaitable<void>`
-
-You can call this assertion to check if a function has successfully returned a value with certain parameters at least once. Requires a spy function to be passed to `expect`.
-
-```ts
-import { expect, test, vi } from 'vitest'
-
-test('spy function returns a product', () => {
-  const sell = vi.fn((product: string) => ({ product }))
-
-  sell('apples')
-
-  expect(sell).toHaveReturnedWith({ product: 'apples' })
-})
-```
-
-## toHaveLastReturnedWith
-
-- **Type:** `(returnValue: any) => Awaitable<void>`
-
-You can call this assertion to check if a function has successfully returned a certain value when it was last invoked. Requires a spy function to be passed to `expect`.
-
-```ts
-import { expect, test, vi } from 'vitest'
-
-test('spy function returns bananas on a last call', () => {
-  const sell = vi.fn((product: string) => ({ product }))
-
-  sell('apples')
-  sell('bananas')
-
-  expect(sell).toHaveLastReturnedWith({ product: 'bananas' })
-})
-```
-
-## toHaveNthReturnedWith
-
-- **Type:** `(time: number, returnValue: any) => Awaitable<void>`
-
-You can call this assertion to check if a function has successfully returned a value with certain parameters on a certain call. Requires a spy function to be passed to `expect`.
-
-The count starts at 1. So, to check the second entry, you would write `.toHaveNthReturnedWith(2, ...)`.
-
-```ts
-import { expect, test, vi } from 'vitest'
-
-test('spy function returns bananas on second call', () => {
-  const sell = vi.fn((product: string) => ({ product }))
-
-  sell('apples')
-  sell('bananas')
-
-  expect(sell).toHaveNthReturnedWith(2, { product: 'bananas' })
-})
-```
-
-## toHaveResolved
-
-- **Type:** `() => Awaitable<void>`
-
-This assertion checks if a function has successfully resolved a value at least once (i.e., did not reject). Requires a spy function to be passed to `expect`.
-
-If the function returned a promise, but it was not resolved yet, this will fail.
-
-```ts
-import { expect, test, vi } from 'vitest'
-import db from './db/apples.js'
-
-async function getApplesPrice(amount: number) {
-  return amount * await db.get('price')
-}
-
-test('spy function resolved a value', async () => {
-  const getPriceSpy = vi.fn(getApplesPrice)
-
-  const price = await getPriceSpy(10)
-
-  expect(price).toBe(100)
-  expect(getPriceSpy).toHaveResolved()
-})
-```
-
-## toHaveResolvedTimes
-
-- **Type:** `(amount: number) => Awaitable<void>`
-
-This assertion checks if a function has successfully resolved a value an exact amount of times (i.e., did not reject). Requires a spy function to be passed to `expect`.
-
-This will only count resolved promises. If the function returned a promise, but it was not resolved yet, it will not be counted.
-
-```ts
-import { expect, test, vi } from 'vitest'
-
-test('spy function resolved a value two times', async () => {
-  const sell = vi.fn((product: string) => Promise.resolve({ product }))
-
-  await sell('apples')
-  await sell('bananas')
-
-  expect(sell).toHaveResolvedTimes(2)
-})
-```
-
-## toHaveResolvedWith
-
-- **Type:** `(returnValue: any) => Awaitable<void>`
-
-You can call this assertion to check if a function has successfully resolved a certain value at least once. Requires a spy function to be passed to `expect`.
-
-If the function returned a promise, but it was not resolved yet, this will fail.
-
-```ts
-import { expect, test, vi } from 'vitest'
-
-test('spy function resolved a product', async () => {
-  const sell = vi.fn((product: string) => Promise.resolve({ product }))
-
-  await sell('apples')
-
-  expect(sell).toHaveResolvedWith({ product: 'apples' })
-})
-```
-
-## toHaveLastResolvedWith
-
-- **Type:** `(returnValue: any) => Awaitable<void>`
-
-You can call this assertion to check if a function has successfully resolved a certain value when it was last invoked. Requires a spy function to be passed to `expect`.
-
-If the function returned a promise, but it was not resolved yet, this will fail.
-
-```ts
-import { expect, test, vi } from 'vitest'
-
-test('spy function resolves bananas on a last call', async () => {
-  const sell = vi.fn((product: string) => Promise.resolve({ product }))
-
-  await sell('apples')
-  await sell('bananas')
-
-  expect(sell).toHaveLastResolvedWith({ product: 'bananas' })
-})
-```
-
-## toHaveNthResolvedWith
-
-- **Type:** `(time: number, returnValue: any) => Awaitable<void>`
-
-You can call this assertion to check if a function has successfully resolved a certain value on a specific invocation. Requires a spy function to be passed to `expect`.
-
-If the function returned a promise, but it was not resolved yet, this will fail.
-
-The count starts at 1. So, to check the second entry, you would write `.toHaveNthResolvedWith(2, ...)`.
-
-```ts
-import { expect, test, vi } from 'vitest'
-
-test('spy function returns bananas on second call', async () => {
-  const sell = vi.fn((product: string) => Promise.resolve({ product }))
-
-  await sell('apples')
-  await sell('bananas')
-
-  expect(sell).toHaveNthResolvedWith(2, { product: 'bananas' })
-})
-```
-
-## called <Version>4.1.0</Version> {#called}
-
-- **Type:** `Assertion` (property, not a method)
-
-Chai-style assertion that checks if a spy was called at least once. This is equivalent to `toHaveBeenCalled()`.
-
-::: tip
-This is a property assertion following sinon-chai conventions. Access it without parentheses: `expect(spy).to.have.been.called`
-:::
-
-```ts
-import { expect, test, vi } from 'vitest'
-
-test('spy was called', () => {
-  const spy = vi.fn()
-
-  spy()
-
-  expect(spy).to.have.been.called
-  expect(spy).to.not.have.been.called // negation
-})
-```
-
-## callCount <Version>4.1.0</Version> {#callcount}
-
-- **Type:** `(count: number) => void`
-
-Chai-style assertion that checks if a spy was called a specific number of times. This is equivalent to `toHaveBeenCalledTimes(count)`.
-
-```ts
-import { expect, test, vi } from 'vitest'
-
-test('spy call count', () => {
-  const spy = vi.fn()
-
-  spy()
-  spy()
-  spy()
-
-  expect(spy).to.have.callCount(3)
-})
-```
-
-## calledWith <Version>4.1.0</Version> {#calledwith}
-
-- **Type:** `(...args: any[]) => void`
-
-Chai-style assertion that checks if a spy was called with specific arguments at least once. This is equivalent to `toHaveBeenCalledWith(...args)`.
-
-```ts
-import { expect, test, vi } from 'vitest'
-
-test('spy called with arguments', () => {
-  const spy = vi.fn()
-
-  spy('apple', 10)
-  spy('banana', 20)
-
-  expect(spy).to.have.been.calledWith('apple', 10)
-  expect(spy).to.have.been.calledWith('banana', 20)
-})
-```
-
-## calledOnce <Version>4.1.0</Version> {#calledonce}
-
-- **Type:** `Assertion` (property, not a method)
-
-Chai-style assertion that checks if a spy was called exactly once. This is equivalent to `toHaveBeenCalledOnce()`.
-
-::: tip
-This is a property assertion following sinon-chai conventions. Access it without parentheses: `expect(spy).to.have.been.calledOnce`
-:::
-
-```ts
-import { expect, test, vi } from 'vitest'
-
-test('spy called once', () => {
-  const spy = vi.fn()
-
-  spy()
-
-  expect(spy).to.have.been.calledOnce
-})
-```
-
-## calledOnceWith <Version>4.1.0</Version> {#calledoncewith}
-
-- **Type:** `(...args: any[]) => void`
-
-Chai-style assertion that checks if a spy was called exactly once with specific arguments. This is equivalent to `toHaveBeenCalledExactlyOnceWith(...args)`.
-
-```ts
-import { expect, test, vi } from 'vitest'
-
-test('spy called once with arguments', () => {
-  const spy = vi.fn()
-
-  spy('apple', 10)
-
-  expect(spy).to.have.been.calledOnceWith('apple', 10)
-})
-```
-
-## calledTwice <Version>4.1.0</Version> {#calledtwice}
-
-- **Type:** `Assertion` (property, not a method)
-
-Chai-style assertion that checks if a spy was called exactly twice. This is equivalent to `toHaveBeenCalledTimes(2)`.
-
-::: tip
-This is a property assertion following sinon-chai conventions. Access it without parentheses: `expect(spy).to.have.been.calledTwice`
-:::
-
-```ts
-import { expect, test, vi } from 'vitest'
-
-test('spy called twice', () => {
-  const spy = vi.fn()
-
-  spy()
-  spy()
-
-  expect(spy).to.have.been.calledTwice
-})
-```
-
-## calledThrice <Version>4.1.0</Version> {#calledthrice}
-
-- **Type:** `Assertion` (property, not a method)
-
-Chai-style assertion that checks if a spy was called exactly three times. This is equivalent to `toHaveBeenCalledTimes(3)`.
-
-::: tip
-This is a property assertion following sinon-chai conventions. Access it without parentheses: `expect(spy).to.have.been.calledThrice`
-:::
-
-```ts
-import { expect, test, vi } from 'vitest'
-
-test('spy called thrice', () => {
-  const spy = vi.fn()
-
-  spy()
-  spy()
-  spy()
-
-  expect(spy).to.have.been.calledThrice
-})
-```
-
-## lastCalledWith
-
-- **Type:** `(...args: any[]) => void`
-
-Chai-style assertion that checks if the last call to a spy was made with specific arguments. This is equivalent to `toHaveBeenLastCalledWith(...args)`.
-
-```ts
-import { expect, test, vi } from 'vitest'
-
-test('spy last called with', () => {
-  const spy = vi.fn()
-
-  spy('apple', 10)
-  spy('banana', 20)
-
-  expect(spy).to.have.been.lastCalledWith('banana', 20)
-})
-```
-
-## nthCalledWith
-
-- **Type:** `(n: number, ...args: any[]) => void`
-
-Chai-style assertion that checks if the nth call to a spy was made with specific arguments. This is equivalent to `toHaveBeenNthCalledWith(n, ...args)`.
-
-```ts
-import { expect, test, vi } from 'vitest'
-
-test('spy nth called with', () => {
-  const spy = vi.fn()
-
-  spy('apple', 10)
-  spy('banana', 20)
-  spy('cherry', 30)
-
-  expect(spy).to.have.been.nthCalledWith(2, 'banana', 20)
-})
-```
-
-## returned <Version>4.1.0</Version> {#returned}
-
-- **Type:** `(value: any) => void`
-
-Chai-style assertion that checks if a spy returned a specific value at least once. This is equivalent to `toHaveReturnedWith(value)`.
-
-```ts
-import { expect, test, vi } from 'vitest'
-
-test('spy returned', () => {
-  const spy = vi.fn(() => 'value')
-
-  spy()
-
-  expect(spy).to.have.returned('value')
-})
-```
-
-## returnedWith <Version>4.1.0</Version> {#returnedwith}
-
-- **Type:** `(value: any) => void`
-
-Chai-style assertion that checks if a spy returned a specific value at least once. This is equivalent to `toHaveReturnedWith(value)`.
-
-```ts
-import { expect, test, vi } from 'vitest'
-
-test('spy returned with value', () => {
-  const spy = vi.fn()
-    .mockReturnValueOnce('apple')
-    .mockReturnValueOnce('banana')
-
-  spy()
-  spy()
-
-  expect(spy).to.have.returnedWith('apple')
-  expect(spy).to.have.returnedWith('banana')
-})
-```
-
-## returnedTimes <Version>4.1.0</Version> {#returnedtimes}
-
-- **Type:** `(count: number) => void`
-
-Chai-style assertion that checks if a spy returned successfully a specific number of times. This is equivalent to `toHaveReturnedTimes(count)`.
-
-```ts
-import { expect, test, vi } from 'vitest'
-
-test('spy returned times', () => {
-  const spy = vi.fn(() => 'result')
-
-  spy()
-  spy()
-  spy()
-
-  expect(spy).to.have.returnedTimes(3)
-})
-```
-
-## lastReturnedWith
-
-- **Type:** `(value: any) => void`
-
-Chai-style assertion that checks if the last return value of a spy matches the expected value. This is equivalent to `toHaveLastReturnedWith(value)`.
-
-```ts
-import { expect, test, vi } from 'vitest'
-
-test('spy last returned with', () => {
-  const spy = vi.fn()
-    .mockReturnValueOnce('apple')
-    .mockReturnValueOnce('banana')
-
-  spy()
-  spy()
-
-  expect(spy).to.have.lastReturnedWith('banana')
-})
-```
-
-## nthReturnedWith
-
-- **Type:** `(n: number, value: any) => void`
-
-Chai-style assertion that checks if the nth return value of a spy matches the expected value. This is equivalent to `toHaveNthReturnedWith(n, value)`.
-
-```ts
-import { expect, test, vi } from 'vitest'
-
-test('spy nth returned with', () => {
-  const spy = vi.fn()
-    .mockReturnValueOnce('apple')
-    .mockReturnValueOnce('banana')
-    .mockReturnValueOnce('cherry')
-
-  spy()
-  spy()
-  spy()
-
-  expect(spy).to.have.nthReturnedWith(2, 'banana')
-})
-```
-
-## calledBefore <Version>4.1.0</Version> {#calledbefore}
-
-- **Type:** `(mock: MockInstance, failIfNoFirstInvocation?: boolean) => void`
-
-Chai-style assertion that checks if a spy was called before another spy. This is equivalent to `toHaveBeenCalledBefore(mock, failIfNoFirstInvocation)`.
-
-```ts
-import { expect, test, vi } from 'vitest'
-
-test('spy called before another', () => {
-  const spy1 = vi.fn()
-  const spy2 = vi.fn()
-
-  spy1()
-  spy2()
-
-  expect(spy1).to.have.been.calledBefore(spy2)
-})
-```
-
-## calledAfter <Version>4.1.0</Version> {#calledafter}
-
-- **Type:** `(mock: MockInstance, failIfNoFirstInvocation?: boolean) => void`
-
-Chai-style assertion that checks if a spy was called after another spy. This is equivalent to `toHaveBeenCalledAfter(mock, failIfNoFirstInvocation)`.
-
-```ts
-import { expect, test, vi } from 'vitest'
-
-test('spy called after another', () => {
-  const spy1 = vi.fn()
-  const spy2 = vi.fn()
-
-  spy1()
-  spy2()
-
-  expect(spy2).to.have.been.calledAfter(spy1)
-})
-```
-
-::: tip Migration Guide
-For a complete guide on migrating from Mocha+Chai+Sinon to Vitest, see the [Migration Guide](/guide/migration#mocha-chai-sinon).
-:::
-
-## toSatisfy
-
-- **Type:** `(predicate: (value: any) => boolean) => Awaitable<void>`
-
-This assertion checks if a value satisfies a certain predicate.
-
-```ts
-import { describe, expect, it } from 'vitest'
-
-const isOdd = (value: number) => value % 2 !== 0
-
-describe('toSatisfy()', () => {
-  it('pass with 0', () => {
-    expect(1).toSatisfy(isOdd)
-  })
-
-  it('pass with negation', () => {
-    expect(2).not.toSatisfy(isOdd)
-  })
-})
-```
-
-## resolves
-
-- **Type:** `Promisify<Assertions>`
-
-`resolves` is intended to remove boilerplate when asserting asynchronous code. Use it to unwrap value from the pending promise and assert its value with usual assertions. If the promise rejects, the assertion will fail.
-
-It returns the same `Assertions` object, but all matchers now return `Promise`, so you would need to `await` it. Also works with `chai` assertions.
-
-For example, if you have a function, that makes an API call and returns some data, you may use this code to assert its return value:
-
-```ts
-import { expect, test } from 'vitest'
-
-async function buyApples() {
-  return fetch('/buy/apples').then(r => r.json())
-}
-
-test('buyApples returns new stock id', async () => {
-  // toEqual returns a promise now, so you HAVE to await it
-  await expect(buyApples()).resolves.toEqual({ id: 1 }) // jest API
-  await expect(buyApples()).resolves.to.equal({ id: 1 }) // chai API
-})
-```
-
-:::warning
-If the assertion is not awaited, then you will have a false-positive test that will pass every time. To make sure that assertions are actually called, you may use [`expect.assertions(number)`](#expect-assertions).
-
-Since Vitest 3, if a method is not awaited, Vitest will show a warning at the end of the test. In Vitest 4, the test will be marked as "failed" if the assertion is not awaited.
-:::
-
-## rejects
-
-- **Type:** `Promisify<Assertions>`
-
-`rejects` is intended to remove boilerplate when asserting asynchronous code. Use it to unwrap reason why the promise was rejected, and assert its value with usual assertions. If the promise successfully resolves, the assertion will fail.
-
-It returns the same `Assertions` object, but all matchers now return `Promise`, so you would need to `await` it. Also works with `chai` assertions.
-
-For example, if you have a function that fails when you call it, you may use this code to assert the reason:
-
-```ts
-import { expect, test } from 'vitest'
-
-async function buyApples(id) {
-  if (!id) {
-    throw new Error('no id')
-  }
-}
-
-test('buyApples throws an error when no id provided', async () => {
-  // toThrow returns a promise now, so you HAVE to await it
-  await expect(buyApples()).rejects.toThrow('no id')
-})
-```
-
-:::warning
-If the assertion is not awaited, then you will have a false-positive test that will pass every time. To make sure that assertions were actually called, you can use [`expect.assertions(number)`](#expect-assertions).
-
-Since Vitest 3, if a method is not awaited, Vitest will show a warning at the end of the test. In Vitest 4, the test will be marked as "failed" if the assertion is not awaited.
-:::
-
-## expect.assertions
-
-- **Type:** `(count: number) => void`
-
-After the test has passed or failed verify that a certain number of assertions was called during a test. A useful case would be to check if an asynchronous code was called.
-
-For example, if we have a function that asynchronously calls two matchers, we can assert that they were actually called.
-
-```ts
-import { expect, test } from 'vitest'
-
-async function doAsync(...cbs) {
-  await Promise.all(
-    cbs.map((cb, index) => cb({ index })),
-  )
-}
-
-test('all assertions are called', async () => {
-  expect.assertions(2)
-  function callback1(data) {
-    expect(data).toBeTruthy()
-  }
-  function callback2(data) {
-    expect(data).toBeTruthy()
-  }
-
-  await doAsync(callback1, callback2)
-})
-```
-::: warning
-When using `assertions` with async concurrent tests, `expect` from the local [Test Context](/guide/test-context) must be used to ensure the right test is detected.
-:::
-
-## expect.hasAssertions
-
-- **Type:** `() => void`
-
-After the test has passed or failed verify that at least one assertion was called during a test. A useful case would be to check if an asynchronous code was called.
-
-For example, if you have a code that calls a callback, we can make an assertion inside a callback, but the test will always pass if we don't check if an assertion was called.
-
-```ts
-import { expect, test } from 'vitest'
-import { db } from './db.js'
-
-const cbs = []
-
-function onSelect(cb) {
-  cbs.push(cb)
-}
-
-// after selecting from db, we call all callbacks
-function select(id) {
-  return db.select({ id }).then((data) => {
-    return Promise.all(
-      cbs.map(cb => cb(data)),
-    )
-  })
-}
-
-test('callback was called', async () => {
-  expect.hasAssertions()
-  onSelect((data) => {
-    // should be called on select
-    expect(data).toBeTruthy()
-  })
-  // if not awaited, test will fail
-  // if you don't have expect.hasAssertions(), test will pass
-  await select(3)
-})
-```
-
-## expect.unreachable
-
-- **Type:** `(message?: string) => never`
-
-This method is used to assert that a line should never be reached.
-
-For example, if we want to test that `build()` throws due to receiving directories having no `src` folder, and also handle each error separately, we could do this:
-
-```ts
-import { expect, test } from 'vitest'
-
-async function build(dir) {
-  if (dir.includes('no-src')) {
-    throw new Error(`${dir}/src does not exist`)
-  }
-}
-
-const errorDirs = [
-  'no-src-folder',
-  // ...
-]
-
-test.each(errorDirs)('build fails with "%s"', async (dir) => {
-  try {
-    await build(dir)
-    expect.unreachable('Should not pass build')
-  }
-  catch (err: any) {
-    expect(err).toBeInstanceOf(Error)
-    expect(err.stack).toContain('build')
-
-    switch (dir) {
-      case 'no-src-folder':
-        expect(err.message).toBe(`${dir}/src does not exist`)
-        break
-      default:
-        // to exhaust all error tests
-        expect.unreachable('All error test must be handled')
-        break
-    }
-  }
-})
-```
-
-## expect.anything
-
-- **Type:** `() => any`
-
-This asymmetric matcher matches anything except `null` or `undefined`. Useful if you just want to be sure that a property exists with any value that's not either `null` or `undefined`.
-
-```ts
-import { expect, test } from 'vitest'
-
-test('object has "apples" key', () => {
-  expect({ apples: 22 }).toEqual({ apples: expect.anything() })
-})
-```
-
-## expect.any
-
-- **Type:** `(constructor: unknown) => any`
-
-This asymmetric matcher, when used with an equality check, will return `true` only if the value is an instance of a specified constructor. Useful, if you have a value that is generated each time, and you only want to know that it exists with a proper type.
-
-```ts
-import { expect, test } from 'vitest'
-import { generateId } from './generators.js'
-
-test('"id" is a number', () => {
-  expect({ id: generateId() }).toEqual({ id: expect.any(Number) })
-})
-```
-
-## expect.closeTo {#expect-closeto}
-
-- **Type:** `(expected: any, precision?: number) => any`
-
-`expect.closeTo` is useful when comparing floating point numbers in object properties or array item. If you need to compare a number, please use `.toBeCloseTo` instead.
-
-The optional `precision` argument limits the number of digits to check **after** the decimal point. For the default value `2`, the test criterion is `Math.abs(expected - received) < 0.005 (that is, 10 ** -2 / 2)`.
-
-For example, this test passes with a precision of 5 digits:
-
-```js
-test('compare float in object properties', () => {
-  expect({
-    title: '0.1 + 0.2',
-    sum: 0.1 + 0.2,
-  }).toEqual({
-    title: '0.1 + 0.2',
-    sum: expect.closeTo(0.3, 5),
-  })
-})
-```
-
-## expect.arrayContaining
-
-- **Type:** `<T>(expected: T[]) => any`
-
-When used with an equality check, this asymmetric matcher will return `true` if the value is an array and contains specified items.
-
-```ts
-import { expect, test } from 'vitest'
-
-test('basket includes fuji', () => {
-  const basket = {
-    varieties: [
-      'Empire',
-      'Fuji',
-      'Gala',
-    ],
-    count: 3
-  }
-  expect(basket).toEqual({
-    count: 3,
-    varieties: expect.arrayContaining(['Fuji'])
-  })
-})
-```
-
-:::tip
-You can use `expect.not` with this matcher to negate the expected value.
-:::
-
-## expect.objectContaining
-
-- **Type:** `(expected: any) => any`
-
-When used with an equality check, this asymmetric matcher will return `true` if the value has a similar shape.
-
-```ts
-import { expect, test } from 'vitest'
-
-test('basket has empire apples', () => {
-  const basket = {
-    varieties: [
-      {
-        name: 'Empire',
-        count: 1,
-      }
-    ],
-  }
-  expect(basket).toEqual({
-    varieties: [
-      expect.objectContaining({ name: 'Empire' }),
-    ]
-  })
-})
-```
-
-:::tip
-You can use `expect.not` with this matcher to negate the expected value.
-:::
-
-## expect.stringContaining
-
-- **Type:** `(expected: any) => any`
-
-When used with an equality check, this asymmetric matcher will return `true` if the value is a string and contains a specified substring.
-
-```ts
-import { expect, test } from 'vitest'
-
-test('variety has "Emp" in its name', () => {
-  const variety = {
-    name: 'Empire',
-    count: 1,
-  }
-  expect(variety).toEqual({
-    name: expect.stringContaining('Emp'),
-    count: 1,
-  })
-})
-```
-
-:::tip
-You can use `expect.not` with this matcher to negate the expected value.
-:::
-
-## expect.stringMatching
-
-- **Type:** `(expected: any) => any`
-
-When used with an equality check, this asymmetric matcher will return `true` if the value is a string and contains a specified substring or if the string matches a regular expression.
-
-```ts
-import { expect, test } from 'vitest'
-
-test('variety ends with "re"', () => {
-  const variety = {
-    name: 'Empire',
-    count: 1,
-  }
-  expect(variety).toEqual({
-    name: expect.stringMatching(/re$/),
-    count: 1,
-  })
-})
-```
-
-:::tip
-You can use `expect.not` with this matcher to negate the expected value.
-:::
-
-## expect.schemaMatching
-
-- **Type:** `(expected: StandardSchemaV1) => any`
-
-When used with an equality check, this asymmetric matcher will return `true` if the value matches the provided schema. The schema must implement the [Standard Schema v1](https://standardschema.dev/) specification.
-
-```ts
-import { expect, test } from 'vitest'
-import { z } from 'zod'
-import * as v from 'valibot'
-import { type } from 'arktype'
-
-test('email validation', () => {
-  const user = { email: 'john@example.com' }
-
-  // using Zod
-  expect(user).toEqual({
-    email: expect.schemaMatching(z.string().email()),
-  })
-
-  // using Valibot
-  expect(user).toEqual({
-    email: expect.schemaMatching(v.pipe(v.string(), v.email()))
-  })
-
-  // using ArkType
-  expect(user).toEqual({
-    email: expect.schemaMatching(type('string.email')),
-  })
-})
-```
-
-:::tip
-You can use `expect.not` with this matcher to negate the expected value.
-:::
-
-## expect.addSnapshotSerializer
-
-- **Type:** `(plugin: PrettyFormatPlugin) => void`
-
-This method adds custom serializers that are called when creating a snapshot. This is an advanced feature - if you want to know more, please read a [guide on custom serializers](/guide/snapshot#custom-serializer).
-
-If you are adding custom serializers, you should call this method inside [`setupFiles`](/config/setupfiles). This will affect every snapshot.
-
-:::tip
-If you previously used Vue CLI with Jest, you might want to install [jest-serializer-vue](https://npmx.dev/package/jest-serializer-vue). Otherwise, your snapshots will be wrapped in a string, which cases `"` to be escaped.
-:::
-
-## expect.extend
-
-- **Type:** `(matchers: MatchersObject) => void`
-
-You can extend default matchers with your own. This function is used to extend the matchers object with custom matchers.
-
-When you define matchers that way, you also create asymmetric matchers that can be used like `expect.stringContaining`.
-
-```ts
-import { expect, test } from 'vitest'
-
-test('custom matchers', () => {
-  expect.extend({
-    toBeFoo: (received, expected) => {
-      if (received !== 'foo') {
-        return {
-          message: () => `expected ${received} to be foo`,
-          pass: false,
-        }
-      }
-    },
-  })
-
-  expect('foo').toBeFoo()
-  expect({ foo: 'foo' }).toEqual({ foo: expect.toBeFoo() })
-})
-```
-
-::: tip
-If you want your matchers to appear in every test, you should call this method inside [`setupFiles`](/config/setupfiles).
-:::
-
-This function is compatible with Jest's `expect.extend`, so any library that uses it to create custom matchers will work with Vitest.
-
-If you are using TypeScript, since Vitest 0.31.0 you can extend default `Assertion` interface in an ambient declaration file (e.g: `vitest.d.ts`) with the code below:
-
-```ts
-interface CustomMatchers<R = unknown> {
-  toBeFoo: () => R
-}
-
-declare module 'vitest' {
-  interface Assertion<T = any> extends CustomMatchers<T> {}
-  interface AsymmetricMatchersContaining extends CustomMatchers {}
-}
-```
-
-::: warning
-Don't forget to include the ambient declaration file in your `tsconfig.json`.
-:::
-
-:::tip
-If you want to know more, checkout [guide on extending matchers](/guide/extending-matchers).
-:::
-
-## expect.addEqualityTesters {#expect-addequalitytesters}
-
-- **Type:** `(tester: Array<Tester>) => void`
-
-You can use this method to define custom testers, which are methods used by matchers, to test if two objects are equal. It is compatible with Jest's `expect.addEqualityTesters`.
-
-```ts
-import { expect, test } from 'vitest'
-
-class AnagramComparator {
-  public word: string
-
-  constructor(word: string) {
-    this.word = word
-  }
-
-  equals(other: AnagramComparator): boolean {
-    const cleanStr1 = this.word.replace(/ /g, '').toLowerCase()
-    const cleanStr2 = other.word.replace(/ /g, '').toLowerCase()
-
-    const sortedStr1 = cleanStr1.split('').sort().join('')
-    const sortedStr2 = cleanStr2.split('').sort().join('')
-
-    return sortedStr1 === sortedStr2
-  }
-}
-
-function isAnagramComparator(a: unknown): a is AnagramComparator {
-  return a instanceof AnagramComparator
-}
-
-function areAnagramsEqual(a: unknown, b: unknown): boolean | undefined {
-  const isAAnagramComparator = isAnagramComparator(a)
-  const isBAnagramComparator = isAnagramComparator(b)
-
-  if (isAAnagramComparator && isBAnagramComparator) {
-    return a.equals(b)
-  }
-  else if (isAAnagramComparator === isBAnagramComparator) {
-    return undefined
-  }
-  else {
-    return false
-  }
-}
-
-expect.addEqualityTesters([areAnagramsEqual])
-
-test('custom equality tester', () => {
-  expect(new AnagramComparator('listen')).toEqual(new AnagramComparator('silent'))
-})
-```