モック関数

vi.fnメソッドを使用して、モック関数を生成し、その実行状況を追跡できます。既に作成されたオブジェクトのメソッドを追跡する場合は、vi.spyOnメソッドを使用します。

import { vi } from 'vitest'

const fn = vi.fn()
fn('hello world')
fn.mock.calls[0] === ['hello world']

const market = {
  getApples: () => 100
}

const getApplesSpy = vi.spyOn(market, 'getApples')
market.getApples()
getApplesSpy.mock.calls.length === 1

モックの結果を検証するには、モックアサーション（例：toHaveBeenCalled）をexpectで使用します。このAPIリファレンスでは、モックの動作を操作するための利用可能なプロパティとメソッドについて説明します。

getMockImplementation

• 型: (...args: any) => any

モック実装が存在する場合は、現在のモック実装を返します。

vi.fnを使用してモックが作成された場合、渡されたメソッドをモック実装として扱います。

vi.spyOnを使用してモックが作成された場合、カスタム実装が提供されていない限り、undefinedを返します。

getMockName

• 型: () => string

.mockName(name)メソッドでモックに与えられた名前を返すために使用します。

mockClear

• 型: () => MockInstance

すべての呼び出しに関するすべての情報をクリアします。これを呼び出した後、.mockのプロパティはすべて空の状態になります。このメソッドは実装をリセットしません。異なるアサーション間でモックをクリーンアップする必要がある場合に役立ちます。

このメソッドを各テストの前に自動的に呼び出すには、設定でclearMocks設定を有効にします。

mockName

• 型: (name: string) => MockInstance

内部モック名を設定します。アサーションが失敗した場合にモックの名前を確認するのに役立ちます。

mockImplementation

• 型: (fn: Function) => MockInstance

モックの実装として使用される関数を受け入れます。

const  = .().( =>  + 1)
// or: vi.fn(apples => apples + 1);

const  = (0)
const  = (1)

 === 1 // true
 === 2 // true

..[0][0] === 0 // true
..[1][0] === 1 // true

mockImplementationOnce

• 型: (fn: Function) => MockInstance

次の呼び出し中にモックの実装として使用される関数を受け入れます。チェーンできるので、複数の関数呼び出しで異なる結果が生成されます。

const  = 
  .()
  .(() => true)
  .(() => false)

() // true
() // false

モック関数が実装を使い果たすと、vi.fn(() => defaultValue)または.mockImplementation(() => defaultValue)で設定されたデフォルトの実装を呼び出します（これらのいずれかが呼び出された場合）。

const  = 
  .(() => 'default')
  .(() => 'first call')
  .(() => 'second call')

// 'first call', 'second call', 'default', 'default'
.((), (), (), ())

withImplementation

• 型: (fn: Function, callback: () => void) => MockInstance
• 型: (fn: Function, callback: () => Promise<unknown>) => Promise<MockInstance>

コールバックの実行中は、元のモック実装を一時的にオーバーライドします。

const  = .(() => 'original')

.(() => 'temp', () => {
  () // 'temp'
})

() // 'original'

非同期コールバックで使用できます。後で元の implementation を使用する場合は、このメソッドを await する必要があります。

test('async callback', () => {
  const myMockFn = vi.fn(() => 'original')

  // We await this call since the callback is async
  await myMockFn.withImplementation(
    () => 'temp',
    async () => {
      myMockFn() // 'temp'
    },
  )

  myMockFn() // 'original'
})

mockImplementationOnceよりも優先されます。

mockRejectedValue

• 型: (value: any) => MockInstance

非同期関数が呼び出されたときに拒否されるエラーを受け入れます。

const  = .().(new ('Async error'))

await () // throws "Async error"

mockRejectedValueOnce

• 型: (value: any) => MockInstance

次の関数呼び出し中に拒否される値を受け入れます。チェーンされた場合、連続する呼び出しごとに指定された値が拒否されます。

const  = 
  .()
  .('first call')
  .(new ('Async error'))

await () // first call
await () // throws "Async error"

mockReset

• 型: () => MockInstance

mockClearと同じことを行い、内部の実装を空の関数にします（呼び出されたときにundefinedを返します）。これにより、すべての「once」実装もリセットされます。モックをデフォルトの状態に完全にリセットする場合に役立ちます。

このメソッドを各テストの前に自動的に呼び出すには、設定でmockReset設定を有効にします。

mockRestore

• 型: () => MockInstance

mockResetと同じことを行い、内部の実装を元の関数に復元します。

vi.fn()からモックを復元すると、実装はundefinedを返す空の関数に設定されることに注意してください。vi.fn(impl)を復元すると、実装はimplに復元されます。

このメソッドを各テストの前に自動的に呼び出すには、設定でrestoreMocks設定を有効にします。

mockResolvedValue

• 型: (value: any) => MockInstance

非同期関数が呼び出されたときに解決される値を受け入れます。

const  = .().(42)

await () // 42

mockResolvedValueOnce

• 型: (value: any) => MockInstance

次の関数呼び出し中に解決される値を受け入れます。チェーンされた場合、連続する呼び出しごとに指定された値が解決されます。

const  = 
  .()
  .('default')
  .('first call')
  .('second call')

await () // first call
await () // second call
await () // default
await () // default

mockReturnThis

• 型: () => MockInstance

実際の実装を呼び出さずに、メソッドからthisコンテキストを返す必要がある場合に使用します。これは、次の略記です。

spy.mockImplementation(function () {
  return this
})

mockReturnValue

• 型: (value: any) => MockInstance

モック関数が呼び出されるたびに返される値を受け入れます。

const  = .()
.(42)
() // 42
.(43)
() // 43

mockReturnValueOnce

• 型: (value: any) => MockInstance

次の関数呼び出し中に返される値を受け入れます。チェーンされた場合、連続する呼び出しごとに指定された値が返されます。

使用するmockReturnValueOnce値がなくなった場合、モックは、存在する場合は以前に定義された実装にフォールバックします。

const  = 
  .()
  .('default')
  .('first call')
  .('second call')

// 'first call', 'second call', 'default', 'default'
.((), (), (), ())

mock.calls

これは、各呼び出しのすべての引数を含む配列です。配列の1つの項目はその呼び出しの引数です。

const fn = vi.fn()

fn('arg1', 'arg2')
fn('arg3')

fn.mock.calls === [
  ['arg1', 'arg2'], // first call
  ['arg3'], // second call
]

mock.lastCall

これには、最後の呼び出しの引数が含まれています。モックが呼び出されなかった場合、undefinedを返します。

mock.results

これは、関数からreturnedされたすべての値を含む配列です。配列の1つの項目は、typeとvalueのプロパティを持つオブジェクトです。使用可能な型は次のとおりです。

• 'return' - 関数がスローせずに返されました。
• 'throw' - 関数が値をスローしました。

valueプロパティには、返された値またはスローされたエラーが含まれています。関数がPromiseを返した場合、解決されていない限り、valueは実際のPromiseではなく、解決された値になります。

const fn = vi.fn()
  .mockReturnValueOnce('result')
  .mockImplementationOnce(() => { throw new Error('thrown error') })

const result = fn() // returned 'result'

try {
  fn() // threw Error
}
catch {}

fn.mock.results === [
  // first result
  {
    type: 'return',
    value: 'result',
  },
  // last result
  {
    type: 'throw',
    value: Error,
  },
]

mock.invocationCallOrder

モックの実行順序。これは、定義されているすべてのモックで共有される数字の配列を返します。

const fn1 = vi.fn()
const fn2 = vi.fn()

fn1()
fn2()
fn1()

fn1.mock.invocationCallOrder === [1, 3]
fn2.mock.invocationCallOrder === [2]

mock.instances

これは、モックがnewキーワードで呼び出されたときにインスタンス化されたすべてのインスタンスを含む配列です。これは、戻り値ではなく、関数の実際のコンテキスト（this）であることに注意してください。

警告

モックがnew MyClass()でインスタンス化された場合、mock.instancesは1つの値を持つ配列になります。

const MyClass = vi.fn()
const a = new MyClass()

MyClass.mock.instances[0] === a

コンストラクターから値を返す場合、その値はinstances配列には含まれず、代わりにresults内に含まれます。

const Spy = vi.fn(() => ({ method: vi.fn() }))
const a = new Spy()

Spy.mock.instances[0] !== a
Spy.mock.results[0] === a