# API設計書

## 概要

本ドキュメントは、Jest JavaScriptテスティングフレームワークのプログラミングAPI設計書です。Jestは55以上のパッケージで構成されるモノレポであり、テスト実行、アサーション、モック、スナップショットテストなどの機能を提供します。

**注意**: JestはHTTP APIを提供するWebサービスではなく、JavaScriptテスティングフレームワークです。本ドキュメントでは、開発者が利用するJavaScript/TypeScript APIを記載します。

## 共通仕様

### インストール

```bash
npm install --save-dev jest
```

### 基本的な使用方法

```javascript
// jest.config.js
module.exports = {
  testEnvironment: 'node',
};

// または ES Modules
import { defineConfig } from 'jest';
export default defineConfig({
  testEnvironment: 'node',
});
```

### サポートするNode.jsバージョン

- Node.js ^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0

### 主要パッケージ

| パッケージ名 | 説明 |
| --- | --- |
| jest | メインエントリーポイント |
| @jest/globals | グローバルAPI（test, expect等） |
| jest-mock | モック関数の作成 |
| expect | アサーションライブラリ |
| jest-snapshot | スナップショットテスト |
| jest-config | 設定管理 |

## API一覧

| カテゴリ | API | 説明 |
| --- | --- | --- |
| グローバルAPI | test / it | テストケースを定義 |
| グローバルAPI | describe | テストスイートを定義 |
| グローバルAPI | beforeAll / afterAll | スイート前後のフック |
| グローバルAPI | beforeEach / afterEach | テスト前後のフック |
| アサーション | expect | アサーションの起点 |
| モック | jest.fn() | モック関数の作成 |
| モック | jest.spyOn() | 既存関数のスパイ |
| モック | jest.mock() | モジュールのモック |
| タイマー | jest.useFakeTimers() | フェイクタイマーの有効化 |
| スナップショット | toMatchSnapshot() | スナップショットテスト |
| 設定 | defineConfig() | 設定ヘルパー |

## 各API定義

### グローバルAPI

#### 1. test / it

テストケースを定義します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| パッケージ | @jest/globals |
| エクスポート | Named Export |

**シグネチャ**

```typescript
test(name: TestNameLike, fn: TestFn, timeout?: number): void
it(name: TestNameLike, fn: TestFn, timeout?: number): void
```

**パラメータ**

| パラメータ名 | 型 | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| name | string \| number \| Function | ○ | - | テスト名 |
| fn | TestFn | ○ | - | テスト関数 |
| timeout | number | - | 5000 | タイムアウト（ミリ秒） |

**使用例**

```javascript
import { test, expect } from '@jest/globals';

test('adds 1 + 2 to equal 3', () => {
  expect(1 + 2).toBe(3);
});

// async/await
test('async test', async () => {
  const data = await fetchData();
  expect(data).toBe('data');
});

// done callback
test('callback test', done => {
  fetchCallback(data => {
    expect(data).toBe('data');
    done();
  });
});
```

**バリエーション**

| API | 説明 |
| --- | --- |
| test.only / it.only | このテストのみ実行 |
| test.skip / it.skip | テストをスキップ |
| test.todo | 未実装テストのプレースホルダー |
| test.each | パラメータ化テスト |
| test.concurrent | 並列テスト実行 |
| test.failing | 失敗することを期待するテスト |

---

#### 2. describe

テストスイート（テストグループ）を定義します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| パッケージ | @jest/globals |
| エクスポート | Named Export |

**シグネチャ**

```typescript
describe(name: BlockNameLike, fn: BlockFn): void
```

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| name | string \| number \| Function | ○ | スイート名 |
| fn | () => void | ○ | テストブロック |

**使用例**

```javascript
describe('Math operations', () => {
  describe('addition', () => {
    test('adds positive numbers', () => {
      expect(1 + 2).toBe(3);
    });
  });
});
```

**バリエーション**

| API | 説明 |
| --- | --- |
| describe.only / fdescribe | このスイートのみ実行 |
| describe.skip / xdescribe | スイートをスキップ |
| describe.each | パラメータ化スイート |

---

#### 3. beforeAll / afterAll

テストスイートの前後に一度だけ実行されるフック。

**シグネチャ**

```typescript
beforeAll(fn: HookFn, timeout?: number): void
afterAll(fn: HookFn, timeout?: number): void
```

**パラメータ**

| パラメータ名 | 型 | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| fn | HookFn | ○ | - | フック関数 |
| timeout | number | - | 5000 | タイムアウト（ミリ秒） |

**使用例**

```javascript
let db;

beforeAll(async () => {
  db = await connectDatabase();
});

afterAll(async () => {
  await db.close();
});
```

---

#### 4. beforeEach / afterEach

各テストの前後に実行されるフック。

**シグネチャ**

```typescript
beforeEach(fn: HookFn, timeout?: number): void
afterEach(fn: HookFn, timeout?: number): void
```

**使用例**

```javascript
beforeEach(() => {
  initializeTestData();
});

afterEach(() => {
  cleanupTestData();
});
```

---

### アサーションAPI（expect）

#### 5. expect

アサーションの起点となる関数。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| パッケージ | expect / @jest/globals |
| エクスポート | Named Export |

**シグネチャ**

```typescript
expect(actual: any): Matchers
```

**マッチャー一覧（Equality）**

| マッチャー | 説明 |
| --- | --- |
| toBe(expected) | Object.is による厳密等価性 |
| toEqual(expected) | 深い等価性（値の比較） |
| toStrictEqual(expected) | 厳密な深い等価性（型も比較） |

**マッチャー一覧（Truthiness）**

| マッチャー | 説明 |
| --- | --- |
| toBeTruthy() | truthy な値か |
| toBeFalsy() | falsy な値か |
| toBeNull() | null か |
| toBeUndefined() | undefined か |
| toBeDefined() | undefined でないか |
| toBeNaN() | NaN か |

**マッチャー一覧（Numbers）**

| マッチャー | 説明 |
| --- | --- |
| toBeGreaterThan(expected) | より大きい |
| toBeGreaterThanOrEqual(expected) | 以上 |
| toBeLessThan(expected) | より小さい |
| toBeLessThanOrEqual(expected) | 以下 |
| toBeCloseTo(expected, precision?) | 浮動小数点の近似比較 |

**マッチャー一覧（Strings）**

| マッチャー | 説明 |
| --- | --- |
| toMatch(regexp \| string) | 正規表現または文字列にマッチ |
| toContain(item) | 文字列に含まれる |

**マッチャー一覧（Arrays/Iterables）**

| マッチャー | 説明 |
| --- | --- |
| toContain(item) | 配列に含まれる |
| toContainEqual(item) | 深い等価で含まれる |
| toHaveLength(number) | 長さが一致 |

**マッチャー一覧（Objects）**

| マッチャー | 説明 |
| --- | --- |
| toHaveProperty(keyPath, value?) | プロパティを持つ |
| toMatchObject(object) | オブジェクトの部分一致 |
| toBeInstanceOf(Class) | クラスのインスタンス |

**マッチャー一覧（Exceptions）**

| マッチャー | 説明 |
| --- | --- |
| toThrow(error?) | 例外をスロー |
| toThrowError(error?) | toThrowのエイリアス |

**使用例**

```javascript
// 基本的なアサーション
expect(2 + 2).toBe(4);
expect({ a: 1 }).toEqual({ a: 1 });

// 否定
expect(1).not.toBe(2);

// Promise
await expect(Promise.resolve('data')).resolves.toBe('data');
await expect(Promise.reject('error')).rejects.toMatch('error');
```

**修飾子**

| 修飾子 | 説明 |
| --- | --- |
| .not | マッチャーの否定 |
| .resolves | Promise の解決値をテスト |
| .rejects | Promise の拒否値をテスト |

---

#### 6. 非対称マッチャー

部分的なマッチングに使用。

| API | 説明 |
| --- | --- |
| expect.anything() | null/undefined 以外 |
| expect.any(Constructor) | 指定クラスのインスタンス |
| expect.stringContaining(string) | 文字列を含む |
| expect.stringMatching(regexp) | 正規表現にマッチ |
| expect.arrayContaining(array) | 配列要素を含む |
| expect.objectContaining(object) | オブジェクトを含む |
| expect.closeTo(number, precision?) | 近似値 |

**使用例**

```javascript
expect({ name: 'Alice', age: 30 }).toEqual({
  name: expect.any(String),
  age: expect.anything(),
});
```

---

#### 7. アサーションカウント

| API | 説明 |
| --- | --- |
| expect.assertions(number) | 期待するアサーション数 |
| expect.hasAssertions() | 1つ以上のアサーション |

---

### モックAPI

#### 8. jest.fn()

モック関数を作成します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| パッケージ | jest-mock |
| エクスポート | Named Export |

**シグネチャ**

```typescript
fn<T extends FunctionLike = UnknownFunction>(implementation?: T): Mock<T>
```

**使用例**

```javascript
const mockFn = jest.fn();
mockFn('arg1', 'arg2');

expect(mockFn).toHaveBeenCalled();
expect(mockFn).toHaveBeenCalledWith('arg1', 'arg2');

// 実装を提供
const mockAdd = jest.fn((a, b) => a + b);
expect(mockAdd(1, 2)).toBe(3);

// 戻り値を設定
const mockValue = jest.fn().mockReturnValue(42);
expect(mockValue()).toBe(42);
```

**Mock インスタンスのプロパティ**

| プロパティ | 説明 |
| --- | --- |
| mock.calls | すべての呼び出し引数の配列 |
| mock.results | すべての戻り値/例外の配列 |
| mock.instances | new で作成されたインスタンス |
| mock.contexts | 呼び出し時の this コンテキスト |
| mock.lastCall | 最後の呼び出し引数 |

**Mock インスタンスのメソッド**

| メソッド | 説明 |
| --- | --- |
| mockClear() | mock プロパティをリセット |
| mockReset() | mockClear + 実装をリセット |
| mockRestore() | 元の実装を復元（spyOn用） |
| mockImplementation(fn) | 実装を設定 |
| mockImplementationOnce(fn) | 一度だけの実装 |
| mockReturnValue(value) | 戻り値を設定 |
| mockReturnValueOnce(value) | 一度だけの戻り値 |
| mockResolvedValue(value) | Promise.resolve 戻り値 |
| mockResolvedValueOnce(value) | 一度だけの Promise.resolve |
| mockRejectedValue(value) | Promise.reject 戻り値 |
| mockRejectedValueOnce(value) | 一度だけの Promise.reject |
| mockReturnThis() | this を返す |
| mockName(name) | モック名を設定 |
| getMockName() | モック名を取得 |
| withImplementation(fn, callback) | 一時的な実装 |

---

#### 9. jest.spyOn()

既存のオブジェクトメソッドをスパイします。

**シグネチャ**

```typescript
spyOn<T extends object>(
  object: T,
  methodKey: keyof T,
  accessType?: 'get' | 'set'
): MockInstance
```

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| object | object | ○ | 対象オブジェクト |
| methodKey | keyof T | ○ | メソッド名 |
| accessType | 'get' \| 'set' | - | アクセサタイプ |

**使用例**

```javascript
const video = {
  play() { return true; },
  get volume() { return 0.5; }
};

const spy = jest.spyOn(video, 'play');
video.play();
expect(spy).toHaveBeenCalled();

// getter をスパイ
const volumeSpy = jest.spyOn(video, 'volume', 'get');
expect(video.volume).toBe(0.5);

spy.mockRestore();
```

---

#### 10. jest.replaceProperty()

オブジェクトのプロパティを置き換えます。

**シグネチャ**

```typescript
replaceProperty<T extends object, K extends keyof T>(
  object: T,
  propertyKey: K,
  value: T[K]
): Replaced<T[K]>
```

**使用例**

```javascript
const utils = { version: '1.0.0' };

const replaced = jest.replaceProperty(utils, 'version', '2.0.0');
expect(utils.version).toBe('2.0.0');

replaced.restore();
expect(utils.version).toBe('1.0.0');
```

---

#### 11. jest.mock()

モジュールをモックします。

**シグネチャ**

```typescript
mock<T = unknown>(
  moduleName: string,
  moduleFactory?: () => T,
  options?: { virtual?: boolean }
): Jest
```

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| moduleName | string | ○ | モジュールパス |
| moduleFactory | () => T | - | モジュールファクトリ |
| options.virtual | boolean | - | 仮想モジュール |

**使用例**

```javascript
// 自動モック
jest.mock('./myModule');

// ファクトリでモック
jest.mock('./myModule', () => ({
  myFunction: jest.fn(() => 'mocked'),
}));

// ES Modules
jest.mock('./myModule', () => ({
  __esModule: true,
  default: jest.fn(),
  namedExport: jest.fn(),
}));
```

---

#### 12. モック関連マッチャー

| マッチャー | 説明 |
| --- | --- |
| toHaveBeenCalled() | 呼び出された |
| toHaveBeenCalledTimes(number) | 指定回数呼び出された |
| toHaveBeenCalledWith(...args) | 指定引数で呼び出された |
| toHaveBeenLastCalledWith(...args) | 最後の呼び出し引数 |
| toHaveBeenNthCalledWith(n, ...args) | n回目の呼び出し引数 |
| toHaveReturned() | 戻り値がある |
| toHaveReturnedTimes(number) | 指定回数戻った |
| toHaveReturnedWith(value) | 指定値を返した |
| toHaveLastReturnedWith(value) | 最後の戻り値 |
| toHaveNthReturnedWith(n, value) | n回目の戻り値 |

---

### タイマーAPI

#### 13. jest.useFakeTimers()

フェイクタイマーを有効にします。

**シグネチャ**

```typescript
useFakeTimers(
  fakeTimersConfig?: FakeTimersConfig | LegacyFakeTimersConfig
): Jest
```

**設定オプション（FakeTimersConfig）**

| オプション | 型 | 説明 |
| --- | --- | --- |
| advanceTimers | boolean \| number | 自動進行 |
| doNotFake | string[] | モックしないAPI |
| now | number \| Date | 初期時刻 |
| timerLimit | number | タイマー実行上限 |

**使用例**

```javascript
jest.useFakeTimers();

const callback = jest.fn();
setTimeout(callback, 1000);

jest.advanceTimersByTime(1000);
expect(callback).toHaveBeenCalled();

jest.useRealTimers();
```

---

#### 14. タイマー制御メソッド

| メソッド | 説明 |
| --- | --- |
| advanceTimersByTime(ms) | 指定ミリ秒進める |
| advanceTimersByTimeAsync(ms) | 非同期で進める |
| advanceTimersToNextTimer(steps?) | 次のタイマーまで進める |
| advanceTimersToNextTimerAsync(steps?) | 非同期で次のタイマーまで |
| advanceTimersToNextFrame() | requestAnimationFrame まで |
| runAllTimers() | すべてのタイマーを実行 |
| runAllTimersAsync() | 非同期ですべて実行 |
| runOnlyPendingTimers() | 保留中のタイマーのみ実行 |
| runOnlyPendingTimersAsync() | 非同期で保留中のみ |
| runAllTicks() | マイクロタスクキューを処理 |
| clearAllTimers() | すべてのタイマーをクリア |
| getTimerCount() | 残りタイマー数 |
| setSystemTime(now) | システム時刻を設定 |
| getRealSystemTime() | 実際の時刻を取得 |
| now() | 現在のフェイク時刻 |
| useRealTimers() | リアルタイマーに戻す |

---

### スナップショットAPI

#### 15. toMatchSnapshot()

スナップショットテストを実行します。

**シグネチャ**

```typescript
toMatchSnapshot(propertyMatchers?: object, hint?: string): void
toMatchSnapshot(hint?: string): void
```

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| propertyMatchers | object | - | 動的プロパティのマッチャー |
| hint | string | - | スナップショット名のヒント |

**使用例**

```javascript
test('snapshot test', () => {
  const tree = renderer.create(<App />).toJSON();
  expect(tree).toMatchSnapshot();
});

// プロパティマッチャー
expect(user).toMatchSnapshot({
  createdAt: expect.any(Date),
  id: expect.any(Number),
});
```

---

#### 16. toMatchInlineSnapshot()

インラインスナップショットテスト。

**シグネチャ**

```typescript
toMatchInlineSnapshot(propertyMatchers?: object, inlineSnapshot?: string): void
toMatchInlineSnapshot(inlineSnapshot?: string): void
```

**使用例**

```javascript
expect({ name: 'Jest' }).toMatchInlineSnapshot(`
  Object {
    "name": "Jest",
  }
`);
```

---

#### 17. スナップショット関連API

| API | 説明 |
| --- | --- |
| toThrowErrorMatchingSnapshot() | エラーのスナップショット |
| toThrowErrorMatchingInlineSnapshot() | インラインエラースナップショット |
| expect.addSnapshotSerializer(serializer) | シリアライザを追加 |

---

### 設定API

#### 18. defineConfig()

型安全な設定ヘルパー。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| パッケージ | jest-config / jest |
| エクスポート | Named Export |

**シグネチャ**

```typescript
defineConfig(config: InitialOptions): InitialOptions
defineConfig(config: Promise<InitialOptions>): Promise<InitialOptions>
defineConfig(config: () => InitialOptions): () => InitialOptions
```

**使用例**

```javascript
// jest.config.js
import { defineConfig } from 'jest';

export default defineConfig({
  testEnvironment: 'node',
  transform: {},
});
```

---

#### 19. mergeConfig()

設定をマージします。

**シグネチャ**

```typescript
mergeConfig<D, O>(defaults: D, overrides: O): InitialOptions
```

**使用例**

```javascript
import { defineConfig, mergeConfig } from 'jest';
import baseConfig from './jest.config.base';

export default defineConfig(
  mergeConfig(baseConfig, {
    testEnvironment: 'jsdom',
  })
);
```

---

### コアAPI

#### 20. runCLI()

プログラムからJestを実行します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| パッケージ | @jest/core / jest |
| エクスポート | Named Export |

**シグネチャ**

```typescript
runCLI(
  argv: Config.Argv,
  projects: Array<string>
): Promise<{
  results: AggregatedResult;
  globalConfig: GlobalConfig;
}>
```

**使用例**

```javascript
import { runCLI } from 'jest';

const { results } = await runCLI(
  { _: [], $0: '' },
  [process.cwd()]
);

console.log(`Tests: ${results.numPassedTests} passed`);
```

---

#### 21. createTestScheduler()

テストスケジューラを作成します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| パッケージ | @jest/core |
| エクスポート | Named Export |

---

#### 22. SearchSource

テストファイルを検索するクラス。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| パッケージ | @jest/core |
| エクスポート | Named Export |

---

### その他のJest API

#### 23. モジュール制御

| メソッド | 説明 |
| --- | --- |
| jest.resetModules() | モジュールキャッシュをリセット |
| jest.isolateModules(fn) | 分離されたモジュールスコープ |
| jest.isolateModulesAsync(fn) | 非同期版 |
| jest.requireActual(moduleName) | 実際のモジュールを取得 |
| jest.requireMock(moduleName) | モックモジュールを取得 |
| jest.unmock(moduleName) | モックを解除 |
| jest.doMock(moduleName, factory) | ホイストなしモック |
| jest.dontMock(moduleName) | ホイストなしアンモック |
| jest.deepUnmock(moduleName) | 依存関係も含めアンモック |
| jest.setMock(moduleName, exports) | モックを明示的に設定 |

---

#### 24. オートモック制御

| メソッド | 説明 |
| --- | --- |
| jest.enableAutomock() | オートモック有効化 |
| jest.disableAutomock() | オートモック無効化 |
| jest.autoMockOn() | enableAutomock のエイリアス |
| jest.autoMockOff() | disableAutomock のエイリアス |
| jest.createMockFromModule(moduleName) | モジュールからモック生成 |

---

#### 25. モック状態制御

| メソッド | 説明 |
| --- | --- |
| jest.clearAllMocks() | すべてのモックをクリア |
| jest.resetAllMocks() | すべてのモックをリセット |
| jest.restoreAllMocks() | すべてのモックを復元 |

---

#### 26. ユーティリティ

| メソッド | 説明 |
| --- | --- |
| jest.setTimeout(timeout) | デフォルトタイムアウト設定 |
| jest.retryTimes(numRetries, options?) | テストリトライ設定 |
| jest.getSeed() | ランダムシード取得 |
| jest.isEnvironmentTornDown() | 環境破棄済みか確認 |
| jest.isMockFunction(fn) | モック関数か判定 |
| jest.mocked(source, options?) | 型付きモックヘルパー |

---

### 型定義

#### 27. 主要な型

```typescript
// テスト関数
type TestFn =
  | PromiseReturningTestFn
  | GeneratorReturningTestFn
  | DoneTakingTestFn;

// モック関数
interface Mock<T extends FunctionLike = UnknownFunction> {
  (...args: Parameters<T>): ReturnType<T>;
  mock: MockFunctionState<T>;
  mockClear(): this;
  mockReset(): this;
  mockRestore(): void;
  mockImplementation(fn: T): this;
  // ... その他のメソッド
}

// 設定
type Config = {
  testEnvironment?: string;
  transform?: Record<string, string>;
  // ... その他のオプション
};
```

---

## 備考

### バージョン互換性

- 本ドキュメントは Jest のメインブランチを基に作成しています
- 一部のAPIは `jest-circus` ランナー専用です
- レガシーフェイクタイマーは非推奨です

### 参考リンク

- 公式ドキュメント: https://jestjs.io
- GitHub: https://github.com/jestjs/jest
- API リファレンス: https://jestjs.io/docs/api

### 更新履歴

| 日付 | 内容 |
| --- | --- |
| 2026-03-01 | 初版作成 |
