getsentry/vitest-evals

What is vitest‑evals?

vitest‑evals 는 JavaScript 테스트 러너 Vitest 위에 일급 평가 계층을 추가하는 모노레포입니다. 개발자는 AI 기반 애플리케이션(LM, 에이전트, 도구 사용 봇 등)용 명시적 실행 평가 세트를 작성하고, 로컬에서 검토하거나 GitHub Actions로 다시 게시할 수 있는 구조화된 JSON 보고서를 얻을 수 있습니다.

Why it matters

AI 인식 테스트 헬퍼 – describeEval, run, expect(...).toSatisfyJudge 를 사용하면 일반적인 Vitest 어설션을 유지하면서도 LLM 출력을 재판 (예: 사실성, 도구 호출 정확성)으로 검증할 수 있습니다.
플러그인 가능한 핸서스 – Sentry AI SDK, OpenAI Agents, Pi‑AI 또는 사용자 정의 핸서스용 어댑터를 통해 다양한 모델 제공업체 간에 동일한 평가 API 를 사용할 수 있습니다.
CI 통합 – 포함된 GitHub Action 은 JSON 보고서를 읽고, 단계 요약을 추가하고, 실패를 주석 처리하며, 통과율 또는 점수 기준에 따라 PR 병합을 차단하는 체크 런을 게시할 수 있습니다.
로컬 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 전용 품질 검사를 추가할 수 있습니다.