概要

API設計において、レスポンスの構造やエラーの表現は後回しにされやすい設計領域だ。
しかし、TDDを実践することで、戻り値・エラー・境界条件を「仕様」として最初に定義できるようになる。

本稿では、Node.js + Jest を使った TDD の流れを通して、
「振る舞いの設計」と「エラーの設計」をテスト駆動でどう構築するかを具体的に解説する。

1. API設計における「戻り値と例外」の責任

APIは「成功」と「失敗」の2軸しかない
それらを構造的にどう返すかが設計品質に直結する

TDDでは、「何を返すべきか」をテストという仕様定義の中で明文化できる。

2. 実装例：ユーザー登録API（成功 / バリデーションエラー / DB失敗）

🔴 Red：仕様を書く（Jest）

// userService.test.js

const { registerUser } = require('./userService');

describe('registerUser', () => {
  it('should return userId on successful registration', async () => {
    const user = { name: 'Alice', email: 'alice@example.com' };
    const result = await registerUser(user);
    expect(result).toEqual({ ok: true, userId: expect.any(String) });
  });

  it('should return validation error if email is missing', async () => {
    const user = { name: 'Bob' };
    const result = await registerUser(user);
    expect(result).toEqual({
      ok: false,
      error: {
        code: 'VALIDATION_ERROR',
        message: 'Email is required.',
        field: 'email',
      },
    });
  });

  it('should return system error if DB fails', async () => {
    const user = { name: 'Charlie', email: 'fail@db.com' };
    const result = await registerUser(user);
    expect(result.ok).toBe(false);
    expect(result.error.code).toBe('DB_ERROR');
  });
});

3. 🟢 Green：仕様を通す実装を最小構成で書く

// userService.js
const crypto = require('crypto');

async function registerUser(user) {
  if (!user.email) {
    return {
      ok: false,
      error: {
        code: 'VALIDATION_ERROR',
        message: 'Email is required.',
        field: 'email',
      },
    };
  }

  if (user.email === 'fail@db.com') {
    return {
      ok: false,
      error: {
        code: 'DB_ERROR',
        message: 'Failed to connect to database',
      },
    };
  }

  return {
    ok: true,
    userId: crypto.randomUUID(),
  };
}

module.exports = { registerUser };

4. 構造の意義：振る舞いを「定義」するという設計

成功：{ ok: true, data }
失敗：{ ok: false, error: { code, message, field? } }

このような構造をテストから先に書くことで、

振る舞いが明文化され、
実装はその仕様に忠実に従うよう設計される。

5. TDDによるAPI設計の価値

項目	TDDでの設計効果
戻り値構造	明示的かつ一貫性のある返却型が定義される
エラー制御	曖昧な例外処理ではなく、構造化された失敗
拡張性	`error.code` ベースでロジックを追加できる
UI実装側	型が保証され、安心してマッピング可能

設計判断フロー

① 成功の戻り値は何か？ → テストで先に書いて定義する

② 失敗時に何を返したいか？ → 構造・コード・メッセージを明示する

③ 想定する失敗の種類は？ → バリデーション / システム / 認証 など

④ その情報でフロントは制御できるか？ → UI要件も含めて考える

よくあるミスと対策

❌ 成功時だけを前提とした実装で例外を投げるだけ

→ ✅ 失敗も1つの仕様として明示的に定義する

❌ テストがレスポンス構造をチェックしていない

→ ✅ 「何を返すか」が設計の本質。型・構造を仕様として記述

❌ テストでtry/catchを使っている（=テストが仕様を覆っている）

→ ✅ catchではなく、構造的な result.ok === false に寄せる

結語

TDDは、単に「コードを確認するもの」ではない。
それは**“振る舞いを先に定義し、実装をそれに従わせるための設計手法”**である。

テストは「何を返すべきか」を先に定義する仕様書
失敗もレスポンスとして設計することで、APIが堅牢になる
フロントエンドやクライアント実装との整合性が高まる

TDDとは、
“振る舞いの期待値をテストに刻み込み、構造的なAPI設計を導く戦略である。”