getsentry/vitest-evals

What is vitest‑evals?

vitest‑evals は、JavaScript テストランナー Vitest の上に一級の評価層を追加する モノレポ です。AI ベースのアプリケーション（LLM、エージェント、ツールを使用するボットなど）用の 明示的実行 評価スイートを記述でき、構造化された JSON レポートを取得できます。このレポートはローカルで確認可能で、GitHub Actions に再投稿することも可能です。

Why it matters

AI 対応のテストヘルパー – describeEval、run、expect(...).toSatisfyJudge を使用すると、通常の Vitest アサーションを維持しつつ、LLM の出力に対して ジャッジ（例：事実性、ツール呼び出しの正しさ）で検証できます。
プラグイン可能なハーネス – Sentry AI SDK、OpenAI Agents、Pi‑AI、またはカスタムハーネスに対応するアダプタにより、異なるモデルプロバイダー間で同じ評価 API を利用可能にします。
CI 統合 – バンドルされた GitHub Action は JSON レポートを読み取り、ステップの要約を追加し、失敗を注釈し、マージをブロックするチェックランを公開できます（パス率またはスコアのしきい値に基づいて）。
ローカル UI – vitest‑evals serve は React SPA を起動し、実行結果、ツール呼び出し、トークン使用量、コスト、トレーススパンを可視化します。これにより LLM の挙動のデバッグが格段に簡単になります。
再実行可能なツール呼び出し – ツール呼び出しの記録はディスクに保存され、自動的に再実行可能で、テスト実行の決定論的性を保証します。

Core pieces of the repo

Package / App	Role
`packages/vitest-evals`	コア API: `describeEval`、ジャッジ、ハーネス/セッション型、カスタム Vitest レポーター。
`packages/core`	共有プリミティブ、JSON スキーマ定義、および完全なレポートを集約するためのヘルパー。
`packages/report-ui`	React シングルページアプリと CLI（`serve`）で JSON 評価アーティファクトを閲覧可能にします。
`packages/harness‑ai-sdk`	コア API が Sentry AI SDK ハーネスと通信できるようにするアダプタ。
`packages/harness‑openai‑agents`	@openai/agents 形式のエージェント用アダプタ。
`packages/harness‑pi‑ai`	pi‑ai 用アダプタで、組み込みのツール再実行サポートを備えています。
`packages/github-reporter`	Vitest JSON レポートを消費し、要約/注釈/チェックランを出力する GitHub Actions アクション。
`apps/demo‑pi`, `apps/demo‑ai-sdk`, `apps/demo‑openai‑agents`	各ハーネスで構築された返金エージェントの評価方法を示す小さなエンドツーエンドのデモアプリ。

How you would use it

パッケージを追加（モノレポに追加するか、npm から必要なものをインストール）。

Vitest の慣用的な構文で評価スイートを記述:

import { describeEval, FactualityJudge, toolCalls } from 'vitest-evals';
import { piAiHarness, piAiJudgeHarness } from '@vitest-evals/harness-pi-ai';

const judge = FactualityJudge({ judgeHarness: piAiJudgeHarness({ model: 'claude-sonnet', temperature: 0 }) });

describeEval('refund agent', { harness: piAiHarness({ agent: createRefundAgent }) }, (it) => {
  it.for([{ name: 'approves invoice', input: 'Refund invoice 123', expectedTools: ['lookupInvoice','createRefund'] }])
    ('$name', async ({ input, expectedTools }, { run }) => {
      const result = await run(input);
      expect(toolCalls(result).map(c => c.name)).toEqual(expectedTools);
      await expect(result).toSatisfyJudge(judge);
    });
});

提供された CLI でスイートを実行:

pnpm evals          # "evals" スクリプトを公開するすべてのパッケージ/アプリを実行
pnpm evals --info   # より豊富なツールメタデータ

ローカルで結果を確認:
```
pnpm exec vitest-evals serve vitest-results.json
```
これにより、各テスト、LLM 出力、ツール呼び出し、トークン使用量、コストを表示する UI が開きます。

CI レポートを追加（README からの GitHub Actions の例）:

- run: pnpm exec vitest run ... --reporter=vitest-evals/reporter --outputFile.json=vitest-results.json
- uses: getsentry/vitest-evals@v0
  with:
    results: vitest-results.json
    publish-check: true
    min-pass-rate: 0.8

このアクションは要約を投稿し、失敗を注釈し、パス率がしきい値を下回った場合にマージをブロックできます。

Key concepts explained

ハーネス – AI ベースのアプリ（またはエージェント）を起動し、テスト入力で呼び出す方法を知る薄いラッパー。異なる SDK/プロバイダー用に異なるハーネスが存在します。
ジャッジ – モデルの応答をスコアリングするロジック（多くの場合 LLM でバックアップ）。組み込みジャッジには FactualityJudge、StructuredOutputJudge、ToolCallJudge があります。assess(ctx) 関数を実装することでカスタムジャッジを作成できます。
明示的実行 – Vitest がテスト関数を直接呼び出すのではなく、スイートがハーネスの run(input) を呼び出すことで、リクエスト/レスポンスのライフサイクルを完全に制御でき、スパン、トークン数、ツール使用量のキャプチャが可能になります。
再実行モード – ツール呼び出しの記録は .vitest-evals/recordings に保存されます。VITEST_EVALS_REPLAY_MODE=auto にすると、既存の記録が再実行され、record にするとライブ呼び出しが強制されます。これにより評価が決定論的でありながら、フィクスチャの容易な更新も可能になります。
JSON レポート – カスタムレポーターは、各テストのメタデータ、スコア、トークン使用量、USD でのコスト、および生のスパンを含む構造化されたファイルを出力します。このファイルは UI、GitHub Action、および下流の分析に使用されます。

Who should consider using it?

LLM ベースのサービス、エージェント、ツールを使用するボット を構築しているチームで、自動化された品質チェックが必要な場合。
Vitest をユニット/統合テストに使用しているプロジェクトで、AI 固有のアサーションを低摩擦で追加したい場合。
CI ゲート付き評価（例：マージ前に最低限の事実性スコアを要求）を希望する組織。
LLM 出力、トークン使用量、ツールインタラクションの 視覚的デバッグ UI を必要とする人。

Where to learn more

ドキュメントサイト – https://vitest-evals.sentry.dev/docs（セットアップガイド、アーキテクチャ、CI 詳細）。
パッケージの README – 特に packages/vitest-evals/README.md でコア API を確認。
デモアプリ – apps/demo‑pi、apps/demo‑ai-sdk、apps/demo‑openai‑agents は実世界での使用例を示しています。

TL;DR

vitest‑evals は、AI エージェント用の構造化された評価フレームワークを Vitest に拡張し、ハーネスアダプタ、再利用可能なジャッジ、JSON レポート、ローカル UI、および GitHub Actions との完全統合を提供します。通常のテストアサーションを維持しつつ、再現可能で観測可能かつ CI ゲート可能な AI 固有の品質チェックを追加できます。