e2e

$ npx e2e init copy

TesterArmy가 만든 오픈소스 프로젝트(tester-army/e2e, Apache-2.0).

왜 필요한가?

E2E(end-to-end) 테스트는 실제 사용자처럼 앱을 처음부터 끝까지 조작해 보는 테스트입니다. 공식 문서는 e2e를 쓰는 이유로 두 가지를 듭니다. 첫째는 테스트에 드는 시간입니다. selector(화면 요소를 찾는 식)와 대기 시간을 나열한 스크립트 대신 목표를 적으며, UI가 바뀌면 에이전트가 맞춰 움직이므로 고쳐야 할 테스트가 줄어든다고 설명합니다. 둘째는 실행 비용입니다. 뒤따르는 검증이 통과한 agent.act 단계는 기록해 두고, 다음 실행에서는 모델 호출 없이 재생합니다.

agent.act('upgrade the workspace to the Pro plan')처럼 목표를 자연어로 쓰면 에이전트가 앱을 조작해 그 목표에 도달합니다. 결과가 맞는지는 같은 테스트 안에서 locator와 assertion으로 확인합니다.

// tests/checkout.e2e.ts
import { test, expect } from 'e2e';

test('a member upgrades to Pro', async ({ app, agent, screen }) => {
  await app.open('/settings/billing');

  await agent.act('upgrade the workspace to the Pro plan');
  await agent.assert('the invoice preview shows a prorated amount');

  await expect(screen.getByRole('status')).toContainText('Pro');
});

무엇을 할 수 있나

코딩 에이전트에게 테스트 작성 맡기기 — 공식 문서는 Claude Code, Codex, Cursor 같은 코딩 에이전트가 e2e 테스트를 쓰고, 실행하고, 디버깅할 수 있다고 설명합니다. 스킬을 설치한 뒤에는 “add a test for checkout” 같은 요청만으로 테스트를 추가합니다.
테스트 파일 없이 앱 탐색하기 — e2e explore에 목표를 주면 에이전트가 단계를 계획해 앱을 조작하고 발견한 문제를 보고합니다. 문서의 예시는 다음과 같습니다.
```
npx e2e explore 'Explore the checkout flow like a first-time buyer and report anything off'
```
문서의 출력 예시에는 장바구니 수량을 늘려도 합계가 바뀌지 않는 문제, 재고가 음수로 표시되는 문제 같은 항목이 심각도와 함께 나옵니다.
버그 배시(bug bash) 돌리기 — 여러 e2e explore 세션을 동시에 실행해 앱의 영역별로 문제를 찾고, 코딩 에이전트가 발견 항목마다 재현 테스트를 작성합니다. 테스트가 실제로 실패한 항목만 버그로 보고합니다. 코딩 에이전트에게 주는 문서의 예시 프롬프트입니다.
```
Bug bash the checkout and account settings on this branch.
```
내 기술 스택의 완성된 예제 보기 — 저장소의 examples/에 Vite, Next.js, Astro, Expo, SwiftUI, Jetpack Compose, Kotlin Multiplatform, Flutter 예제가 있습니다. 각각 독립된 프로젝트이며 통과하는 테스트 묶음이 들어 있습니다.

핵심 기능

에이전트 단계와 정확한 검증을 한 테스트에

agent.act는 목표 하나를 수행하고, agent.assert는 화면을 보고 판단합니다. screen, expect 같은 일반 locator와 assertion은 정확한 값을 확인합니다. 문서는 agent.act 하나에 목표 하나를 주고 바로 뒤에 expect로 확인하도록 안내합니다. 에이전트가 잘못 수행하면 그 expect가 실패합니다.
검증된 조작은 기록했다가 모델 호출 없이 재생

agent.act 단계 뒤의 검증이 통과하면 그 단계의 조작이 기록됩니다. 다음 실행에서는 모델을 호출하지 않고 기록된 조작을 재생하며, 화면 요소나 기대한 결과가 달라지면 에이전트가 현재 화면에서 이어받습니다. agent.assert, agent.waitFor, agent.extract는 항상 실시간으로 실행됩니다.
웹과 모바일을 같은 API로

@e2e-dev/web은 Playwright를 통해 Chromium, Firefox, WebKit을 다룹니다. @e2e-dev/mobile은 iOS 시뮬레이터, Android 에뮬레이터, 연결된 휴대폰에서 테스트를 실행하며, 브라우저 테스트와 같은 agent, screen, expect API를 씁니다.
코딩 에이전트용 스킬과 MCP 서버

스킬은 코딩 에이전트에게 e2e 사용법을 알려 줍니다. e2e mcp 서버는 코딩 에이전트가 앱을 열어 직접 살펴보고, locator를 시험해 보고, 스크린샷을 찍을 수 있게 합니다. 하위 에이전트를 포함해 에이전트마다 별도 세션을 열 수 있고, 동시에 열 수 있는 세션은 기본 4개입니다. 이 서버는 테스트를 실행하지는 않으며, 모델 없이 동작합니다.
실패 원인을 담은 trace 페이지

테스트가 실패하거나 시간 초과되면 .e2e/results/<test>/trace.md가 만들어집니다. 실패한 줄, 각 단계가 한 일, 콘솔 오류, 실패한 요청, 실패 시점의 화면이 담겨 있어 코딩 에이전트가 이 페이지를 읽고 원인을 찾습니다.
모델은 직접 선택

에이전트 단계는 e2e.config.ts에 설정한 모델을 씁니다. Vercel AI Gateway나 OpenRouter 같은 게이트웨이, 제공자 API 키, 로컬 또는 자체 호스팅 서버, 기존 구독 중에서 고릅니다.

사용 방법

Node.js 24.8 이상(Node.js 22는 22.22.3 이상)이 필요합니다. Windows에서는 WSL 안에서 실행합니다. 모바일 테스트에는 iOS 시뮬레이터 런타임이 포함된 Xcode 또는 에뮬레이터가 포함된 Android SDK가 추가로 필요합니다.

앱 디렉터리에서 다음을 실행합니다.

npx e2e init

Web (Playwright) 또는 **Mobile (iOS/Android)**을 고르고, 이어서 구독, 모델 제공자, 또는 AI 없는 테스트용 None 중 하나를 고릅니다. 설정 파일과 예제 테스트가 만들어지고, 코딩 에이전트 설정 여부를 묻습니다. 기존 파일은 그대로 둡니다. Claude Code용으로는 스킬이 .claude/skills/e2e/에 설치되고 MCP 서버가 .mcp.json에 등록됩니다.

예제를 실행합니다.

npx e2e run

예제 테스트는 모델을 호출하지 않으므로 로그인이나 API 키 없이 실행됩니다. 에이전트 단계를 추가한 뒤에는 파일 하나만 지정해 실행할 수 있습니다.

npx e2e run tests/agent.e2e.ts

웹 테스트를 눈으로 보려면 --headed를, 기록된 조작을 건너뛰고 에이전트를 실시간으로 실행하려면 --no-cache를 붙입니다.

코딩 에이전트에게 설정 전체를 맡길 수도 있습니다. 공식 quickstart에 Claude Code, Codex, Cursor에 붙여 넣는 설정용 프롬프트가 있습니다.

MCP 서버만 Claude Code에 직접 등록하려면 다음을 실행합니다.

claude mcp add e2e -- npx e2e mcp

알아두면 좋은 점

텔레메트리가 기본으로 켜져 있습니다 — CLI는 어떤 명령과 엔진이 실행되는지, 어디서 실패하는지 같은 익명 사용 데이터를 보냅니다. 테스트 내용, 앱 내용, 자격 증명은 보내지 않는다고 밝힙니다. npx e2e telemetry disable, 환경 변수 E2E_TELEMETRY_DISABLED=1 또는 DO_NOT_TRACK=1로 끕니다. E2E_TELEMETRY_DEBUG=1을 붙여 실행하면 보낼 내용을 전송 없이 출력해 줍니다. 전송 항목 전체는 Telemetry 문서에 있습니다.
1.0 이전 단계입니다 — README는 “e2e is in active development on the way to 1.0. APIs and config can still change between minor releases.”라고 안내합니다.
기본 모델이 없습니다 — 에이전트 단계에 쓸 모델은 직접 설정해야 하며, 도구 호출과 이미지를 지원하는 모델이 필요합니다. 에이전트 단계가 없는 테스트는 모델 없이 실행됩니다.
Claude Max, Team 플랜은 API 키로 연결합니다 — ChatGPT, GitHub Copilot 등은 npx e2e login으로 구독을 연결하지만, Claude Max와 Team은 API 키를 쓰며 비용은 플랜의 월간 API 크레딧에서 차감됩니다.
탐색과 버그 배시는 모델 호출 비용이 듭니다 — e2e explore는 기본 8단계 또는 10분에서 멈추고, --max-steps는 12까지, --timeout은 15분까지 늘릴 수 있습니다. 실행이 끝나면 토큰, 비용, 소요 시간이 표시됩니다. 문서는 발견 항목을 근거와 대조한 뒤 조치하도록 안내합니다.
호스팅 엔진은 별도 서비스입니다 — @e2e-dev/kernel, @e2e-dev/limrun, @e2e-dev/eas, @e2e-dev/smol은 각 서비스가 호스팅하는 브라우저나 시뮬레이터를 연결하는 패키지입니다. 로컬 브라우저와 시뮬레이터만 쓴다면 필요하지 않습니다.
스킬은 e2e 업그레이드 후 다시 설치합니다 — e2e를 업그레이드한 뒤 init을 다시 실행하면 스킬이 갱신됩니다. npx e2e guide [topic]은 설치된 패키지에 들어 있는 스킬 내용을 출력합니다.
출처 — tester-army/e2e (Apache-2.0), 문서: e2e.tester.army/docs.

§ 6

자주 묻는 질문

§ 7.1

e2e는 무엇인가요?

웹과 모바일 앱을 위한 E2E 테스트 프레임워크입니다. 테스트 코드에 목표를 자연어로 적으면 에이전트가 앱을 조작해 목표에 도달하고, 결과는 같은 테스트 안에서 locator와 assertion으로 확인합니다.

§ 7.2

Claude Code에서 어떻게 쓰나요?

`npx e2e init`이 e2e 스킬을 `.claude/skills/e2e/`에 설치하고 MCP 서버를 `.mcp.json`에 등록합니다. 이후 Claude Code가 스킬로 사용법을 익히고, `e2e mcp` 서버로 실행 중인 앱을 직접 살펴보며 테스트를 작성, 실행, 디버깅합니다.

§ 7.3

어떻게 설치하나요?

앱 디렉터리에서 `npx e2e init`을 실행합니다. 웹 또는 모바일 엔진과 모델 제공 방식을 고르면 설정 파일과 예제 테스트가 만들어지고, `npx e2e run`으로 예제를 실행합니다.

§ 7.4

모델이나 API 키가 꼭 필요한가요?

에이전트 단계(`agent.act` 등)를 쓰는 테스트에만 필요합니다. 기본 모델은 없으며, 구독, API 키, 로컬 모델 중 하나를 직접 설정합니다. 에이전트 단계가 없는 테스트는 모델 없이 실행됩니다.

§ 7.5

Claude 구독으로 에이전트 단계를 실행할 수 있나요?

Claude Max 또는 Team 플랜은 로그인 방식이 아니라 API 키로 연결합니다. 비용은 플랜의 사용 한도가 아니라 월간 API 크레딧에서 차감된다고 공식 문서가 안내합니다.

§ 7.6

사용 데이터를 수집하나요?

CLI가 익명 사용 데이터를 보내며, 텔레메트리는 기본으로 켜져 있습니다. 테스트 내용, 앱 내용, 자격 증명은 보내지 않는다고 밝히고 있고, `npx e2e telemetry disable` 또는 환경 변수 `E2E_TELEMETRY_DISABLED=1`로 끌 수 있습니다.