expect

以下の型は、下記の型シグネチャで使用されています。

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

expect はアサーションを作成するために使用されます。このコンテキストでは、アサーションはステートメントをアサートするために呼び出すことができる関数です。Vitestはデフォルトでchaiアサーション、そしてchaiの上に構築されたJest互換のアサーションを提供します。

例えば、このコードはinputの値が2と等しいことをアサートします。そうでない場合、アサーションはエラーをスローし、テストは失敗します。

import {  } from 'vitest'

const  = .(4)

()..(2) // chai API
().(2) // jest API

技術的にはこの例ではtest関数は使用していないため、コンソールにはVitestの出力ではなく、Node.jsのエラーが表示されます。testの詳細については、テストAPIリファレンスを参照してください。

また、expectは、後で説明するmatcher関数などに静的にアクセスするために使用できます。

警告

式に型エラーがない場合、expectはテストの型に影響を与えません。Vitestを型チェッカーとして使用したい場合は、expectTypeOfまたはassertTypeを使用してください。

soft

• 型: ExpectStatic & (actual: any) => Assertions

expect.softはexpectと同様に機能しますが、アサーションが失敗した場合にテストの実行を終了する代わりに、実行を継続し、失敗をテストの失敗としてマークします。テストが完了するまで、テスト中に発生したすべてのエラーが表示されます。

import { ,  } from 'vitest'

('expect.soft test', () => {
  .(1 + 1).(3) // mark the test as fail and continue
  .(1 + 2).(4) // mark the test as fail and continue
})
// At the end of the test, the above errors will be output.

expectと併用することもできます。expectのアサーションが失敗すると、テストは終了し、すべてのエラーが表示されます。

import { ,  } from 'vitest'

('expect.soft test', () => {
  .(1 + 1).(3) // mark the test as fail and continue
  (1 + 2).(4) // failed and terminate the test, all previous errors will be output
  .(1 + 3).(5) // do not run
})

警告

expect.softはtest関数内でのみ使用できます。

not

notを使用すると、アサーションが否定されます。例えば、このコードはinputの値が2と等しくないことをアサートします。等しい場合、アサーションはエラーをスローし、テストは失敗します。

import { ,  } from 'vitest'

const  = .(16)

()...(2) // chai API
()..(2) // jest API

toBe

• 型: (value: any) => Awaitable<void>

toBeは、プリミティブが等しいか、オブジェクトが同じ参照を共有しているかどうかをアサートするために使用できます。これはexpect(Object.is(3, 3)).toBe(true)を呼び出すことと同等です。オブジェクトが同じではないが、それらの構造が同一であるかどうかを確認したい場合は、toEqualを使用できます。

例えば、以下のコードは、トレーダーが13個のリンゴを持っているかどうかを確認します。

import { ,  } from 'vitest'

const  = {
  : 'apples',
  : 13,
}

('stock has 13 apples', () => {
  (.).('apples')
  (.).(13)
})

('stocks are the same', () => {
  const  =  // same reference

  ().()
})

浮動小数点数にはtoBeを使用しないでください。JavaScriptは浮動小数点数を丸めるため、0.1 + 0.2は厳密には0.3ではありません。浮動小数点数を確実にアサートするには、toBeCloseToアサーションを使用してください。

toBeCloseTo

• 型: (value: number, numDigits?: number) => Awaitable<void>

浮動小数点数を比較するにはtoBeCloseToを使用します。オプションのnumDigits引数は、小数点以下の桁数を制限します。例えば

import { ,  } from 'vitest'

.('decimals are not equal in javascript', () => {
  (0.2 + 0.1).(0.3) // 0.2 + 0.1 is 0.30000000000000004
})

('decimals are rounded to 5 after the point', () => {
  // 0.2 + 0.1 is 0.30000 | "000000000004" removed
  (0.2 + 0.1).(0.3, 5)
  // nothing from 0.30000000000000004 is removed
  (0.2 + 0.1)..(0.3, 50)
})

toBeDefined

• 型: () => Awaitable<void>

toBeDefinedは、値がundefinedと等しくないことをアサートします。関数が何かを返したかどうかを確認する場合に便利です。

import { ,  } from 'vitest'

function () {
  return 3
}

('function returned something', () => {
  (()).()
})

toBeUndefined

• 型: () => Awaitable<void>

toBeDefinedとは逆に、toBeUndefinedは値がundefinedと等しいことをアサートします。関数が何も返さなかったかどうかを確認する場合に便利です。

import { ,  } from 'vitest'

function (: string) {
  if ( === 'Bill')
    return 13
}

('mary doesn\'t have a stock', () => {
  (('Mary')).()
})

toBeTruthy

• 型: () => Awaitable<void>

toBeTruthyは、値をブール値に変換したときにtrueであることをアサートします。値は気にせず、trueに変換できるかどうかだけを知りたい場合に便利です。

例えば、このコードではstocks.getInfoの戻り値は気にしません。それは複雑なオブジェクト、文字列、またはその他の何かかもしれません。コードはそれでも動作します。

import { Stocks } from './stocks.js'

const stocks = new Stocks()
stocks.sync('Bill')
if (stocks.getInfo('Bill'))
  stocks.sell('apples', 'Bill')

そのため、stocks.getInfoがtruthyであることをテストしたい場合は、次のように記述できます。

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

JavaScriptでは、false、null、undefined、NaN、0、-0、0n、""、document.allを除くすべてがtruthyです。

toBeFalsy

• 型: () => Awaitable<void>

toBeFalsyは、値をブール値に変換したときにfalseであることをアサートします。値は気にせず、falseに変換できるかどうかだけを知りたい場合に便利です。

例えば、このコードではstocks.stockFailedの戻り値は気にしません。それは任意のfalsy値を返す可能性がありますが、コードはそれでも動作します。

import { Stocks } from './stocks.js'

const stocks = new Stocks()
stocks.sync('Bill')
if (!stocks.stockFailed('Bill'))
  stocks.sell('apples', 'Bill')

そのため、stocks.stockFailedがfalsyであることをテストしたい場合は、次のように記述できます。

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

JavaScriptでは、false、null、undefined、NaN、0、-0、0n、""、document.allを除くすべてがtruthyです。

toBeNull

• 型: () => Awaitable<void>

toBeNullは、単に何かがnullであるかどうかをアサートします。.toBe(null)のエイリアスです。

import { ,  } from 'vitest'

function () {
  return null
}

('we don\'t have apples', () => {
  (()).()
})

toBeNaN

• 型: () => Awaitable<void>

toBeNaNは、単に何かがNaNであるかどうかをアサートします。.toBe(NaN)のエイリアスです。

import { ,  } from 'vitest'

let  = 0

function () {
  ++
  return  > 1 ? . : 
}

('getApplesCount has some unusual side effects...', () => {
  (())..()
  (()).()
})

toBeTypeOf

• 型: (c: 'bigint' | 'boolean' | 'function' | 'number' | 'object' | 'string' | 'symbol' | 'undefined') => Awaitable<void>

toBeTypeOfは、実際の値が受信した型と同じ型であるかどうかをアサートします。

import { ,  } from 'vitest'

const  = 'stock'

('stock is type of string', () => {
  ().('string')
})

toBeInstanceOf

• 型: (c: any) => Awaitable<void>

toBeInstanceOfは、実際の値が受信したクラスのインスタンスであるかどうかをアサートします。

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

• 型: (n: number | bigint) => Awaitable<void>

toBeGreaterThanは、実際の値が受信した値よりも大きいことをアサートします。値が等しいとテストは失敗します。

import { expect, test } from 'vitest'
import { getApples } from './stocks.js'

test('have more then 10 apples', () => {
  expect(getApples()).toBeGreaterThan(10)
})

toBeGreaterThanOrEqual

• 型: (n: number | bigint) => Awaitable<void>

toBeGreaterThanOrEqualは、実際の値が受信した値よりも大きい、または等しいことをアサートします。

import { expect, test } from 'vitest'
import { getApples } from './stocks.js'

test('have 11 apples or more', () => {
  expect(getApples()).toBeGreaterThanOrEqual(11)
})

toBeLessThan

• 型: (n: number | bigint) => Awaitable<void>

toBeLessThanは、実際の値が受信した値よりも小さいことをアサートします。値が等しいとテストは失敗します。

import { expect, test } from 'vitest'
import { getApples } from './stocks.js'

test('have less then 20 apples', () => {
  expect(getApples()).toBeLessThan(20)
})

toBeLessThanOrEqual

• 型: (n: number | bigint) => Awaitable<void>

toBeLessThanOrEqualは、実際の値が受信した値よりも小さい、または等しいことをアサートします。

import { expect, test } from 'vitest'
import { getApples } from './stocks.js'

test('have 11 apples or less', () => {
  expect(getApples()).toBeLessThanOrEqual(11)
})

toEqual

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

toEqualは、実際の値が受信した値と等しいか、オブジェクトの場合は同じ構造を持っているかどうか（再帰的に比較）をアサートします。この例でtoEqualとtoBeの違いを確認できます。

import { ,  } from 'vitest'

const  = {
  : 'apples',
  : 13,
}

const  = {
  : 'apples',
  : 13,
}

('stocks have the same properties', () => {
  ().()
})

('stocks are not the same', () => {
  ()..()
})

警告

Errorオブジェクトに対しては、深い等価性は実行されません。Errorのmessageプロパティのみが等価性のために考慮されます。message以外のプロパティをチェックするように等価性をカスタマイズするには、expect.addEqualityTestersを使用してください。何かがスローされたかどうかをテストするには、toThrowErrorアサーションを使用してください。

toStrictEqual

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

toStrictEqualは、実際の値が受信した値と等しいか、オブジェクトの場合は同じ構造を持っているかどうか（再帰的に比較）をアサートし、かつ型も同じであることを確認します。

.toEqualとの違い

• undefinedのプロパティを持つキーがチェックされます。例：{a: undefined, b: 2}は、.toStrictEqualを使用する場合、{b: 2}とは一致しません。
• 配列の疎密がチェックされます。例：[, 1]は、.toStrictEqualを使用する場合、[undefined, 1]とは一致しません。
• オブジェクトの型が等しいかどうかがチェックされます。例：フィールドaとbを持つクラスインスタンスは、フィールドaとbを持つリテラルオブジェクトとは等しくありません。

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

• 型: (received: string) => Awaitable<void>

toContainは、実際の値が配列に含まれているかどうかをアサートします。toContainは、文字列が別の文字列の部分文字列であるかどうかを確認することもできます。Vitest 1.0以降、ブラウザのような環境でテストを実行している場合、このアサーションは、クラスがclassListに含まれているかどうか、または要素が別の要素内にあるかどうかを確認することもできます。

import { expect, test } from 'vitest'
import { getAllFruits } from './stocks.js'

test('the fruit list contains orange', () => {
  expect(getAllFruits()).toContain('orange')

  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

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

toContainEqualは、特定の構造と値を持つアイテムが配列に含まれているかどうかをアサートします。各要素内でtoEqualのように機能します。

import { expect, test } from 'vitest'
import { getFruitStock } from './stocks.js'

test('apple available', () => {
  expect(getFruitStock()).toContainEqual({ fruit: 'apple', count: 5 })
})

toHaveLength

• 型: (received: number) => Awaitable<void>

toHaveLengthは、オブジェクトに.lengthプロパティがあり、それが特定の数値に設定されているかどうかをアサートします。

import { ,  } from 'vitest'

('toHaveLength', () => {
  ('abc').(3)
  ([1, 2, 3]).(3)

  ('')..(3) // doesn't have .length of 3
  ({ : 3 }).(3)
})

toHaveProperty

• 型: (key: any, received?: any) => Awaitable<void>

toHavePropertyは、オブジェクトに指定された参照keyのプロパティが存在するかどうかをアサートします。

toEqual matcherのように、受信したプロパティ値を比較するためのオプションの値引数（深い等価性）も提供できます。

import { ,  } from 'vitest'

const  = {
  'isActive': true,
  'P.O': '12345',
  'customer': {
    : 'John',
    : 'Doe',
    : 'China',
  },
  'total_amount': 5000,
  'items': [
    {
      : 'apples',
      : 10,
    },
    {
      : 'oranges',
      : 5,
    },
  ],
}

('John Doe Invoice', () => {
  ().('isActive') // assert that the key exists
  ().('total_amount', 5000) // assert that the key exists and the value is equal

  ()..('account') // assert that this key does not exist

  // Deep referencing using dot notation
  ().('customer.first_name')
  ().('customer.last_name', 'Doe')
  ()..('customer.location', 'India')

  // Deep referencing using an array containing the key
  ().('items[0].type', 'apples')
  ().('items.0.type', 'apples') // dot notation also works

  // Deep referencing using an array containing the keyPath
  ().(['items', 0, 'type'], 'apples')
  ().(['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
  ().(['P.O'], '12345')
})

toMatch

• 型: (received: string | regexp) => Awaitable<void>

toMatchは、文字列が正規表現または文字列と一致するかどうかをアサートします。

import { ,  } from 'vitest'

('top fruits', () => {
  ('top fruits include apple, orange and grape').(/apple/)
  ('applefruits').('fruit') // toMatch also accepts a string
})

toMatchObject

• 型: (received: object | array) => Awaitable<void>

toMatchObjectは、オブジェクトがオブジェクトのプロパティのサブセットと一致するかどうかをアサートします。

オブジェクトの配列を渡すこともできます。これは、arrayContainingとは対照的に、受信した配列に余分な要素を許可するのではなく、2つの配列の要素数が一致することを確認したい場合に役立ちます。

import { ,  } from 'vitest'

const  = {
  : true,
  : {
    : 'John',
    : 'Doe',
    : 'China',
  },
  : 5000,
  : [
    {
      : 'apples',
      : 10,
    },
    {
      : 'oranges',
      : 5,
    },
  ],
}

const  = {
  : {
    : 'John',
    : 'Doe',
    : 'China',
  },
}

('invoice has john personal details', () => {
  ().()
})

('the number of elements must match exactly', () => {
  // Assert that an array of object matches
  ([{ : 'bar' }, { : 1 }]).([
    { : 'bar' },
    { : 1 },
  ])
})

toThrowError

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

• エイリアス: toThrow

toThrowErrorは、関数が呼び出されたときにエラーをスローするかどうかをアサートします。

特定のエラーがスローされたかどうかをテストするためのオプションの引数を指定できます。

• 正規表現：エラーメッセージがパターンと一致します。
• 文字列：エラーメッセージに部分文字列が含まれています。

ヒント

コードを関数でラップする必要があります。そうしないと、エラーはキャッチされず、テストは失敗します。

例えば、getFruitStock('pineapples')がエラーを投げることをテストしたい場合、次のように記述できます。

import { ,  } from 'vitest'

function (: string) {
  if ( === 'pineapples')
    throw new ('Pineapples are not in stock')

  // Do some other stuff
}

('throws on pineapples', () => {
  // Test that the error message says "stock" somewhere: these are equivalent
  (() => ('pineapples')).(/stock/)
  (() => ('pineapples')).('stock')

  // Test the exact error message
  (() => ('pineapples')).(
    /^Pineapples are not in stock$/,
  )
})

ヒント

非同期関数をテストするには、rejectsと組み合わせて使用します。

function () {
  return .(new ('empty'))
}

test('throws on pineapples', async () => {
  await expect(() => ()).rejects.toThrowError('empty')
})

toMatchSnapshot

• 型: <T>(shape?: Partial<T> | string, message?: string) => void

これにより、値が最新のsnapshotと一致することが保証されます。

テスト名に付加されるオプションのhint文字列引数を指定できます。Vitestは常にsnapshot名に番号を付加しますが、単一のitブロックまたはtestブロック内の複数のsnapshotを区別するには、番号よりも短い記述的なヒントの方が役立つ場合があります。Vitestは対応する.snapファイル内の名前でsnapshotをソートします。

ヒント

snapshotの不一致が発生し、テストが失敗した場合、不一致が予期される場合は、uキーを押してsnapshotを一度更新できます。または、-uまたは--update CLIオプションを渡して、Vitestが常にテストを更新するようにすることもできます。

import { ,  } from 'vitest'

('matches snapshot', () => {
  const  = { : new (['bar', 'snapshot']) }
  ().()
})

オブジェクトの形状のみをテストしていて、100%の互換性が必要ない場合は、オブジェクトの形状も指定できます。

import { ,  } from 'vitest'

('matches snapshot', () => {
  const  = { : new (['bar', 'snapshot']) }
  ().({ : .() })
})

toMatchInlineSnapshot

• 型: <T>(shape?: Partial<T> | string, snapshot?: string, message?: string) => void

これにより、値が最新のsnapshotと一致することが保証されます。

Vitestは、(外部の.snapファイルではなく)テストファイル内のmatcherにinlineSnapshot文字列引数を追加および更新します。

import { ,  } from 'vitest'

('matches inline snapshot', () => {
  const  = { : new (['bar', 'snapshot']) }
  // Vitest will update following content when updating the snapshot
  ().(`
    {
      "foo": Set {
        "bar",
        "snapshot",
      },
    }
  `)
})

オブジェクトの形状のみをテストしていて、100%の互換性が必要ない場合は、オブジェクトの形状も指定できます。

import { ,  } from 'vitest'

('matches snapshot', () => {
  const  = { : new (['bar', 'snapshot']) }
  ().(
    { : .() },
    `
    {
      "foo": Any<Set>,
    }
  `
  )
})

toMatchFileSnapshot 0.30.0+

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

.snapファイルの代わりに、明示的に指定されたファイルの内容とsnapshotを比較または更新します。

import { expect, it } from 'vitest'

it('render basic', async () => {
  const result = renderHTML(h('div', { class: 'foo' }))
  await expect(result).toMatchFileSnapshot('./test/basic.output.html')
})

ファイルシステム操作は非同期であるため、toMatchFileSnapshot()にはawaitを使用する必要があることに注意してください。

toThrowErrorMatchingSnapshot

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

toMatchSnapshotと同じですが、toThrowErrorと同じ値を期待します。

toThrowErrorMatchingInlineSnapshot

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

toMatchInlineSnapshotと同じですが、toThrowErrorと同じ値を期待します。

toHaveBeenCalled

• 型: () => Awaitable<void>

このアサーションは、関数が呼び出されたことをテストする場合に役立ちます。expectにスパイ関数を渡す必要があります。

import { , ,  } from 'vitest'

const  = {
  (: string, : number) {
    // ...
  },
}

('spy function', () => {
  const  = .(, 'buy')

  ()..()

  .('apples', 10)

  ().()
})

toHaveBeenCalledTimes

• 型: (amount: number) => Awaitable<void>

このアサーションは、関数が特定の回数呼び出されたかどうかを確認します。expectにスパイ関数を渡す必要があります。

import { , ,  } from 'vitest'

const  = {
  (: string, : number) {
    // ...
  },
}

('spy function called two times', () => {
  const  = .(, 'buy')

  .('apples', 10)
  .('apples', 20)

  ().(2)
})

toHaveBeenCalledWith

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

このアサーションは、関数が特定のパラメータで少なくとも1回呼び出されたかどうかを確認します。expectにスパイ関数を渡す必要があります。

import { , ,  } from 'vitest'

const  = {
  (: string, : number) {
    // ...
  },
}

('spy function', () => {
  const  = .(, 'buy')

  .('apples', 10)
  .('apples', 20)

  ().('apples', 10)
  ().('apples', 20)
})

toHaveBeenLastCalledWith

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

このアサーションは、関数が最後の実行で特定のパラメータで呼び出されたかどうかを確認します。expectにスパイ関数を渡す必要があります。

import { , ,  } from 'vitest'

const  = {
  (: string, : number) {
    // ...
  },
}

('spy function', () => {
  const  = .(, 'buy')

  .('apples', 10)
  .('apples', 20)

  ()..('apples', 10)
  ().('apples', 20)
})

toHaveBeenNthCalledWith

• 型: (time: number, ...args: any[]) => Awaitable<void>

このアサーションは、関数が特定のタイミングで特定のパラメータで呼び出されたかどうかを確認します。カウントは1から始まります。したがって、2番目のエントリを確認するには、.toHaveBeenNthCalledWith(2, ...)と書きます。

expectにスパイ関数を渡す必要があります。

import { , ,  } from 'vitest'

const  = {
  (: string, : number) {
    // ...
  },
}

('first call of spy function called with right params', () => {
  const  = .(, 'buy')

  .('apples', 10)
  .('apples', 20)

  ().(1, 'apples', 10)
})

toHaveReturned

• 型: () => Awaitable<void>

このアサーションは、関数が少なくとも1回正常に値を返したかどうか（つまり、エラーをスローしなかったかどうか）を確認します。expectにスパイ関数を渡す必要があります。

import { , ,  } from 'vitest'

function (: number) {
  const  = 10
  return  * 
}

('spy function returned a value', () => {
  const  = .()

  const  = (10)

  ().(100)
  ().()
})

toHaveReturnedTimes

• 型: (amount: number) => Awaitable<void>

このアサーションは、関数が正確な回数、正常に値を返したかどうか（つまり、エラーをスローしなかったかどうか）を確認します。expectにスパイ関数を渡す必要があります。

import { , ,  } from 'vitest'

('spy function returns a value two times', () => {
  const  = .((: string) => ({  }))

  ('apples')
  ('bananas')

  ().(2)
})

toHaveReturnedWith

• 型: (returnValue: any) => Awaitable<void>

このアサーションを呼び出して、関数が少なくとも1回、特定のパラメータで値を正常に返したかどうかを確認できます。expectにスパイ関数を渡す必要があります。

import { , ,  } from 'vitest'

('spy function returns a product', () => {
  const  = .((: string) => ({  }))

  ('apples')

  ().({ : 'apples' })
})

toHaveLastReturnedWith

• 型: (returnValue: any) => Awaitable<void>

このアサーションを呼び出して、関数が最後の実行で特定のパラメータで値を正常に返したかどうかを確認できます。expectにスパイ関数を渡す必要があります。

import { , ,  } from 'vitest'

('spy function returns bananas on a last call', () => {
  const  = .((: string) => ({  }))

  ('apples')
  ('bananas')

  ().({ : 'bananas' })
})

toHaveNthReturnedWith

• 型: (time: number, returnValue: any) => Awaitable<void>

このアサーションを呼び出して、関数が特定の呼び出しで特定のパラメータで値を正常に返したかどうかを確認できます。expectにスパイ関数を渡す必要があります。

import { , ,  } from 'vitest'

('spy function returns bananas on second call', () => {
  const  = .((: string) => ({  }))

  ('apples')
  ('bananas')

  ().(2, { : 'bananas' })
})

toSatisfy

• 型: (predicate: (value: any) => boolean) => Awaitable<void>

このアサーションは、値が特定の述語を満たすかどうかを確認します。

import { , ,  } from 'vitest'
('toSatisfy()', () => {
  const  = (: number) =>  % 2 !== 0

  ('pass with 0', () => {
    (1).()
  })

  ('pass with negation', () => {
    (2)..()
  })
})

resolves

• 型: Promisify<Assertions>

resolvesは、非同期コードのアサーションを行う際の定型コードを削減するために設計されています。これを使用して、保留中のPromiseから値を展開し、通常のAssertionを使用してその値をアサートします。Promiseが拒否されると、アサーションは失敗します。

同じAssertionsオブジェクトを返しますが、すべてのマッチャーはPromiseを返すため、awaitする必要があります。chaiアサーションでも機能します。

例えば、API呼び出しを行い、データを取得する関数が存在する場合、このコードを使用して戻り値をアサートできます。

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

警告

アサーションが待機されていない場合、常に成功する偽陽性のテストになります。アサーションが実際に呼び出されていることを確認するには、expect.assertions(number)を使用できます。

rejects

• 型: Promisify<Assertions>

rejectsは、非同期コードのアサーションを行う際の定型コードを削減するために設計されています。これを使用して、Promiseが拒否された理由を展開し、通常のAssertionを使用してその値をアサートします。Promiseが正常に解決されると、アサーションは失敗します。

同じAssertionsオブジェクトを返しますが、すべてのマッチャーはPromiseを返すため、awaitする必要があります。chaiアサーションでも機能します。

例えば、呼び出すと失敗する関数が存在する場合、このコードを使用して理由をアサートできます。

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

警告

アサーションが待機されていない場合、常に成功する偽陽性のテストになります。アサーションが実際に呼び出されたことを確認するには、expect.assertions(number)を使用できます。

expect.assertions

• 型: (count: number) => void

テストの成功または失敗後、テスト中に特定数のAssertionが呼び出されたことを確認します。非同期コードが呼び出されたかどうかを確認する場合に役立ちます。

例えば、非同期で2つのマッチャーを呼び出す関数が存在する場合、それらが実際に呼び出されたことをアサートできます。

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

警告

非同期同時テストでassertionsを使用する場合、正しいテストが検出されるように、ローカルのテストコンテキストからexpectを使用する必要があります。

expect.hasAssertions

• 型: () => void

テストの成功または失敗後、テスト中に少なくとも1つのAssertionが呼び出されたことを確認します。非同期コードが呼び出されたかどうかを確認する場合に役立ちます。

例えば、コールバックを呼び出すコードがある場合、コールバック内でアサーションを行うことができますが、アサーションが呼び出されたかどうかを確認しない場合、テストは常に成功します。

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

• 型: (message?: string) => never

このメソッドは、行に到達してはならないことをアサートするために使用されます。

例えば、build()がsrcフォルダがないディレクトリを受け取ったためにエラーをスローし、各エラーを個別に処理することをテストしたい場合、次のように行うことができます。

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

• 型: () => any

この非対称マッチャーは、等価チェックで使用した場合、常にtrueを返します。プロパティが存在することを確認したい場合に便利です。

import { expect, test } from 'vitest'

test('object has "apples" key', () => {
  expect({ apples: 22 }).toEqual({ apples: expect.anything() })
})

expect.any

• 型: (constructor: unknown) => any

この非対称マッチャーは、等価チェックで使用した場合、値が指定されたコンストラクターのインスタンスである場合にのみtrueを返します。毎回生成される値があり、適切な型で存在することだけを知りたい場合に便利です。

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 1.0.0+

• 型: (expected: any, precision?: number) => any

expect.closeToは、オブジェクトのプロパティまたは配列の項目内の浮動小数点数を比較する場合に役立ちます。数値を比較する必要がある場合は、代わりに.toBeCloseToを使用してください。

オプションのnumDigits引数は、小数点以下のチェックする桁数を制限します。デフォルト値2の場合、テスト基準はMath.abs(expected - received) < 0.005 (つまり、10 ** -2 / 2)です。

例えば、このテストは5桁の精度で成功します。

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

• 型: <T>(expected: T[]) => any

等価チェックで使用する場合、この非対称マッチャーは、値が配列であり、指定された項目が含まれている場合にtrueを返します。

import { ,  } from 'vitest'

('basket includes fuji', () => {
  const  = {
    : [
      'Empire',
      'Fuji',
      'Gala',
    ],
    : 3
  }
  ().({
    : 3,
    : .(['Fuji'])
  })
})

ヒント

このマッチャーでexpect.notを使用して、期待値を否定できます。

expect.objectContaining

• 型: (expected: any) => any

等価チェックで使用する場合、この非対称マッチャーは、値が類似した形状を持っている場合にtrueを返します。

import { ,  } from 'vitest'

('basket has empire apples', () => {
  const  = {
    : [
      {
        : 'Empire',
        : 1,
      }
    ],
  }
  ().({
    : [
      .({ : 'Empire' }),
    ]
  })
})

ヒント

このマッチャーでexpect.notを使用して、期待値を否定できます。

expect.stringContaining

• 型: (expected: any) => any

等価チェックで使用する場合、この非対称マッチャーは、値が文字列であり、指定された部分文字列が含まれている場合にtrueを返します。

import { ,  } from 'vitest'

('variety has "Emp" in its name', () => {
  const  = {
    : 'Empire',
    : 1,
  }
  ().({
    : .('Emp'),
    : 1,
  })
})

ヒント

このマッチャーでexpect.notを使用して、期待値を否定できます。

expect.stringMatching

• 型: (expected: any) => any

等価チェックで使用する場合、この非対称マッチャーは、値が文字列であり、指定された部分文字列を含んでいる場合、または文字列が正規表現に一致する場合にtrueを返します。

import { ,  } from 'vitest'

('variety ends with "re"', () => {
  const  = {
    : 'Empire',
    : 1,
  }
  ().({
    : .(/re$/),
    : 1,
  })
})

ヒント

このマッチャーでexpect.notを使用して、期待値を否定できます。

expect.addSnapshotSerializer

• 型: (plugin: PrettyFormatPlugin) => void

このメソッドは、スナップショットを作成する際に呼び出されるカスタムシリアライザを追加します。これは高度な機能です。詳細については、カスタムシリアライザに関するガイドをお読みください。

カスタムシリアライザを追加する場合は、setupFiles内でこのメソッドを呼び出す必要があります。これにより、すべてのスナップショットに影響します。

ヒント

以前Vue CLIとJestを使用していた場合は、jest-serializer-vueをインストールすることをお勧めします。インストールしないと、スナップショットが文字列でラップされ、"がエスケープされます。

expect.extend

• 型: (matchers: MatchersObject) => void

独自のマッチャでデフォルトのマッチャを拡張できます。この関数は、カスタムマッチャを使用してマッチャオブジェクトを拡張するために使用されます。

このようにマッチャーを定義すると、expect.stringContainingのように使用できる非対称マッチャーも作成されます。

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

ヒント

すべてのテストにマッチャーを表示する場合は、setupFiles内でこのメソッドを呼び出す必要があります。

この関数はJestのexpect.extendと互換性があるため、カスタムマッチャーの作成にこの関数を使用するライブラリはすべてVitestで動作します。

TypeScriptを使用している場合、Vitest 0.31.0以降、下記のコードを使用して、環境宣言ファイル（例：vitest.d.ts）でデフォルトのAssertionインターフェースを拡張できます。

interface CustomMatchers<R = unknown> {
  toBeFoo: () => R
}

declare module 'vitest' {
  interface Assertion<T = any> extends CustomMatchers<T> {}
  interface AsymmetricMatchersContaining extends CustomMatchers {}
}

警告

環境宣言ファイルをtsconfig.jsonに含めることを忘れないでください。

ヒント

詳細については、マッチャーの拡張に関するガイドをご覧ください。

expect.addEqualityTesters 1.2.0+

• 型: (tester: Array<Tester>) => void

このメソッドを使用して、カスタムテスターを定義できます。カスタムテスターは、2つのオブジェクトが等しいかどうかをテストするためにマッチャーで使用されるメソッドです。Jestのexpect.addEqualityTestersと互換性があります。

import { ,  } from 'vitest'

class  {
  public : string

  constructor(: string) {
    this. = 
  }

  (: ): boolean {
    const  = this..(/ /g, '').()
    const  = ..(/ /g, '').()

    const  = .('').().('')
    const  = .('').().('')

    return  === 
  }
}

function (: unknown):  is  {
  return  instanceof 
}

function (: unknown, : unknown): boolean | undefined {
  const  = ()
  const  = ()

  if ( && )
    return .()

  else if ( === )
    return 

  else
    return false
}

.([])

('custom equality tester', () => {
  (new ('listen')).(new ('silent'))
})