bug0inc/qa-agent

Bug0 AI – AI 기반 Playwright 회귀 테스트

개요 – Playwright 브라우저 테스트를 자연어로 작성할 수 있게 해주는 오픈 소스 TypeScript 라이브러리입니다. 이 라이브러리는 각 단계를 LLM(Claude, Gemini, OpenAI의 computer-use agent 등)으로 전송하고, 작업을 받아 브라우저에서 실행하며, 다중 모델 합의 엔진으로 결과를 검증합니다. 또한 성공한 단계를 Redis에 캐싱하여 이후 실행 속도를 높이고 비용을 절감합니다.

주요 기능

기능	작동 방식
자연어 단계	runSteps()는 {description, data?, waitUntil?, ai?} 객체 배열을 받습니다. 설명은 평이한 영어(예: “Click Acme Circles T-Shirt”)입니다. 라이브러리가 프롬프트를 포맷하고 설정된 LLM을 호출하여 모델의 응답을 Playwright 작업으로 변환합니다.
다중 모델 어설션 엔진	각 assertion에 대해 라이브러리는 Claude와 Gemini를 병렬로 호출합니다. 의견이 일치하지 않으면 세 번째 "중재" 모델(설정 가능)이 결정하거나 즉시 실패(fail-on-disagreement) 처리할 수 있습니다.
스마트 캐싱	성공한 단계 실행은 userFlow + step.description을 키로 Redis에 저장됩니다. 캐시 적중 시 LLM 호출 없이 단계가 재생되므로 지연 시간과 비용이 크게 줄어듭니다.
자동 복구	캐시된 단계가 실패하면 라이브러리는 LLM으로 돌아가 작업을 다시 계산한 후 캐시를 업데이트합니다.
비디오 어설션	어설션에 선택적 video: true를 설정하면 전체 단계 실행이 기록되고 .webm이 Gemini의 Files API에 업로드됩니다. Gemini는 비디오를 기반으로 어설션을 평가합니다(토스트 메시지와 같은 일시적인 UI에 유용).
AI 게이트웨이 지원	Vercel AI Gateway, OpenRouter, Cloudflare AI Gateway를 통해 모든 LLM 호출을 라우팅하거나 제공업체(Anthropic, Google, OpenAI)와 직접 통신할 수 있습니다.
CUA 모드	mode: "cua"를 선택하면 OpenAI의 computer-use agent(gpt-5.5 + 내장 computer 도구)를 사용하여 시각적이고 스크린샷 기반의 자동화를 수행합니다.
동적 플레이스홀더	{{run.*}}, {{global.*}}, {{data.*}}, {{email.*}}를 사용하여 임의의 이메일, ID 또는 수신된 이메일에서 추출한 값을 단계에 주입할 수 있습니다.
텔레메트리 및 로그	선택적 OpenTelemetry 추적(Axiom) 및 구조화된 Pino 로그.
이메일 추출	내장 emailsink 제공업체(일회용 받은 편지함) 또는 사용자 지정 제공업체를 사용하여 인증 코드 등을 가져올 수 있습니다.

일반적인 워크플로우

1. Playwright 프로젝트 생성 – npm init playwright@latest bug0-ai-project (TypeScript 선택).
2. 라이브러리 설치 – npm install @bug0/ai dotenv.
3. LLM 자격 증명 추가 – 최소 하나의 Anthropic 키와 하나의 Google Generative AI 키(또는 게이트웨이)가 필요합니다. .env 파일에 추가하세요.
4. 설정 – 테스트 스위트 상단에서 configure({ ai: { gateway: "vercel", models: { … } }, redis: { url }, telemetry: { … } })를 호출합니다.
5. 테스트 작성 – runSteps({ page, userFlow, steps, assertions, test, expect })를 사용합니다. 각 단계는 평이한 영어 설명이며, 어설션도 자연어 문자열입니다.
6. 실행 – npx playwright test example.spec.ts --project chromium. 보고서에는 AI가 생성한 요약이 포함됩니다.

테스트 예시 (TypeScript)

import { test, expect } from "@playwright/test";
import { runSteps, configure } from "@bug0/ai";

configure({
  ai: { gateway: "vercel" },
});

test("Shopping cart", async ({ page }) => {
  await runSteps({
    page,
    userFlow: "Add product to cart",
    steps: [
      { description: "Navigate to https://demo.vercel.store" },
      { description: "Click Acme Circles T-Shirt" },
      { description: "Select color", data: { value: "White" } },
      { description: "Add to cart", waitUntil: "My Cart is visible" },
    ],
    assertions: [{ assertion: "You can see My Cart with Acme Circles T-Shirt" }],
    test,
    expect,
  });
});

설정 포인트

• 모델 슬롯 – 8개의 슬롯(단계 실행, 사용자 흐름 저/고, 기본/보조/중재 어설션, 유틸리티, CUA). 기본값은 저비용 단계용 Gemini-flash와 기본 어설션용 Claude-4.5-haiku입니다.
• Redis – REDIS_URL을 설정하거나 configure({ redis: { url } })를 전달하여 캐싱 및 전역 플레이스홀더를 활성화합니다.
• 게이트웨이 – 선택한 게이트웨이에 따라 AI_GATEWAY_API_KEY, OPENROUTER_API_KEY 등을 설정합니다.
• CUA 모드 – computer 도구에 대한 액세스 권한이 있는 OPENAI_API_KEY가 필요합니다. mode: "cua" 및 gateway: "none"을 설정하세요.
• 텔레메트리 – AXIOM_TOKEN/AXIOM_DATASET을 제공하거나 프로그래밍 방식으로 설정하여 OpenTelemetry 추적을 가져옵니다.

대상 사용자

• AI 에이전트(예: Bug0의 FactoryKit)로 UI 코드를 생성하고, 잦은 DOM 변경을 견딜 수 있는 회귀 테스트 스위트가 필요한 팀.
• 깨지기 쉬운 선택자를 유지 관리하지 않고 빠르게 테스트를 작성하려는 QA 엔지니어.
• LLM 기반 자동화와 캐싱 및 비디오 캡처와 같은 기존 Playwright의 신뢰성 기능을 결합하려는 개발자.

README에 명시된 제한 사항

• 테스트 스위트 자체는 아직 작습니다. 엣지 케이스 커버리지를 환영합니다.
• 비디오 어설션은 게이트웨이를 우회하므로 직접적인 Google API 키가 필요합니다.
• CUA 모드는 게이트웨이와 혼합할 수 없습니다. OpenAI와 직접 통신해야 합니다.
• 다중 단계 캐싱은 아직 구현되지 않았습니다(단일 단계 작업만 캐싱됨).

라이선스 – FSL-1.1-ALv2(관대한 오픈 소스 라이선스).

---

위의 모든 정보는 저장소의 README에서 직접 가져온 것이며, 추가 기능은 추론되지 않았습니다.