expect ​

The following types are used in the type signatures below

type Awaitable<T> = T | PromiseLike<T>

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 build on top of chai.

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.

import { expect } from 'vitest'

const input = Math.sqrt(4)

expect(input).to.equal(2) // chai API
expect(input).toBe(2) // jest API

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 function, so in the console you will see Nodejs error instead of Vitest output. To learn more about test, please read Test API Reference.

Also, expect can be used statically to access matchers functions, described later, and more.

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.

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
})
// At the end of the test, the above errors will be output.

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
})
// At the end of the test, the above errors will be output.

It can also be used with expect. if expect assertion fails, the test will be terminated and all errors will be displayed.

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(3) // failed and terminate the test, all previous errors will be output
  expect.soft(1 + 2).toBe(4) // do not run
})

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(3) // failed and terminate the test, all previous errors will be output
  expect.soft(1 + 2).toBe(4) // do not run
})

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.

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

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.

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

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

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

  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) {
    if (stock === 'Bill')
      return 13
  }
  
  test('mary doesn\'t have a stock', () => {
    expect(getApplesFromStock('Mary')).toBeUndefined()
  })

  import { expect, test } from 'vitest'
  
  function getApplesFromStock(stock) {
    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')

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

  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, 0, '', null, undefined, and NaN.

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

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

  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, 0, '', null, undefined, and NaN.

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

  import { expect, test } from 'vitest'
  
  function apples() {
    return null
  }
  
  test('we don\'t have apples', () => {
    expect(apples()).toBeNull()
  })

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

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

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

  import { expect, test } from 'vitest'
  
  const actual = 'stock'
  
  test('stock is type of string', () => {
    expect(actual).toBeTypeOf('string')
  })

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

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

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

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

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

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

  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

  A deep equality will not be performed for Error objects. To test if something was thrown, use toThrowError 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:

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

  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.

  ts

  import { expect, test } from 'vitest'
  import { getAllFruits } from './stocks.js'
  
  test('the fruit list contains orange', () => {
    expect(getAllFruits()).toContain('orange')
  })

  import { expect, test } from 'vitest'
  import { getAllFruits } from './stocks.js'
  
  test('the fruit list contains orange', () => {
    expect(getAllFruits()).toContain('orange')
  })

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

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

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

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

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

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

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

toThrowError ​

• Type: (received: any) => Awaitable<void>

• Alias: toThrow

  toThrowError 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:

  • regular expression: error message matches the pattern
  • string: error message includes the substring

  TIP

  You must wrap the code in a function, otherwise the error will not be caught, and test will fail.

  For example, if we want to test that getFruitStock('pineapples') throws, we could write:

  ts

  import { expect, test } from 'vitest'
  
  function getFruitStock(type) {
    if (type === 'pineapples')
      throw new DiabetesError('Pineapples are not good for people with diabetes')
  
    // Do some other stuff
  }
  
  test('throws on pineapples', () => {
    // Test that the error message says "diabetes" somewhere: these are equivalent
    expect(() => getFruitStock('pineapples')).toThrowError(/diabetes/)
    expect(() => getFruitStock('pineapples')).toThrowError('diabetes')
  
    // Test the exact error message
    expect(() => getFruitStock('pineapples')).toThrowError(
      /^Pineapples are not good for people with diabetes$/,
    )
  })

  import { expect, test } from 'vitest'
  
  function getFruitStock(type) {
    if (type === 'pineapples')
      throw new DiabetesError('Pineapples are not good for people with diabetes')
  
    // Do some other stuff
  }
  
  test('throws on pineapples', () => {
    // Test that the error message says "diabetes" somewhere: these are equivalent
    expect(() => getFruitStock('pineapples')).toThrowError(/diabetes/)
    expect(() => getFruitStock('pineapples')).toThrowError('diabetes')
  
    // Test the exact error message
    expect(() => getFruitStock('pineapples')).toThrowError(
      /^Pineapples are not good for people with diabetes$/,
    )
  })

  TIP

  To test async functions, use in combination with rejects.

  js

  function getAsyncFruitStock() {
    return Promise.reject(new Error('empty'))
  }
  
  test('throws on pineapples', async () => {
    await expect(() => getAsyncFruitStock()).rejects.toThrowError('empty')
  })

  function getAsyncFruitStock() {
    return Promise.reject(new Error('empty'))
  }
  
  test('throws on pineapples', async () => {
    await expect(() => getAsyncFruitStock()).rejects.toThrowError('empty')
  })

toMatchSnapshot ​

• Type: <T>(shape?: Partial<T> | string, message?: 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 snapshot mismatch and causing the test failing, if the mismatch is expected, you can press u key to update the snapshot for 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()
  })

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

  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, message?: 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",
        },
      }
    `)
  })

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

  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 ​

• Type: <T>(filepath: string, message?: string) => Promise<void>

• Version: Since Vitest 0.30.0

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

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

toThrowErrorMatchingSnapshot ​

• Type: (message?: string) => void

  The same as toMatchSnapshot, but expects the same value as toThrowError.

  If the function throws an Error, the snapshot will be the error message. Otherwise, snapshot will be the value thrown by the function.

toThrowErrorMatchingInlineSnapshot ​

• Type: (snapshot?: string, message?: string) => void

  The same as toMatchInlineSnapshot, but expects the same value as toThrowError.

  If the function throws an Error, the snapshot will be the error message. Otherwise, snapshot will be the value thrown by the function.

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

  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.

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

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.

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

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

toHaveBeenLastCalledWith ​

• Type: (...args: any[]) => Awaitable<void>

This assertion checks if a function was called with certain parameters at it's last invocation. Requires a spy function to be passed to expect.

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

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, ...).