testing-llm

LLM と AI のテストパターン

LLM 統合のテスト、AI 出力品質の評価、決定論的な CI のための応答のモック、エージェント型テストワークフロー（プランナー、ジェネレーター、ヒーラー）の適用に関するパターンとツールです。この 3 つのうち、ここにローカルのリファレンスがあるのはヒーラーだけです。プランナーとジェネレーターのステージは testing-e2e スキルに属します。

クイックリファレンス

分野	ファイル	目的
ルール	rules/llm-evaluation.md	DeepEval の品質メトリクス、Pydantic スキーマ検証、タイムアウトテスト
ルール	rules/llm-mocking.md	LLM 応答のモック、VCR.py の記録、カスタムリクエストマッチャー
リファレンス	references/ork-delta.md	ベンダーのドキュメントに含まれない独自ルール：GEval と RAGAS の API 修正、しきい値の方向、カセットのパス、ゴールデンデータセットとレイテンシの予算
リファレンス	references/healer-agent.md	失敗するテストを自動修正します（セレクター、待機、動的コンテンツ）
リファレンス	references/langfuse-v4.md	Langfuse Python SDK v4 によるトレースとデータセットの実行、およびゼロ以外のスループットのアサーション
チェックリスト	checklists/llm-test-checklist.md	LLM テストの完全なチェックリスト（セットアップ、カバレッジ、CI/CD）

上流ドキュメントの対象範囲（再記載しないでください）

DeepEval、RAGAS、VCR.py、Playwright には、それぞれ独自のドキュメントがあります。このスキルに含まれるのは OrchestKit 固有の差分（references/ork-delta.md）と、rules/ および checklists/ にある独自の抜粋だけです。ここに記載された情報を期待するのではなく、以下のソースを参照してください。

トピック	ソース
DeepEval の全メトリクス一覧とメトリクスごとのコンストラクター引数（独自のしきい値テーブルと 2 メトリクスのクイックスタートは、このファイル、rules/llm-evaluation.md、checklists/llm-test-checklist.md に記載）	https://deepeval.com/docs/metrics-introduction
GEval のカスタム基準：evaluation_params、evaluation_steps、criteria（独自のインポート修正は references/ork-delta.md に記載）	https://deepeval.com/docs/metrics-llm-evals
HallucinationMetric の引数（独自の 0.3 上限と、方向が逆になることへの警告は references/ork-delta.md に記載）	https://deepeval.com/docs/metrics-hallucination
RAGAS のメトリクス一覧（Faithfulness、LLMContextRecall、FactualCorrectness）	https://docs.ragas.io/en/stable/concepts/metrics/available_metrics/
EvaluationDataset の構築（0.2 以降のフィールド名に関する独自の注記は references/ork-delta.md に記載）	https://docs.ragas.io/en/stable/concepts/components/eval_dataset/
VCR.py の設定キー（記録モードのゲートとヘッダーフィルターに関する独自の注記は rules/llm-mocking.md に記載）	https://vcrpy.readthedocs.io/en/latest/configuration.html
Playwright の Planner と Generator エージェント、init-agents CLI、および生成されるファイル（独自のヒーラー関連の抜粋は references/healer-agent.md に記載）	https://playwright.dev/docs/test-agents
生成されたテストで使用される Playwright のセマンティックロケーターの優先順位	testing-e2e スキル（rules/e2e-playwright.md）および https://playwright.dev/docs/locators
メトリクスのスコアサンプルに対する信頼区間	https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.t.html

このスキルを使用する場面

• LLM API（OpenAI、Anthropic など）を呼び出すコードのテスト
• RAG パイプラインの出力品質の検証
• CI で決定論的な LLM テストをセットアップ
• 品質ゲートを備えた評価パイプラインの構築
• エージェント型テストパターン（計画 -> 生成 -> 修復）の適用

LLM モックのクイックスタート

高速で決定論的なユニットテストのために、LLM 応答をモックします。

from unittest.mock import AsyncMock, patch
import pytest

@pytest.fixture
def mock_llm():
    mock = AsyncMock()
    mock.return_value = {"content": "Mocked response", "confidence": 0.85}
    return mock

@pytest.mark.asyncio
async def test_with_mocked_llm(mock_llm):
    with patch("app.core.model_factory.get_model", return_value=mock_llm):
        result = await synthesize_findings(sample_findings)
    assert result["summary"] is not None

重要なルール： CI でライブ LLM API を呼び出してはいけません。ユニットテストにはモックを、統合テストには VCR.py を使用してください。

DeepEval 品質評価のクイックスタート

多次元メトリクスを使用して LLM の出力品質を検証します。

from deepeval import assert_test
from deepeval.test_case import LLMTestCase
from deepeval.metrics import AnswerRelevancyMetric, FaithfulnessMetric

test_case = LLMTestCase(
    input="What is the capital of France?",
    actual_output="The capital of France is Paris.",
    retrieval_context=["Paris is the capital of France."],
)

assert_test(test_case, [
    AnswerRelevancyMetric(threshold=0.7),
    FaithfulnessMetric(threshold=0.8),
])

ライブラリに関する注記（DeepEval、RAGAS）

DeepEval のメトリクスでは、include_reason=True の場合、数値スコアとともに reason フィールドが公開されるため、CI ビルドが失敗したときに、LLM をもう一度呼び出さなくても人が読める説明を得られます。

metric = AnswerRelevancyMetric(threshold=0.7, include_reason=True)
metric.measure(test_case)
print(metric.score, metric.reason)
# 0.62  "Response addresses the topic but omits the date asked for."

RAGAS はクラスベースのメトリクス API を使用します。メトリクスクラスをインスタンス化し、EvaluationDataset を渡します。llm= は省略可能です。省略すると、設定済みのデフォルトの評価器が使用されます。

from ragas import evaluate
from ragas.metrics import Faithfulness, LLMContextRecall

result = evaluate(
    dataset,
    metrics=[Faithfulness(), LLMContextRecall()],
)

バージョンの下限を引き上げます：deepeval >= 4.0、ragas >= 0.4。

ベンダーのドキュメントには記載されていないチーム内ルール（反転した HallucinationMetric のしきい値、デフォルトの評価器 gpt-5-mini、95％信頼区間の算出手順、レイテンシ、品質ゲート、切り捨ての数値）は、references/ork-delta.md に記録されています。どちらかのライブラリのセットアップコードを書く前に、そちらを読んでください。

品質メトリクスのしきい値

メトリクス	しきい値	目的
回答の関連性	>= 0.7	応答が質問に答えている
忠実性	>= 0.8	出力がコンテキストと一致している
ハルシネーション	<= 0.3	捏造された事実がない
コンテキストの適合率	>= 0.7	検索されたコンテキストが関連している
コンテキストの再現率	>= 0.7	関連するコンテキストがすべて検索されている

構造化出力の検証

LLM の出力は必ず Pydantic スキーマで検証してください。

from pydantic import BaseModel, Field

class LLMResponse(BaseModel):
    answer: str = Field(min_length=1)
    confidence: float = Field(ge=0.0, le=1.0)
    sources: list[str] = Field(default_factory=list)

async def test_structured_output():
    result = await get_llm_response("test query")
    parsed = LLMResponse.model_validate(result)
    assert 0 <= parsed.confidence <= 1.0

統合テストでの VCR.py

決定論的な統合テストのために、LLM API 呼び出しを記録して再生します。

@pytest.fixture(scope="module")
def vcr_config():
    import os
    return {
        "record_mode": "none" if os.environ.get("CI") else "new_episodes",
        "filter_headers": ["authorization", "x-api-key"],
    }

@pytest.mark.vcr()
async def test_llm_integration():
    response = await llm_client.complete("Say hello")
    assert "hello" in response.content.lower()

エージェント型テストのワークフロー

エンドツーエンドのテスト自動化で使用する、3 エージェントのパターンです。

Planner -> specs/*.md -> Generator -> tests/*.spec.ts -> Healer (auto-fix)

1. プランナー：アプリを調査し、Markdown のテスト計画を作成します。testing-e2e スキル（rules/e2e-ai-agents.md）が管理します。CLI と生成されるファイルについては、https://playwright.dev/docs/test-agents に記載されています。

2. ジェネレーター：Markdown 仕様を Playwright テストに変換し、実行中のアプリに対してセレクターを検証します。こちらも testing-e2e（rules/e2e-ai-agents.md）が管理します。これが従うロケーターの優先順位は、testing-e2e の rules/e2e-playwright.md に記載されています。

3. ヒーラー（references/healer-agent.md）：失敗を再生して DOM を調査し、ロケーターや待機処理に修正を加えることで、失敗したテストを自動的に修復します。テストごとの修復試行は最大 3 回です。

エージェントの初期化は CLI のみで行います（npx playwright init-agents）。設定キーはありません。ローカル参照を維持するのは修復ステージだけです。試行回数の上限である 3 回と、テストロジックに手を加えないという制限は、ベンダーのデフォルトではなくチーム内の制限であるためです。

必ずテストするエッジケース

LLM との統合では、次のケースをすべて網羅してください。

• 空または null の入力 -- 空文字列、None 値
• 長い入力 -- トークン上限付近での切り捨て動作
• タイムアウト -- フェイルオープンとフェイルクローズの動作
• スキーマ違反 -- 無効な構造化出力
• プロンプトインジェクション -- 敵対的な入力への耐性
• Unicode -- プロンプトと応答内の ASCII 以外の文字

完全なチェックリストについては、checklists/llm-test-checklist.md を参照してください。

アンチパターン

アンチパターン	正しい方法
CI での実際の LLM 呼び出し	単体テストではモック、統合テストでは VCR を使用
ランダムシード	固定シードまたはモックした応答を使用
単一メトリクスによる評価	3～5 個の品質指標を使用
タイムアウト処理がない	テストでは常に 1 秒未満のタイムアウトを設定
API キーのハードコード	環境変数を使用し、VCR ではフィルタリング
is not None のみをアサート	スキーマ検証と品質メトリクスを使用

関連スキル

• ork:testing-unit — 単体テストの基礎、AAA パターン
• ork:testing-integration — AI パイプラインの統合テスト
• ork:golden-dataset — 評価データセットの管理
• ork:testing-e2e は、プランナーとジェネレーターのエージェントワークフロー、および Playwright のロケーターの優先順位を管理します
• ork:testing-perf は、references/ork-delta.md で参照されているレイテンシと負荷の予算を管理します