Jest mockImplementationの使い方｜引数で分岐・非同期・Once・whenCalledWith【Jest 30.5対応】

mockImplementation は、Jestのモック関数に任意の関数を中身として差し込むメソッドです。戻り値を固定するだけなら mockReturnValue で足ります。引数によって返す値を変えたい、例外を投げさせたい、非同期処理の成功と失敗を作り分けたい、という場面で mockImplementation の出番になります。

この記事のコード例は、Jest 30.5.2（2026年9月18日公開の最新版）と Node.js 26.5.0 を検証環境とし、JavaScript の例は実行して、TypeScript の例は TypeScript 5.9.3 の strict モードで型検査して確かめたものです。2026年8月の Jest 30.5.0 で追加された whenCalledWith を使うと、これまで mockImplementation の中に if 文で書いていた「引数ごとの戻り値」を宣言的に書けます。その書き換え方と、mockImplementation が効かないときに確かめる5つの原因も扱います。

まとめ：mockImplementationと周辺メソッドの使い分け

やりたいことからメソッドを逆引きできるよう、先に対応表を置きます。

判断の軸は1つです。返す値が引数に依存しないなら mockReturnValue 系を、依存するなら mockImplementation か whenCalledWith を選びます。分岐が「この引数ならこの値」という対応表で書けるなら、Jest 30.5.0 以降では whenCalledWith の方が読みやすくなります。

mockImplementationの基本構文と動作

Jest公式のモック関数リファレンスによると、mockImplementation(fn) に渡した関数はモックが呼ばれるたびに実行され、モック自体は呼び出しの記録を続けます。差し替えても toHaveBeenCalledWith などの検証はそのまま使えます。

jest.fn(impl)とmockImplementation(fn)の関係

jest.fn(impl) は jest.fn().mockImplementation(impl) の短縮形と公式に明記されています。作成時に実装が決まっているなら短縮形で書き、テストの途中で実装を入れ替えるときに mockImplementation を呼びます。

test('引数を受け取る実装を差し込む', () => {
  const add = jest.fn();
  add.mockImplementation((a, b) => a + b);

  expect(add(1, 2)).toBe(3);
  expect(add).toHaveBeenCalledWith(1, 2);

  // 短縮形。作成時に実装を渡す
  const multiply = jest.fn((a, b) => a * b);
  expect(multiply(2, 3)).toBe(6);
});

実装の差し替えは何度でもでき、最後に設定したものが有効になります。現在の実装は getMockImplementation() で取り出せます。

mockReturnValueとmockImplementationの引数参照の違い

mockReturnValue(v) は、どんな引数で呼ばれても同じ v を返します。mockImplementation は引数を受け取れるので、入力に応じて出力を変えられます。

test('mockReturnValue は引数を見ない', () => {
  const fixed = jest.fn().mockReturnValue(10);
  expect(fixed(1)).toBe(10);
  expect(fixed(999)).toBe(10);

  const doubled = jest.fn().mockImplementation((n) => n * 2);
  expect(doubled(1)).toBe(2);
  expect(doubled(999)).toBe(1998);
});

値が固定で足りる場面で mockImplementation(() => 10) と書くのは避けます。読み手が「中で何か計算しているのか」を確かめに行く手間が増えるだけです。

例外を投げる実装への差し替え

同期関数が例外を投げるケースを再現するには、mockImplementation の中で throw します。mockReturnValue には例外を投げる手段がないため、ここでは mockImplementation に例外を投げる関数を渡します。

test('例外を投げさせる', () => {
  const parse = jest.fn().mockImplementation(() => {
    throw new Error('boom');
  });

  expect(() => parse()).toThrow('boom');
  // 例外の記録は mock.results に type: 'throw' で残る
  expect(parse.mock.results[0].type).toBe('throw');
});

mockImplementationOnceによる呼び出し順の戻り値設定

リトライ処理やページングのように「1回目は失敗、2回目は成功」を作りたいときは、Once 系のメソッドを呼び出し順に積みます。

Onceの消費順と既定実装へのフォールバック

Once で積んだ実装は登録順に1回ずつ消費され、尽きると jest.fn(impl) や mockImplementation で設定した既定の実装に戻ります。既定の実装が無ければ undefined が返ります。

test('Once は登録順に消費され、尽きると既定に戻る', () => {
  const next = jest.fn(() => 'default')
    .mockImplementationOnce(() => 'first')
    .mockImplementationOnce(() => 'second');

  expect([next(), next(), next(), next()])
    .toEqual(['first', 'second', 'default', 'default']);

  // 既定の実装が無いと、Once が尽きた後は undefined
  const onlyOnce = jest.fn().mockImplementationOnce(() => 'only');
  expect([onlyOnce(), onlyOnce()]).toEqual(['only', undefined]);
});

Once は mockImplementation より優先されます。mockImplementationOnce(A).mockImplementation(B) の順に書いても、1回目は A、2回目以降は B です。

mockResolvedValueOnce・mockRejectedValueOnceによる成功と失敗の順序設定

非同期関数でも同じ考え方で、mockResolvedValueOnce と mockRejectedValueOnce を混ぜて積めます。下の例は「1回目は成功、2回目は失敗」を作っています。

test('1回目は成功、2回目は失敗', async () => {
  const fetchPage = jest.fn()
    .mockResolvedValueOnce({ items: [1, 2], next: 2 })
    .mockRejectedValueOnce(new Error('timeout'));

  await expect(fetchPage(1)).resolves.toEqual({ items: [1, 2], next: 2 });
  await expect(fetchPage(2)).rejects.toThrow('timeout');
});

非同期関数のモック：mockResolvedValueとasyncの実装

mockResolvedValue(v) は mockImplementation(() => Promise.resolve(v)) の短縮形で、mockRejectedValue(e) は Promise.reject(e) を返す短縮形です。引数によって成功と失敗を分けたいときは、mockImplementation に async 関数を渡します。

test('非同期のモック', async () => {
  const ok = jest.fn().mockResolvedValue({ id: 1 });
  await expect(ok()).resolves.toEqual({ id: 1 });

  const ng = jest.fn().mockRejectedValue(new Error('not found'));
  await expect(ng()).rejects.toThrow('not found');

  // 引数で結果を変えるなら async 関数を渡す
  const findById = jest.fn().mockImplementation(async (id) => {
    if (id === 1) return { id, name: '佐藤' };
    throw new Error('not found');
  });
  await expect(findById(1)).resolves.toEqual({ id: 1, name: '佐藤' });
  await expect(findById(2)).rejects.toThrow('not found');
});

await expect(...).rejects の await も return も付けないと、Jest がアサーションの完了を待てず、誤判定につながるおそれがあります。アサーションが返す Promise は await するか、テスト関数から return します。失敗系のテストを書いたら、モックの値をわざと変えて赤くなることを一度確かめておくと安全です。

whenCalledWithによる引数ごとの戻り値（Jest 30.5.0以降）

JestのCHANGELOGによると、30.5.0（2026年8月28日公開）で mockFn.whenCalledWith(...args) が追加されました。指定した引数で呼ばれたときだけ働く戻り値や実装を登録するメソッドです。公式リファレンスの whenCalledWith の節は、日本語版のページでも本文が英語のままです。

if分岐のmockImplementationからの書き換え

whenCalledWith が返すのは通常のモックなので、mockReturnValue・mockResolvedValue・mockRejectedValue・mockImplementation とその Once 版をそのままつなげられます。どの登録にも一致しない呼び出しは、元のモックの実装に流れます。

test('引数ごとの戻り値を宣言的に書く', async () => {
  // 一致しない呼び出しは元のモックの実装（ここでは失敗）に流れる
  const getUser = jest.fn().mockRejectedValue(new Error('not found'));
  getUser.whenCalledWith(1).mockResolvedValue({ id: 1, name: '佐藤' });

  await expect(getUser(1)).resolves.toEqual({ id: 1, name: '佐藤' });
  await expect(getUser(2)).rejects.toThrow('not found');

  // 引数には expect.any などの非対称マッチャーも使える
  const label = jest.fn();
  label.whenCalledWith('apple').mockReturnValue('red');
  label.whenCalledWith(expect.any(Number)).mockReturnValue('numeric');
  expect([label('apple'), label(1), label('grape')])
    .toEqual(['red', 'numeric', undefined]);
});

上の getUser を mockImplementation で書くと、async 関数の中に if 文が1つ入ります。引数と戻り値の組が3つを超えるあたりから、whenCalledWith を並べた方が「どの入力に何を返すか」を一目で追えます。逆に、戻り値が引数から計算で決まる（n * 2 のような）場合は対応表にできないので、mockImplementation のままにします。Jest 30.5 未満が混在するモノレポでは使えない点にも注意が要ります。

whenCalledWithの引数一致判定と登録の優先順位

引数は深い等価で比較され、非対称マッチャーも使えます。ただし toHaveBeenCalledWith と違い、expect.addEqualityTesters で登録した独自の比較処理は whenCalledWith には適用されません。末尾に undefined が付く呼び出しは一致とみなされ、手元の実行では whenCalledWith('a') は fn('a', undefined) には一致し、fn('a', 'b') には一致しませんでした。複数の登録が同じ呼び出しに一致したときの優先順位は、公式で次のように決まっています。

元のモックで mockReset() を呼ぶと、whenCalledWith の登録もすべて消えます。テストごとにリセットする運用なら、登録は beforeEach かテスト本体の中で行います。

withImplementationによる一時的な差し替え（Jest 29.1.0以降）

withImplementation(fn, callback) は、コールバックを実行している間だけ実装を fn に差し替え、正常終了すると元の実装に戻します。ただし Jest 30.5.2 では、コールバックが例外を投げたり、返した Promise が reject されたりすると元に戻りません。異常終了も含めて復元する場合は、元の実装を保存しておき、try／finally で設定し直します。

test('コールバックの間だけ差し替える', async () => {
  const mock = jest.fn(() => 'outside');

  mock.withImplementation(() => 'inside', () => {
    expect(mock()).toBe('inside');
  });
  expect(mock()).toBe('outside');

  // コールバックが async なら Promise が返るので await する
  await mock.withImplementation(() => 'inside', async () => {
    expect(mock()).toBe('inside');
  });
  expect(mock()).toBe('outside');
});

1つのテストの中で「この区間だけ時刻を固定したい」「この呼び出しだけ失敗させたい」という場面で使います。

jest.mockとmockImplementationの組み合わせ

実務で mockImplementation を使う場面の多くは、テスト対象が import している別モジュールの関数を差し替えるケースです。ここでは、API クライアントの getUser を呼んで表示名を作る getDisplayName をテストします。テストダブル全般の考え方はモックとスタブの違いとテストダブル5分類で整理しています。

// src/apiClient.js
async function getUser(id) {
  const res = await fetch(`https://api.example.com/users/${id}`);
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res.json();
}
function buildUrl(path) {
  return `https://api.example.com${path}`;
}
module.exports = { getUser, buildUrl };

// src/userService.js
const { getUser } = require('./apiClient');
async function getDisplayName(id) {
  try {
    const user = await getUser(id);
    return `${user.name}さん`;
  } catch (e) {
    return 'ゲスト';
  }
}
module.exports = { getDisplayName };

自動モックとテストごとの実装の差し替え

jest.mock('./src/apiClient') とだけ書くと、モジュールのすべての関数が undefined を返すモック関数に置き換わります（自動モック）。各テストで必要な振る舞いを mockResolvedValue や mockImplementation で与えます。

jest.mock('./src/apiClient');
const { getUser } = require('./src/apiClient');
const { getDisplayName } = require('./src/userService');

beforeEach(() => {
  jest.resetAllMocks();
});

test('取得に成功したら名前に「さん」を付ける', async () => {
  getUser.mockResolvedValue({ id: 1, name: '佐藤' });
  await expect(getDisplayName(1)).resolves.toBe('佐藤さん');
  expect(getUser).toHaveBeenCalledWith(1);
});

test('取得に失敗したらゲストを返す', async () => {
  getUser.mockRejectedValue(new Error('HTTP 404'));
  await expect(getDisplayName(1)).resolves.toBe('ゲスト');
});

HTTP 層ごと差し替えるか、関数単位で差し替えるかの判断はAPIモッキングの方式選定で比較しています。関数単位のモックは実際のHTTP通信を省ける反面、モックが返すデータを更新しなければ、APIのレスポンス形式の変更をこのテストだけでは検出できません。

jest.requireActualによる部分モックと本物の関数の保持

jest.mock の第2引数に factory 関数を渡し、jest.requireActual で本物のモジュールを展開してから、差し替えたい関数だけ上書きします。

jest.mock('./src/apiClient', () => ({
  ...jest.requireActual('./src/apiClient'),
  getUser: jest.fn(),
}));
const { getUser, buildUrl } = require('./src/apiClient');

test('getUser だけモック、buildUrl は本物', () => {
  expect(buildUrl('/x')).toBe('https://api.example.com/x');
  expect(jest.isMockFunction(getUser)).toBe(true);
});

逆向きの jest.requireMock は、モジュールがモック化されているかどうかに関係なく、常にモック版を返します。

mockImplementationによるクラスのコンストラクタの差し替え

mockImplementation はクラスのコンストラクタにも使えます。new で呼ばれたときに返すオブジェクトを実装として渡します。

const Mailer = jest.fn();
const send = jest.fn().mockResolvedValue('ok');
Mailer.mockImplementation(() => ({ send }));

test('コンストラクタが返すインスタンスを差し替える', async () => {
  const mailer = new Mailer('smtp');
  await expect(mailer.send('hello')).resolves.toBe('ok');
  expect(Mailer).toHaveBeenCalledWith('smtp');
  expect(Mailer.mock.instances).toHaveLength(1);
});

jest.spyOnでの差し替えと元実装の復元

jest.spyOn(object, 'method') は既存オブジェクトのメソッドをモックで包みます。何も設定しなければ本物が実行され、mockImplementation を呼ぶと差し替わります。Date.now のように実行のたびに値が変わる関数を固定する用途でよく使います。

test('Date.now を固定して戻す', () => {
  const spy = jest.spyOn(Date, 'now').mockImplementation(() => 1767225600000);
  expect(Date.now()).toBe(1767225600000);

  spy.mockRestore();
  expect(jest.isMockFunction(Date.now)).toBe(false);
});

mockRestoreによる元実装の復元とspyOnの条件

公式リファレンスは、mockRestore() が元の実装に戻せるのは jest.spyOn() で作ったモックだけだと明記しています。jest.fn(impl) で作ったモックに mockRestore() を呼ぶと、手元の実行では impl にも戻らず undefined を返すようになりました。

Jest 30.0.0 からは using 宣言にも対応し、ブロックを抜けた時点で spyOn の差し替えが自動で戻ります（Node.js 26.5.0 で確認）。

test('using でブロックの終わりに自動で戻す', () => {
  const clock = { now: () => 'real' };
  {
    using spy = jest.spyOn(clock, 'now').mockImplementation(() => 'fixed');
    expect(clock.now()).toBe('fixed');
  }
  expect(clock.now()).toBe('real');
});

呼び出し記録の検証：mock.calls・mock.results・lastCall

差し替えた実装が「正しい引数で、正しい回数だけ」呼ばれたかは、モックが持つ記録で確かめます。

test('呼び出し記録を読む', () => {
  const tenTimes = jest.fn((x) => x * 10);
  tenTimes(1);
  tenTimes(2);

  expect(tenTimes.mock.calls).toEqual([[1], [2]]);
  expect(tenTimes.mock.results).toEqual([
    { type: 'return', value: 10 },
    { type: 'return', value: 20 },
  ]);
  expect(tenTimes.mock.lastCall).toEqual([2]);

  // マッチャーで書くと失敗時のメッセージが読みやすい
  expect(tenTimes).toHaveBeenCalledTimes(2);
  expect(tenTimes).toHaveBeenNthCalledWith(1, 1);
  expect(tenTimes).toHaveBeenLastCalledWith(2);
});

mock.calls は呼び出しごとの引数の配列、mock.results は戻り値か例外か（type は正常終了なら 'return'、例外なら 'throw'、呼び出しがまだ終了していなければ 'incomplete'）の配列です。アサーションには toHaveBeenCalledWith などのマッチャーを使い、mock.calls を直接読むのは「2回目の呼び出しで渡されたコールバックを取り出して実行する」ような場面に限ると、テストが読みやすく保てます。

mockClear・mockReset・mockRestoreの違い

3つは消す範囲が段階的に広がります。テスト間の汚染を防ぐ設定（clearMocks・resetMocks・restoreMocks）は、それぞれ各テストの前に一括処理を行います。ただし、restoreMocks の対象は jest.spyOn による差し替えと jest.replaceProperty による置換だけで、通常の jest.fn() の実装や呼び出し記録には触れません。3つとも既定値は false です。

使い分けは単純で、記録だけ消したいなら mockClear、テストごとに実装を設定し直す運用なら mockReset、spyOn で本物のオブジェクトを書き換えたなら mockRestore です。spyOn を使うテストファイルで restoreMocks を有効にしないまま放置すると、差し替えが後続のテストに漏れます。

JestとVitestのmockReset後の実装の違い

Vitest の vi.fn にも同名の mockImplementation があり、書き方はほぼ同じです。ただし Vitest のドキュメントでは、vi.fn(impl) に mockReset() を呼ぶと実装が impl に戻ると説明されています。Jest 30.5.2 で同じことをすると impl には戻らず undefined を返しました。Jest から Vitest へ移したテストが、リセット後の戻り値の違いで落ちる・通るが入れ替わることがあります。

mockImplementationが効かないときに確かめる5つの原因

「設定したはずの実装が呼ばれない」「undefined が返る」ときは、設定、変数の参照、関数の参照、Once、モジュール形式の順に確かめます。いずれも Jest 30.5.2 で再現を確かめています。

resetMocksによるfactory内のモック実装の消去

設定で resetMocks: true が有効だと、各テストの前に全モックの実装が消えます。jest.mock の factory の中で jest.fn().mockResolvedValue(...) と書いた実装も消え、テストの中では undefined が返ります。手元の実行でも、同じテストファイルが --resetMocks 付きでは undefined、無しでは Promise を返しました。公式の設定リファレンスにも「偽の実装を取り除く」と書かれています。プロジェクトの雛形が resetMocks を有効にしていることがあるので、まず jest.config.js と package.json の jest 欄を確かめ、有効なら実装の設定を beforeEach に移します。

jest.mockのfactoryにおける外側の変数の参照制限

jest.mock の呼び出しはファイル先頭へ巻き上げられるため、factory から外側の変数を参照すると「The module factory of jest.mock() is not allowed to reference any out-of-scope variables」で失敗します。babel-plugin-jest-hoist 30.5.0 のソースでは、例外が2つあります。変数名が mock で始まる場合（大文字小文字は問わない）と、再代入されない変数の初期値がリテラルのような副作用の無い式である場合です。手元の実行では const fakeUser = { id: 1 } は参照でき、const fakeUser = makeUser(1) は上のエラーになりました。関数呼び出しで作った値を使う場合、変数名を mockUser のようにすると参照制限の検査を回避できます。ただし、参照時点での初期化は別途必要です。factory内で未初期化の変数を読むとReferenceErrorになるため、初期化後に呼ばれるモック実装の中で参照するか、beforeEachで実装を設定します。

spyOn前に取得した関数参照の差し替え漏れ

jest.spyOn はオブジェクトのプロパティを置き換えるだけです。テスト対象が const { now } = util のように先に関数を取り出していると、取り出した参照は本物のままです。手元の実行でも、取り出し済みの now() は 'real'、util.now() は 'fixed' を返しました。この場合はテスト対象側で util.now() の形で呼ぶか、jest.mock でモジュールごと差し替えます。

mockClear後に残る未消費のOnce実装

mockClear() と clearMocks が消すのは呼び出し記録だけで、積んだ Once の残りは消えません。前のテストで消費しきれなかった mockImplementationOnce が、次のテストの1回目に返ってきます。Once を使うテストファイルでは mockReset() か resetMocks でリセットします。

ネイティブESMでのjest.mockの制約と代替API

ネイティブ ESM（"type": "module" や .mjs）のテストでは静的な import が先に評価されるので、jest.mock の巻き上げが効きません。公式のESMの解説のとおり、jest.unstable_mockModule で factory を登録してから、動的 import() でモジュールを読み込みます。名前のとおり実験的な API です。Babel や ts-jest で CommonJS に変換して動かしている構成なら、ここまでの書き方がそのまま使えます。

TypeScriptでの型付け：jest.fn<typeof fn>とjest.mocked

以下の TypeScript 例は、apiClient.ts が getUser(id: number): Promise<{ id: number; name: string }> という型の関数を公開している前提です。実行には、jest.mock の巻き上げに対応した CommonJS 向けの変換設定（babel-jest や ts-jest）も必要です。このようにモックに元の関数の型を持たせておくと、mockImplementation や mockResolvedValue に渡す値が型検査されます。jest.fn<typeof getUser>() で型引数を渡すか、jest.mock したモジュールの関数を jest.mocked() で包みます。

import { jest, test, expect } from '@jest/globals';
import { getUser } from './apiClient';

jest.mock('./apiClient');
const mockedGetUser = jest.mocked(getUser);

test('型付きのモック', async () => {
  mockedGetUser.mockResolvedValue({ id: 1, name: '佐藤' });

  const fn = jest.fn<typeof getUser>();
  fn.mockImplementation(async (id) => ({ id, name: String(id) }));
  fn.whenCalledWith(1).mockResolvedValue({ id: 1, name: 'a' });

  await expect(fn(1)).resolves.toEqual({ id: 1, name: 'a' });
});

この型付けでは、mockResolvedValue({ id: 1 }) のようにプロパティが足りない値や、whenCalledWith('1') のように引数の型が違う呼び出しが tsc --strict でエラーになります（TypeScript 5 系で確認）。Jest 30 で jest.SpyInstance 型は削除されたので、spyOn の型注釈には jest.Spied を使います。

テストの書き方を揃えたい、既存のテストが脆くて保守に手間がかかっている、という場合は保守運用・内製化支援でテスト基盤の見直しから相談を受けています。

よくある質問

mockImplementationとmockReturnValueの違いは？

mockReturnValue(v) は引数に関係なく常に v を返します。mockImplementation(fn) は渡した関数を毎回実行するので、引数に応じて戻り値を変えたり、例外を投げたりできます。返す値が固定なら mockReturnValue、引数で変わるなら mockImplementation を使います。Jest 30.5.0 以降で、引数と戻り値の組が決まっているだけなら whenCalledWith も選べます。

mockResolvedValueOnceは何回まで積めますか？

回数の上限はなく、呼び出し順に1回ずつ消費されます。mockRejectedValueOnce や mockImplementationOnce と混ぜて積むこともでき、「1回目は成功、2回目は失敗」のような順序を作れます。積んだ分を使い切ると、mockResolvedValue などで設定した既定の値に戻り、既定が無ければ undefined を返します。

jest.requireActualとjest.requireMockの違いは？

jest.requireActual はモックを迂回して本物のモジュールを返します。jest.mock の factory の中で展開し、一部の関数だけ差し替える部分モックに使います。jest.requireMock は逆で、モック化の有無にかかわらずモック版のモジュールを返します。

mockImplementationで差し替えた実装を元に戻すには？

jest.spyOn で作ったモックなら mockRestore() で本物に戻ります。jest.fn(impl) で作ったモックは mockRestore() でも impl に戻らず undefined を返すようになるので、mockImplementation(impl) で設定し直します。一時的な差し替えには withImplementation を使えます。ただし、Jest 30.5.2ではコールバックの例外・reject時に復元されないため、異常終了時の後始末は別途必要です。

Vitestでもmockimplementationは同じ書き方ですか？

vi.fn().mockImplementation(fn) と同じ名前・同じ書き方で使えます。違いが出やすいのはリセットで、Vitest では vi.fn(impl) に mockReset() を呼ぶと impl に戻り、Jest では undefined を返すようになります。移行時のその他の差分はVitest 5移行ガイドにまとめています。

関連記事

• モックとは？スタブとの違い・テストダブル5分類と5言語の書き方を実行例で解説
• APIモッキングとは？モックサーバーの方式選定と契約ドリフト対策を実装目線で解説
• Vitestの使い方と書き方：読み方・設定からReact Testing Libraryのコンポーネントテストまで【Vitest 5対応】
• Vitest 5移行ガイド：4からの破壊的変更・新機能と落ちるテストの直し方【5.0.5で実測】
• React Testing Libraryとは？使い方・Vitest・Jestの設定とベストプラクティス【v16.3.3】