Claude API アプリケーションのテスト戦略 — AI出力の品質をユニットテスト・統合テスト・E2Eテストで保証する

// src/validators/ai-response.ts
import { z } from "zod";
 
export const SummaryResponseSchema = z.object({
  summary: z
    .string()
    .min(50, "要約が短すぎます（50文字以上）")
    .max(200, "要約が長すぎます（200文字以下）"),
  keyPoints: z
    .array(z.string().min(10))
    .min(2, "要点は最低2つ必要")
    .max(5, "要点は最大5つまで"),
  readingTime: z
    .number()
    .int()
    .min(1, "読了時間は1分以上")
    .max(60, "読了時間が非現実的"),
});
 
export type SummaryResponse = z.infer<typeof SummaryResponseSchema>;

// テストでの使用例
it("要約レスポンスがスキーマに適合する", () => {
  const response = {
    summary: "Claude APIのテスト戦略について解説した記事で、モック戦略とセマンティックアサーションを組み合わせた実践的手法を紹介している",
    keyPoints: [
      "AIの出力は非決定的なのでテスト戦略を変える必要がある",
      "セマンティックアサーションで意味レベルの検証が可能",
    ],
    readingTime: 8,
  };
 
  const result = SummaryResponseSchema.safeParse(response);
  expect(result.success).toBe(true);
 
  if (\!result.success) {
    console.error("バリデーションエラー:", result.error.format());
  }
});

// test/helpers/semantic-assertions.ts
export function assertContainsKeywords(
  text: string,
  required: string[],
  forbidden: string[] = []
): void {
  const missing = required.filter(
    (kw) => \!text.toLowerCase().includes(kw.toLowerCase())
  );
  if (missing.length > 0) {
    throw new Error(
      `必須キーワードが不足: [${missing.join(", ")}]\n出力の先頭200文字: ${text.substring(0, 200)}`
    );
  }
 
  const found = forbidden.filter((kw) =>
    text.toLowerCase().includes(kw.toLowerCase())
  );
  if (found.length > 0) {
    throw new Error(
      `禁止キーワードを検出: [${found.join(", ")}]\n出力の先頭200文字: ${text.substring(0, 200)}`
    );
  }
}
 
// 使用例
assertContainsKeywords(
  aiResponse,
  ["Claude", "API", "テスト"],       // 必ず含まれるべき
  ["ChatGPT", "OpenAI", "GPT-4"]     // 含まれてはいけない
);

// src/evaluation/llm-judge.ts
import Anthropic from "@anthropic-ai/sdk";
 
interface EvaluationResult {
  score: number;      // 1-5
  reasoning: string;
  passed: boolean;
}
 
export async function evaluateWithLLM(
  client: Anthropic,
  input: string,
  output: string,
  criteria: string
): Promise<EvaluationResult> {
  const response = await client.messages.create({
    model: "claude-haiku-4-5",  // 評価にはHaikuで十分（コスト削減）
    max_tokens: 512,
    messages: [
      {
        role: "user",
        content: `あなたはAI出力の品質評価者です。以下の基準に基づいて、入力に対する出力を1〜5のスコアで評価してください。
 
評価基準: ${criteria}
 
入力: ${input}
 
出力: ${output}
 
以下のJSON形式で回答してください:
{"score": 数値(1-5), "reasoning": "評価理由（100文字以内）", "passed": スコアが3以上ならtrue}`,
      },
    ],
  });
 
  const text =
    response.content[0].type === "text" ? response.content[0].text : "";
 
  try {
    const result = JSON.parse(text);
    return {
      score: Number(result.score),
      reasoning: String(result.reasoning),
      passed: result.score >= 3,
    };
  } catch {
    // JSON解析失敗時はテキストからスコアを抽出する
    const scoreMatch = text.match(/"score"\s*:\s*(\d)/);
    return {
      score: scoreMatch ? Number(scoreMatch[1]) : 0,
      reasoning: "JSON解析失敗。生テキスト: " + text.substring(0, 100),
      passed: false,
    };
  }
}

export async function evaluateWithConsensus(
  client: Anthropic,
  input: string,
  output: string,
  criteria: string,
  runs: number = 3
): Promise<EvaluationResult> {
  const results = await Promise.all(
    Array.from({ length: runs }, () =>
      evaluateWithLLM(client, input, output, criteria)
    )
  );
 
  const scores = results.map((r) => r.score).sort((a, b) => a - b);
  const medianScore = scores[Math.floor(scores.length / 2)];
 
  return {
    score: medianScore,
    reasoning: results.find((r) => r.score === medianScore)?.reasoning || "",
    passed: medianScore >= 3,
  };
}

// test/helpers/cached-client.ts
import Anthropic from "@anthropic-ai/sdk";
import { createHash } from "crypto";
import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
 
const CACHE_DIR = "test/.api-cache";
 
export class CachedTestClient {
  private client: Anthropic;
  private ttlMs: number;
 
  constructor(ttlMs: number = 24 * 60 * 60 * 1000) {
    this.client = new Anthropic();
    this.ttlMs = ttlMs;
    if (\!existsSync(CACHE_DIR)) mkdirSync(CACHE_DIR, { recursive: true });
  }
 
  async createMessage(
    params: Anthropic.MessageCreateParams
  ): Promise<Anthropic.Message> {
    const cacheKey = createHash("sha256")
      .update(JSON.stringify(params))
      .digest("hex");
    const cachePath = `${CACHE_DIR}/${cacheKey}.json`;
 
    // キャッシュが存在し、TTL内ならキャッシュを返す
    if (existsSync(cachePath)) {
      const cached = JSON.parse(readFileSync(cachePath, "utf-8"));
      if (Date.now() - cached.timestamp < this.ttlMs) {
        console.log(`  📦 キャッシュヒット: ${cacheKey.substring(0, 8)}...`);
        return cached.response;
      }
    }
 
    // キャッシュミス — 実APIを呼び出して保存
    console.log(`  🌐 API呼び出し: ${cacheKey.substring(0, 8)}...`);
    const response = await this.client.messages.create(params);
    writeFileSync(
      cachePath,
      JSON.stringify({ timestamp: Date.now(), response, params })
    );
    return response;
  }
}

// test/integration/summarizer.integration.test.ts
import { describe, it, expect } from "vitest";
import { CachedTestClient } from "../helpers/cached-client";
import { ArticleSummarizer } from "../../src/services/summarizer";
import { SummaryResponseSchema } from "../../src/validators/ai-response";
import { assertContainsKeywords } from "../helpers/semantic-assertions";
 
// 統合テストは明示的にフラグで制御
const RUN_INTEGRATION =
  process.env.RUN_INTEGRATION_TESTS === "true";
 
describe.skipIf(\!RUN_INTEGRATION)(
  "ArticleSummarizer — 統合テスト",
  () => {
    const cachedClient = new CachedTestClient();
 
    it("実APIで記事を要約し、スキーマに適合する応答を返す", async () => {
      const testArticle = `
        TypeScriptの型システムは、JavaScriptに静的型付けを追加する強力な仕組みです。
        ジェネリクス、条件型、マップ型などの高度な機能により、
        型安全なコードを書きながら柔軟性を維持できます。
        特に大規模プロジェクトでは、型チェックによるバグの早期発見が開発効率を大幅に向上させます。
      `;
 
      // Anthropicクライアントのインターフェースに合わせてラップ
      const wrappedClient = {
        messages: { create: (p: any) => cachedClient.createMessage(p) },
      } as any;
 
      const summarizer = new ArticleSummarizer(wrappedClient);
      const result = await summarizer.summarize(testArticle);
 
      // 構造バリデーション
      const validation = SummaryResponseSchema.safeParse(result);
      expect(validation.success).toBe(true);
 
      // セマンティック検証
      assertContainsKeywords(
        result.summary,
        ["TypeScript"],
        ["Python", "Java"]
      );
 
      // 要点の妥当性
      expect(result.keyPoints.length).toBeGreaterThanOrEqual(2);
      expect(result.readingTime).toBeLessThan(10);
    }, 30_000); // タイムアウトを30秒に設定
  }
);

// e2e/ai-chat.spec.ts
import { test, expect } from "@playwright/test";
 
test.describe("AI チャット機能", () => {
  test("ユーザーが質問を送信し、AI応答が表示される", async ({ page }) => {
    await page.goto("/chat");
 
    // メッセージ入力
    const input = page.getByPlaceholder("メッセージを入力...");
    await input.fill("TypeScriptのジェネリクスとは何ですか？");
    await page.getByRole("button", { name: "送信" }).click();
 
    // ローディング表示の確認
    await expect(page.getByTestId("loading-indicator")).toBeVisible();
 
    // AI応答の表示を待機（最大30秒）
    const response = page.getByTestId("ai-response").last();
    await expect(response).toBeVisible({ timeout: 30_000 });
 
    // 応答内容の基本検証
    const text = await response.textContent();
    expect(text).toBeTruthy();
    expect(text\!.length).toBeGreaterThan(50);
 
    // UIの状態検証
    await expect(page.getByTestId("loading-indicator")).not.toBeVisible();
    await expect(input).toBeEmpty(); // 入力欄がクリアされている
  });
 
  test("APIエラー時にエラーメッセージが表示される", async ({ page }) => {
    // APIをモックしてエラーを返す
    await page.route("**/api/chat", (route) =>
      route.fulfill({
        status: 429,
        body: JSON.stringify({ error: "Rate limit exceeded" }),
      })
    );
 
    await page.goto("/chat");
    await page.getByPlaceholder("メッセージを入力...").fill("テスト");
    await page.getByRole("button", { name: "送信" }).click();
 
    // エラーメッセージの表示確認
    await expect(page.getByTestId("error-message")).toContainText(
      /しばらく時間をおいて|再度お試し/
    );
 
    // リトライボタンの存在確認
    await expect(
      page.getByRole("button", { name: /再試行|リトライ/ })
    ).toBeVisible();
  });
});

# .github/workflows/ai-tests.yml
name: AI Application Tests
 
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  schedule:
    - cron: "0 9 * * 1-5"  # 平日9:00 UTCに統合テスト実行
 
jobs:
  unit-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "22"
          cache: "npm"
      - run: npm ci
      - run: npx vitest run --reporter=verbose
        env:
          # ユニットテストではAPIキー不要（モックのみ）
          NODE_ENV: test
 
  integration-tests:
    # PRへのpushまたはスケジュール実行時のみ
    if: github.event_name == 'schedule' || contains(github.event.head_commit.message, '[integration]')
    runs-on: ubuntu-latest
    needs: unit-tests
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "22"
          cache: "npm"
      - run: npm ci
      - run: npx vitest run --reporter=verbose
        env:
          RUN_INTEGRATION_TESTS: "true"
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY_TEST }}
      - name: コスト集計レポート
        if: always()
        run: |
          # キャッシュ統計を出力
          CACHE_HITS=$(find test/.api-cache -name "*.json" -mmin -5 | wc -l)
          echo "### 統合テスト実行レポート" >> $GITHUB_STEP_SUMMARY
          echo "- キャッシュヒット: ${CACHE_HITS} 件" >> $GITHUB_STEP_SUMMARY

// test/regression/prompt-regression.test.ts
import { describe, it, expect } from "vitest";
import { CachedTestClient } from "../helpers/cached-client";
import { evaluateWithConsensus } from "../../src/evaluation/llm-judge";
import Anthropic from "@anthropic-ai/sdk";
 
const TEST_CASES = [
  {
    name: "技術記事の要約",
    input: "React Server Componentsは、サーバーサイドでレンダリングされるReactコンポーネントです...",
    criteria: "技術的に正確で、初心者にもわかりやすい要約になっているか。重要な概念（サーバーサイドレンダリング、パフォーマンス向上）が含まれているか。",
    minScore: 3,
  },
  {
    name: "エラーメッセージの生成",
    input: "TypeError: Cannot read properties of undefined (reading 'map')",
    criteria: "エラーの原因を正確に特定し、具体的な修正案を提示しているか。初心者にも実行可能な手順になっているか。",
    minScore: 3,
  },
];
 
const RUN_REGRESSION = process.env.RUN_REGRESSION_TESTS === "true";
 
describe.skipIf(\!RUN_REGRESSION)("プロンプトリグレッション", () => {
  const client = new Anthropic();
 
  TEST_CASES.forEach(({ name, input, criteria, minScore }) => {
    it(`${name}: スコア ${minScore} 以上`, async () => {
      // 現在のプロンプトでAPIを呼び出す
      const response = await client.messages.create({
        model: "claude-haiku-4-5",
        max_tokens: 512,
        messages: [{ role: "user", content: input }],
      });
 
      const output =
        response.content[0].type === "text"
          ? response.content[0].text
          : "";
 
      // LLM-as-Judge で評価（3回の多数決）
      const evaluation = await evaluateWithConsensus(
        client,
        input,
        output,
        criteria
      );
 
      console.log(
        `  📊 ${name}: score=${evaluation.score}, reason=${evaluation.reasoning}`
      );
 
      expect(evaluation.score).toBeGreaterThanOrEqual(minScore);
    }, 60_000);
  });
});

// ❌ やってはいけない
expect(summary).toBe("TypeScriptは静的型付け言語です。");
 
// ✅ 正しいアプローチ
expect(summary.length).toBeGreaterThan(20);
expect(summary.length).toBeLessThan(200);
assertContainsKeywords(summary, ["TypeScript", "型"]);
const validation = SummarySchema.safeParse({ summary });
expect(validation.success).toBe(true);

// ストリーミングのモック例
const mockStream = {
  async *[Symbol.asyncIterator]() {
    yield { type: "content_block_start", content_block: { type: "text", text: "" } };
    yield { type: "content_block_delta", delta: { type: "text_delta", text: "部分" } };
    yield { type: "content_block_delta", delta: { type: "text_delta", text: "応答" } };
    yield { type: "message_stop" };
  },
};