Jest でテストを書き始めると、誰もが一度は疑問に思うことがあります。「describe と it と test は何が違うのか？」「どれを使えばいいのか？」これらの API は機能的に重複する部分もあり、適切な使い分けが分からないまま開発を進めてしまうことが多いのです。

この記事では、Jest における describe・it・test の正確な理解と実践的な活用方法について詳しく解説いたします。各 API の設計思想から実際のコード例まで、テスト記述の品質向上に役立つ知識を体系的に学んでいきましょう。

Jest API の背景

describe・it・test の設計思想

Jest の describe・it・test は、それぞれ異なる設計思想に基づいて作られています。これらの背景を理解することで、適切な使い分けができるようになるでしょう。

describe の役割

describe は、関連するテストをグループ化するためのコンテナとして設計されています。この API は、テストの構造化と可読性の向上を主目的としており、実際のテスト実行は行いません。

javascriptCopy code// describe の基本的な使用例
describe('ユーザー管理機能', () => {
  // ここに関連するテストが入る
  describe('ユーザー作成', () => {
    // より具体的なグループ化
  });

  describe('ユーザー更新', () => {
    // 機能別のグループ化
  });
});

it の設計哲学

it は BDD（Behavior Driven Development）スタイルを意識した設計になっています。「それは〜する」という自然言語的な表現を重視し、テストの意図を明確に表現することを目的としています。

javascriptCopy code// it による自然言語的な表現
describe('Calculator', () => {
  it('should add two numbers correctly', () => {
    // テストの実装
  });

  it('should handle division by zero', () => {
    // エラーケースのテスト
  });
});

test の位置づけ

test は it のエイリアスとして提供されており、機能的には完全に同じです。より直接的で簡潔な表現を好む開発者のために用意されており、テストの実装に集中したい場合に適しています。

BDD スタイルテストとの関係性

Jest の API 設計は、BDD（振る舞い駆動開発）の考え方を強く反映しています。BDD では、ソフトウェアの振る舞いを自然言語に近い形で記述することが重視されるのです。

BDD における階層構造

BDD では、一般的に以下のような階層構造でテストを記述します：

1. Feature（機能）- システム全体の大きな機能
2. Scenario（シナリオ）- 特定の条件下での振る舞い
3. Given/When/Then - 具体的なテストステップ

Jest の describe と it は、この BDD の構造を JavaScript のテストコードで表現するために設計されています。

javascriptCopy code// BDD スタイルの Jest テスト例
describe('Feature: ショッピングカート機能', () => {
  describe('Scenario: 商品をカートに追加', () => {
    it('should add item to cart when valid product is selected', () => {
      // Given: 有効な商品が選択されている
      // When: カートに追加ボタンを押す
      // Then: 商品がカートに追加される
    });
  });
});

自然言語との対応関係

BDD スタイルでは、テストケースを自然言語で読み上げた時に意味が通るよう記述することが推奨されます。Jest の API もこの思想を継承しています。

#	BDD 要素	Jest API	自然言語表現
1	Feature	describe	「〜機能について」
2	Scenario	describe	「〜の場合」
3	Example	it/test	「それは〜する」

API 使い分けの課題

機能的な重複と混乱ポイント

Jest を使い始めた開発者が最初に困惑するのは、it と test が機能的に全く同じであることです。この重複は意図的な設計ですが、適切な使い分けのルールがないと、チーム内で記述方法が統一されません。

it と test の完全な等価性

実際に Jest のソースコードを確認すると、test は単純に it のエイリアスとして定義されています。つまり、どちらを使用しても実行結果は全く同じになります。

javascriptCopy code// これらは完全に同じ動作をします
it('calculates sum correctly', () => {
  expect(add(2, 3)).toBe(5);
});

test('calculates sum correctly', () => {
  expect(add(2, 3)).toBe(5);
});

混乱を招く使い分けパターン

実際のプロジェクトで見かける混乱しやすいパターンを示します：

javascriptCopy code// 悪い例：一貫性のない使い分け
describe('Math utilities', () => {
  it('should add numbers', () => {
    // it を使用
  });

  test('should subtract numbers', () => {
    // 同じファイル内で test を使用
  });

  it('should multiply numbers', () => {
    // 再び it を使用
  });
});

このような不統一な記述は、コードレビューで指摘されることが多く、チーム開発での摩擦の原因となります。

Jest 特有の動作の違い

Jest には、他のテストフレームワークとは異なる特有の動作があります。これらを理解せずに使い分けを行うと、期待しない結果になる場合があります。

describe のスコープ動作

Jest の describe は、単純なグループ化以上の機能を持っています。特に、変数のスコープや setup/teardown の実行タイミングに影響を与えます。

javascriptCopy code// Jest 特有のスコープ動作
describe('スコープの動作例', () => {
  let sharedVariable;

  beforeEach(() => {
    sharedVariable = 'initialized';
  });

  describe('ネストしたスコープ', () => {
    beforeEach(() => {
      // 親の beforeEach の後に実行される
      sharedVariable += ' and extended';
    });

    it('should have access to modified variable', () => {
      expect(sharedVariable).toBe(
        'initialized and extended'
      );
    });
  });
});

テスト実行順序の制御

Jest では、describe のネスト構造によってテストの実行順序が決まります。この順序は、テスト間の依存関係がある場合に重要になります。

javascriptCopy code// 実行順序の例
describe('外側のグループ', () => {
  console.log('外側の describe が評価される');

  beforeAll(() => console.log('外側の beforeAll'));
  beforeEach(() => console.log('外側の beforeEach'));

  it('最初のテスト', () => {
    console.log('最初のテスト実行');
  });

  describe('内側のグループ', () => {
    console.log('内側の describe が評価される');

    beforeEach(() => console.log('内側の beforeEach'));

    it('内側のテスト', () => {
      console.log('内側のテスト実行');
    });
  });
});

Jest における使い分け原則

describe のグループ化戦略

describe の効果的な使用には、明確なグループ化戦略が必要です。適切にグループ化されたテストは、保守性と可読性を大幅に向上させるでしょう。

機能ベースのグループ化

最も基本的なアプローチは、テストする機能に基づいてグループ化する方法です。これにより、関連するテストケースが一箇所にまとまり、理解しやすくなります。

javascriptCopy code// 機能ベースのグループ化例
describe('UserService', () => {
  describe('ユーザー作成機能', () => {
    it('should create user with valid data', () => {
      // ユーザー作成の正常ケース
    });

    it('should reject invalid email format', () => {
      // バリデーションエラーのテスト
    });
  });

  describe('ユーザー検索機能', () => {
    it('should find user by id', () => {
      // ID による検索
    });

    it('should return null for non-existent user', () => {
      // 存在しないユーザーの処理
    });
  });
});

条件ベースのグループ化

特定の条件や状態に基づいてテストをグループ化する方法も効果的です。これは、同じ機能でも異なる条件での動作をテストする場合に有用でしょう。

javascriptCopy code// 条件ベースのグループ化例
describe('ShoppingCart', () => {
  describe('カートが空の場合', () => {
    it('should show empty cart message', () => {
      // 空カートの表示テスト
    });

    it('should disable checkout button', () => {
      // チェックアウトボタンの無効化
    });
  });

  describe('カートに商品がある場合', () => {
    beforeEach(() => {
      // 商品を追加するセットアップ
    });

    it('should display total price', () => {
      // 合計金額の表示
    });

    it('should enable checkout button', () => {
      // チェックアウトボタンの有効化
    });
  });
});

階層の深さ制御

describe のネストは、3 層以下に抑えることが推奨されます。深すぎる階層は、かえってテストの理解を困難にしてしまいます。

javascriptCopy code// 適切な階層の例（3層）
describe('E-commerce App', () => {
  // 1層目：アプリケーション
  describe('Product Management', () => {
    // 2層目：機能
    describe('when user is admin', () => {
      // 3層目：条件
      it('should allow product creation', () => {
        // テストの実装
      });
    });
  });
});

it vs test の実践的判断基準

it と test の使い分けには、いくつかの実践的なアプローチがあります。チームでの統一性を保つため、明確な基準を設けることが重要です。

文脈重視のアプローチ

BDD スタイルを重視する場合は、自然言語として読みやすい it を選択します。一方で、より技術的で直接的な表現を好む場合は test を使用するという使い分けが可能です。

javascriptCopy code// BDD スタイル重視の場合
describe('User authentication', () => {
  it('should authenticate user with valid credentials', () => {
    // "it should authenticate..." が自然な英語
  });

  it('should reject invalid password', () => {
    // "it should reject..." も自然
  });
});

// 技術的アプローチの場合
describe('Password validation', () => {
  test('valid password passes validation', () => {
    // より直接的な表現
  });

  test('empty password fails validation', () => {
    // 簡潔で明確
  });
});

プロジェクト標準化のアプローチ

最も実用的なアプローチは、プロジェクト内で一つの API に統一することです。これにより、コードレビューでの議論を減らし、開発効率を向上させられます。

javascriptCopy code// プロジェクト標準：it を統一使用
describe('API endpoints', () => {
  it('should return user data for GET /users/:id', () => {
    // 統一された記述
  });

  it('should create user for POST /users', () => {
    // 一貫性のある表現
  });

  it('should update user for PUT /users/:id', () => {
    // 読みやすい構造
  });
});

文字数と可読性のバランス

test は it より 2 文字短いため、長いテスト名の場合には可読性の向上に寄与する場合があります。ただし、この差は実際の開発では大きな影響を与えません。

#	比較項目	it	test
1	文字数	2 文字	4 文字
2	自然言語性	高い	中程度
3	技術的明確性	中程度	高い
4	BDD 親和性	高い	低い

Jest 実践パターン解説

単純な関数テストでの使い分け

最も基本的な関数のテストから、実践的な使い分けパターンを見ていきましょう。単純な関数のテストでは、明確で読みやすい構造を作ることが重要です。

数学関数のテストパターン

javascriptCopy code// 数学ライブラリのテスト例
describe('Math utilities', () => {
  describe('add function', () => {
    it('should return sum of two positive numbers', () => {
      expect(add(2, 3)).toBe(5);
      expect(add(10, 15)).toBe(25);
    });

    it('should handle negative numbers correctly', () => {
      expect(add(-2, 3)).toBe(1);
      expect(add(-5, -3)).toBe(-8);
    });

    it('should handle zero values', () => {
      expect(add(0, 5)).toBe(5);
      expect(add(0, 0)).toBe(0);
    });
  });

  describe('divide function', () => {
    it('should divide numbers correctly', () => {
      expect(divide(10, 2)).toBe(5);
      expect(divide(9, 3)).toBe(3);
    });

    it('should throw error for division by zero', () => {
      expect(() => divide(10, 0)).toThrow(
        'Division by zero'
      );
    });
  });
});

文字列処理関数のテストパターン

javascriptCopy code// 文字列ユーティリティのテスト
describe('String utilities', () => {
  describe('capitalize function', () => {
    it('should capitalize first letter of string', () => {
      expect(capitalize('hello')).toBe('Hello');
      expect(capitalize('world')).toBe('World');
    });

    it('should handle empty string', () => {
      expect(capitalize('')).toBe('');
    });

    it('should handle single character', () => {
      expect(capitalize('a')).toBe('A');
    });

    it('should not change already capitalized string', () => {
      expect(capitalize('Hello')).toBe('Hello');
    });
  });

  describe('truncate function', () => {
    it('should truncate long strings', () => {
      expect(truncate('Hello World', 5)).toBe('Hello...');
    });

    it('should not truncate short strings', () => {
      expect(truncate('Hi', 10)).toBe('Hi');
    });
  });
});

React コンポーネント用テスト構造

React コンポーネントのテストでは、コンポーネントの振る舞いに応じた構造化が重要になります。props、状態、イベントハンドリングなど、異なる側面を明確に分離してテストしましょう。

基本的なコンポーネントテスト

javascriptCopy code// Button コンポーネントのテスト
import {
  render,
  screen,
  fireEvent,
} from '@testing-library/react';
import Button from './Button';

describe('Button component', () => {
  describe('rendering', () => {
    it('should render with provided text', () => {
      render(<Button>Click me</Button>);
      expect(screen.getByRole('button')).toHaveTextContent(
        'Click me'
      );
    });

    it('should apply custom className', () => {
      render(<Button className='custom-btn'>Test</Button>);
      expect(screen.getByRole('button')).toHaveClass(
        'custom-btn'
      );
    });

    it('should be disabled when disabled prop is true', () => {
      render(<Button disabled>Test</Button>);
      expect(screen.getByRole('button')).toBeDisabled();
    });
  });

  describe('interactions', () => {
    it('should call onClick handler when clicked', () => {
      const handleClick = jest.fn();
      render(
        <Button onClick={handleClick}>Click me</Button>
      );

      fireEvent.click(screen.getByRole('button'));
      expect(handleClick).toHaveBeenCalledTimes(1);
    });

    it('should not call onClick when disabled', () => {
      const handleClick = jest.fn();
      render(
        <Button onClick={handleClick} disabled>
          Click me
        </Button>
      );

      fireEvent.click(screen.getByRole('button'));
      expect(handleClick).not.toHaveBeenCalled();
    });
  });
});

状態を持つコンポーネントのテスト

javascriptCopy code// Counter コンポーネントのテスト
import {
  render,
  screen,
  fireEvent,
} from '@testing-library/react';
import Counter from './Counter';

describe('Counter component', () => {
  describe('initial state', () => {
    it('should display initial count value', () => {
      render(<Counter initialValue={5} />);
      expect(
        screen.getByTestId('count-value')
      ).toHaveTextContent('5');
    });

    it('should default to 0 when no initial value provided', () => {
      render(<Counter />);
      expect(
        screen.getByTestId('count-value')
      ).toHaveTextContent('0');
    });
  });

  describe('increment functionality', () => {
    it('should increase count when increment button clicked', () => {
      render(<Counter />);
      const incrementBtn = screen.getByRole('button', {
        name: /increment/i,
      });

      fireEvent.click(incrementBtn);
      expect(
        screen.getByTestId('count-value')
      ).toHaveTextContent('1');

      fireEvent.click(incrementBtn);
      expect(
        screen.getByTestId('count-value')
      ).toHaveTextContent('2');
    });
  });

  describe('decrement functionality', () => {
    it('should decrease count when decrement button clicked', () => {
      render(<Counter initialValue={3} />);
      const decrementBtn = screen.getByRole('button', {
        name: /decrement/i,
      });

      fireEvent.click(decrementBtn);
      expect(
        screen.getByTestId('count-value')
      ).toHaveTextContent('2');
    });
  });
});

非同期処理テストでの適用

非同期処理のテストでは、Promise、async/await、タイマーなどの処理に応じて適切な構造化が必要です。

API 呼び出しのテスト

javascriptCopy code// UserService の非同期テスト
import UserService from './UserService';

// fetch のモック
global.fetch = jest.fn();

describe('UserService', () => {
  beforeEach(() => {
    fetch.mockClear();
  });

  describe('fetchUser method', () => {
    it('should return user data for valid ID', async () => {
      const mockUser = { id: 1, name: '山田太郎' };
      fetch.mockResolvedValue({
        ok: true,
        json: async () => mockUser,
      });

      const result = await UserService.fetchUser(1);

      expect(result).toEqual(mockUser);
      expect(fetch).toHaveBeenCalledWith('/api/users/1');
    });

    it('should throw error for invalid response', async () => {
      fetch.mockResolvedValue({
        ok: false,
        status: 404,
      });

      await expect(
        UserService.fetchUser(999)
      ).rejects.toThrow('User not found');
    });
  });

  describe('createUser method', () => {
    it('should create user and return created data', async () => {
      const newUser = {
        name: '佐藤花子',
        email: 'sato@example.com',
      };
      const createdUser = { id: 2, ...newUser };

      fetch.mockResolvedValue({
        ok: true,
        json: async () => createdUser,
      });

      const result = await UserService.createUser(newUser);

      expect(result).toEqual(createdUser);
      expect(fetch).toHaveBeenCalledWith('/api/users', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(newUser),
      });
    });
  });
});

タイマー処理のテスト

javascriptCopy code// 遅延処理を含む関数のテスト
describe('delayed functions', () => {
  beforeEach(() => {
    jest.useFakeTimers();
  });

  afterEach(() => {
    jest.useRealTimers();
  });

  describe('debounce function', () => {
    it('should execute function after specified delay', () => {
      const mockFn = jest.fn();
      const debouncedFn = debounce(mockFn, 1000);

      debouncedFn();
      expect(mockFn).not.toHaveBeenCalled();

      jest.advanceTimersByTime(1000);
      expect(mockFn).toHaveBeenCalledTimes(1);
    });

    it('should cancel previous call when called multiple times', () => {
      const mockFn = jest.fn();
      const debouncedFn = debounce(mockFn, 1000);

      debouncedFn();
      debouncedFn();
      debouncedFn();

      jest.advanceTimersByTime(1000);
      expect(mockFn).toHaveBeenCalledTimes(1);
    });
  });
});

モック使用時の組み合わせパターン

モックを使用したテストでは、モックの設定とテストケースを明確に分離した構造が重要です。

外部依存関係のモック

javascriptCopy code// 外部ライブラリを使用するサービスのテスト
import EmailService from './EmailService';
import nodemailer from 'nodemailer';

// nodemailer のモック
jest.mock('nodemailer');

describe('EmailService', () => {
  let mockTransporter;

  beforeEach(() => {
    mockTransporter = {
      sendMail: jest.fn(),
    };
    nodemailer.createTransporter.mockReturnValue(
      mockTransporter
    );
  });

  describe('sendWelcomeEmail method', () => {
    it('should send email with correct parameters', async () => {
      mockTransporter.sendMail.mockResolvedValue({
        messageId: '123',
      });

      await EmailService.sendWelcomeEmail(
        'test@example.com',
        'John'
      );

      expect(mockTransporter.sendMail).toHaveBeenCalledWith(
        {
          to: 'test@example.com',
          subject: 'Welcome John!',
          html: expect.stringContaining('John'),
        }
      );
    });

    it('should handle email sending errors', async () => {
      mockTransporter.sendMail.mockRejectedValue(
        new Error('SMTP Error')
      );

      await expect(
        EmailService.sendWelcomeEmail(
          'invalid@email',
          'John'
        )
      ).rejects.toThrow('Failed to send email');
    });
  });
});

エラーハンドリングテストでの活用

エラーハンドリングのテストでは、正常ケースと異常ケースを明確に分離し、エラーの種類に応じた構造化が効果的です。

例外処理のテスト

javascriptCopy code// 複雑なエラーハンドリングを持つクラスのテスト
describe('BankAccount', () => {
  let account;

  beforeEach(() => {
    account = new BankAccount(1000); // 初期残高 1000
  });

  describe('withdraw method', () => {
    describe('when sufficient balance exists', () => {
      it('should withdraw requested amount', () => {
        const result = account.withdraw(500);
        expect(result).toBe(500);
        expect(account.getBalance()).toBe(500);
      });
    });

    describe('when insufficient balance', () => {
      it('should throw InsufficientFundsError', () => {
        expect(() => account.withdraw(1500)).toThrow(
          InsufficientFundsError
        );
      });

      it('should not change balance when error occurs', () => {
        try {
          account.withdraw(1500);
        } catch (error) {
          // エラーを無視
        }
        expect(account.getBalance()).toBe(1000);
      });
    });

    describe('when invalid amount provided', () => {
      it('should throw error for negative amount', () => {
        expect(() => account.withdraw(-100)).toThrow(
          'Amount must be positive'
        );
      });

      it('should throw error for zero amount', () => {
        expect(() => account.withdraw(0)).toThrow(
          'Amount must be greater than zero'
        );
      });
    });
  });
});

#	テストパターン	適用場面	推奨構造
1	単純関数	ユーティリティ関数	機能別 describe
2	React コンポーネント	UI コンポーネント	振る舞い別 describe
3	非同期処理	API 呼び出し	メソッド別 describe
4	モック使用	外部依存あり	依存関係別 describe
5	エラーハンドリング	例外処理	条件別 describe

まとめ

Jest における describe・it・test の使い分けは、単なる API の選択以上の意味を持ちます。適切な使い分けにより、テストコードの可読性、保守性、そしてチーム開発での効率性が大幅に向上するでしょう。

API 選択の重要性

describe は関連するテストをグループ化し、構造化された理解しやすいテストスイートを作るために不可欠です。一方、it と test の選択は、プロジェクトの文脈とチームの価値観に基づいて決定すべきでしょう。

実践的なアプローチ

最も重要なのは、チーム内で一貫したルールを確立し、それを守り続けることです。BDD スタイルを重視するなら it を、より直接的な表現を好むなら test を選択し、プロジェクト全体で統一することが推奨されます。

継続的な改善

テスト構造は、プロジェクトの成長とともに進化させる必要があります。定期的にテストコードをレビューし、より良い構造への改善を続けることで、長期的な開発効率の向上を実現できるでしょう。

この記事で学んだ使い分けの原則と実践パターンを活用して、皆さんのプロジェクトでより良いテストコードを書いてみてください。適切な構造化により、テストコード自体がプロジェクトの貴重なドキュメントとなるはずです。

関連リンク

• Jest 公式ドキュメント - describe API
• Jest 公式ドキュメント - test API
• BDD（振る舞い駆動開発）について
• React Testing Library 公式ガイド
• Jest モック機能ガイド
• JavaScript テストのベストプラクティス
• Testing Trophy について
• Jest 設定ガイド