Expect 딥다이브
— AI 에이전트가 실제 브라우저에서 코드를 적대적으로 테스트하는 도구

1프로젝트 한줄 요약

Expect는 AI 에이전트(Claude, Codex 등)가 코드 변경사항을 분석하여 "적대적(adversarial)" 테스트 계획을 자동 생성하고, 실제 브라우저(Playwright)에서 해당 테스트를 실행하여 통과/실패를 리포트하는 자동화 테스트 도구입니다.

2왜 주목받는가

경쟁 도구 대비 위치

핵심 혁신 4가지: 적대적 테스트 철학, 쿠키/인증 자동 주입, Playwright 스냅샷 비교, Claude Code 스킬 통합.

3기술 스택 전체 지도

언어 & 런타임

핵심 프레임워크

AI/에이전트 연동

빌드 & 패키지 관리

4아키텍처 심화 분석

시스템 구조도

패턴 1 — Effect 기반 함수형 아키텍처

Expect의 가장 독특한 기술적 선택은 Effect 라이브러리를 핵심 프레임워크로 사용한다는 점입니다. Effect는 TypeScript의 "ZIO" 같은 것으로, 에러 타입이 타입 시스템에 명시됩니다.

// Effect 패턴 — 에러 타입이 타입 시그니처에 명시됨
type BrowserResult = Effect.Effect<SnapshotResult, BrowserLaunchError | ActionTimeoutError>

// 의존성 주입이 타입 레벨에서 관리됨 — 테스트 시 쉽게 모킹 가능

패턴 2 — Agent Client Protocol (ACP)

detectAvailableAgents() 함수가 사용 가능한 에이전트를 자동 감지하고, AgentBackend 타입으로 추상화합니다.

패턴 3 — MCP (Model Context Protocol) 통합

Browser 패키지가 MCP 서버를 내장하여, Claude Code가 Expect를 도구(tool)로 직접 호출할 수 있습니다:

// MCP 서버 생성 — Claude Code가 이 도구를 호출 가능
const runtime = ManagedRuntime.make(
  Layer.mergeAll(McpSession.layer, OverlayController.layer)
);
const server = createBrowserMcpServer(runtime);
// 호출 흐름: Claude Code → MCP 프로토콜 → Playwright 실행

패턴 4 — Supervisor 오케스트레이션 패턴

Supervisor 패키지가 전체 워크플로우를 조율합니다: Git 모듈 → Agent 테스트 계획 → Browser 실행 → Reporter 결과 수집.

5디렉토리 구조 해부

6학습 포인트 (기술별)

Effect (함수형 TypeScript)

배울 것: TypeScript에서 "에러를 타입으로 추적"하는 혁신적 방식. try-catch의 한계를 넘어서는 함수형 에러 핸들링.

// 전통적 방식: 어떤 에러가 발생하는지 타입에서 안 보임
async function runTest(): Promise<Result> {
  try { /* ... */ } catch (e) { /* e는 unknown */ }
}

// Effect 방식: 에러 타입이 시그니처에 명시
function runTest(): Effect.Effect<Result, BrowserLaunchError | ActionTimeoutError> {
  // 컴파일러가 모든 에러 케이스 처리를 강제
}

Playwright 브라우저 자동화

배울 것: CDP(Chrome DevTools Protocol) 자동 발견, 스크린샷 비교(diffSnapshots), 스냅샷 기반 테스트.

// CDP 자동 발견 — 이미 실행 중인 Chrome에 연결
autoDiscoverCdp()  // 개발 중인 앱의 브라우저에 바로 연결

MCP 서버 구현

배울 것: Claude Code의 도구를 확장하는 MCP 서버를 TypeScript로 구현하는 방법. Expect의 packages/browser/src/mcp/ 코드를 분석하면 완전한 MCP 서버 구현 패턴을 익힐 수 있습니다.

rrweb 세션 녹화

배울 것: DOM 변경사항을 이벤트로 캡처하여 "영상처럼" 리플레이하는 기술. 비디오가 아닌 DOM 이벤트 기반이라 파일 크기가 작습니다.

// 세션 이벤트 수집 → HTML 리플레이어 생성
const events = collectAllEvents(session);
const html = buildReplayViewerHtml(events);
// 브라우저에서 열면 테스트 과정을 그대로 재생

Turborepo 모노레포 관리

배울 것: 7개 패키지를 효율적으로 관리하는 모노레포 구성, 의존성 그래프 기반 빌드.

// turbo.json — 빌드 태스크 간 의존 관계 정의
{
  "tasks": {
    "build": { "dependsOn": ["^build"] },  // 의존 패키지 먼저 빌드
    "test": { "dependsOn": ["^test"] }
  }
}

7하드웨어 / 시스템 요구사항

8직접 해볼 수 있는 실습 과제

import { Effect } from "effect";
import { chromium } from "playwright";
// 1. Git diff 파싱 → 변경 파일 목록
// 2. AI에게 테스트 계획 요청
// 3. Playwright로 브라우저에서 테스트 실행
// 4. 결과 리포트 출력

9관련 기술 심화 학습 로드맵

1주차 — 기초 다지기

Playwright 공식 튜토리얼 완주(2~3일), TypeScript 고급 타입(제네릭, 조건부 타입, 매핑된 타입) 복습, Git diff 파싱 기초(simple-git 라이브러리).

2주차 — Effect 입문

Effect 공식 문서 "Getting Started" 완독. Effect<Success, Error, Requirements> 3가지 타입 파라미터 이해. pipe, map, flatMap, catchAll 패턴 실습. Expect의 에러 타입 계층 분석.

3주차 — MCP 프로토콜 심화

MCP 공식 스펙 문서 읽기, 간단한 MCP 서버 직접 구현(Node.js + TypeScript), Claude Code에서 커스텀 MCP 도구 연동 테스트. Expect의 packages/browser/src/mcp/ 코드 분석.

4주차 — 모노레포 & 빌드 시스템

pnpm workspace 설정 방법 학습, Turborepo로 빌드 파이프라인 구성, Expect의 7-패키지 모노레포 구조를 참고한 미니 프로젝트 구성.

5주차 — AI 에이전트 통합

Vercel AI SDK(@ai-sdk/provider) 학습, ACP(Agent Client Protocol) 스펙 이해, 멀티 프로바이더 에이전트 시스템 직접 구현.

6주차 — 통합 프로젝트

자신만의 "AI 기반 자동화 테스트 도구" 미니 버전 구현, Supervisor 패턴으로 워크플로우 오케스트레이션, rrweb 세션 녹화 + 리플레이 기능 추가, CI/CD 파이프라인 통합.

10핵심 키워드 사전

11참고 링크

• GitHub 레포 — millionco/expect
• 공식 데모 — expect.dev
• Effect 공식 문서
• Playwright 공식 문서
• rrweb 프로젝트
• MCP 스펙
• Turborepo 문서
• Vercel AI SDK
• Zod v4 문서