/moai e2e

웹·모바일·데스크탑 애플리케이션의 E2E (End-to-End) 테스트를 생성하고 실행하는 명령어입니다. 프로젝트 유형을 자동 감지하고, 플랫폼에 맞는 CLI 우선 툴체인을 선택해 토큰을 최소화하며 실행합니다. 전체 실행 로그는 파일로 돌리고 컨텍스트에는 종료 코드와 요약만 남기기 때문에, 긴 테스트 출력이 컨텍스트를 잡아먹지 않습니다.

정보

한 줄 요약: /moai e2e는 “사용자 여정 검증 도구” 입니다. 로그인 → 결제 → 확인 같은 실제 사용자 흐름을 브라우저·시뮬레이터·데스크탑 앱에서 끝까지 실행해 검증합니다.

정보

슬래시 커맨드: Claude Code에서 /moai:e2e를 입력하면 이 명령어를 바로 실행할 수 있습니다. /moai만 입력하면 사용 가능한 모든 서브커맨드 목록이 표시됩니다.

단위 테스트가 함수 하나를 검증한다면, E2E 테스트는 사용자가 실제로 거치는 흐름 전체를 검증합니다. /moai e2e는 이 과정을 자동으로 처리합니다. 프로젝트가 웹인지 모바일인지 데스크탑인지 스스로 가려낸 다음, 플랫폼별 기본 툴체인을 골라 테스트 스크립트를 쓰고 실행합니다.

전체 흐름은 다음과 같습니다.

flowchart TD
    Start["/moai e2e 실행"] --> Detect["플랫폼 자동 감지
(프로젝트 마커 스캔)"]
    Detect --> Select["툴체인 선택
(기본값 권장 + 사용자 확인)"]
    Select --> Journey["사용자 여정 매핑
(라우트·문서 분석)"]
    Journey --> Script["테스트 스크립트 작성"]
    Script --> Run["CLI 우선 실행
(출력은 파일로, 컨텍스트엔 요약만)"]
    Run --> Record["기록 (선택)
--record 시 네이티브 트레이스"]
    Record --> Report["결과 보고
(여정별 상태 + 아티팩트 경로)"]

> /moai e2e

인수 없이 실행하면 프로젝트 유형을 감지한 뒤, 추천 툴체인과 발견된 사용자 여정을 제시하고 선택을 받아 진행합니다.

# 툴체인을 지정해 바로 실행
> /moai e2e --tool playwright

# 특정 여정만 실행
> /moai e2e --journey login

# 실행 과정을 기록 (트레이스/레코딩)
> /moai e2e --record

플랫폼마다 기본 툴체인이 정해져 있으며, 모든 기본 경로는 CLI만으로 완결됩니다.

선택한 툴체인이 설치되어 있지 않으면, 설치 명령어를 먼저 제시하고 승인 후 설치 → 버전 재확인 → 진행합니다.

데스크탑-네이티브 레인은 세 OS (macOS·Windows·Linux) 의 접근성 레시피를 모두 문서로 갖추고 있지만, 호스트 OS 규칙에 따라 호스트와 다른 OS의 레시피는 설명으로만 남겨 두고, 실제 프로브와 실행은 호스트 OS에서만 합니다.

프로젝트의 마커 파일을 읽어 플랫폼을 분류합니다. 감지는 마커 기반이며 특정 언어나 프레임워크를 우대하지 않습니다.

프로젝트 문서와 라우트 정의 (routes.ts, urls.py, router.go, 내비게이션 그래프 등) 를 읽어 테스트할 사용자 여정 후보를 추립니다. 로그인, 핵심 기능, 오류 처리처럼 중요한 경로가 앞순위입니다.

여정: 사용자 로그인
단계:
1. /login으로 이동 (웹) | 로그인 화면으로 앱 실행 (모바일/데스크탑)
2. 이메일 입력
3. 비밀번호 입력
4. 제출
5. /dashboard로 리다이렉트 확인
6. 환영 메시지 표시 확인

선택된 툴체인의 규약에 맞춰 e2e/ 디렉토리에 테스트 스크립트를 작성합니다.

모든 여정 단계는 검증할 수 있는 결과와 짝을 이룹니다. 단언 (assertion) 없이 화면만 넘기는 스크립트는 쓰지 않습니다.

테스트를 실행하고, 여정별 PASS/FAIL 상태·소요 시간·아티팩트 경로를 표로 보고합니다. 실패한 여정은 실패 지점의 로그 발췌와 스크린샷 경로가 함께 제공됩니다.

--autofix 플래그를 주면 Phase 3 실행에서 실패나 개선 여지가 발견됐을 때, 오케스트레이터가 수정을 manager-develop 에이전트에 위임하고 Phase 3를 재실행하는 루프에 진입합니다. 플래그가 없거나 Phase 3가 green이면 이 단계는 건너뜁니다.

flowchart TD
    Run["Phase 3 실행"] --> Fail{"실패/개선 저지?"}
    Fail -->|"아니오"| Green["Phase 5 보고"]
    Fail -->|"예 (--autofix)"| Approve["진입 승인 1회"]
    Approve --> Group["저지 그룹화
독립=병렬 / 의존=순차"]
    Group --> Fix["manager-develop
autofix: localize→repair→validate"]
    Fix --> Run

• 진입 승인 1회: 첫 위임 전에 오케스트레이터가 한 번 승인을 받습니다. 이 승인 하나가 루프 전체를 덮으므로 다음 반복부터는 다시 묻지 않습니다. 거절하면 원래의 수동 진행 흐름으로 돌아갑니다.
• 저지 그룹화: 서로 다른 파일을 건드리는 독립 저지는 병렬 fan-out, 같은 모듈을 건드리는 의존 저지는 순차 처리합니다 (동시 쓰기 충돌 방지).
• 루프 한계: 최대 3회 반복 (ci-autofix-protocol.md와 동일). green이면 보고하고, 3회를 다 쓰면 남은 실패와 아티팩트 경로를 사용자에게 돌려줍니다.

/moai e2e의 핵심 설계 원칙은 CLI 우선 (CLI-first) 입니다. AI 컨텍스트에 장황한 출력을 쌓는 대신, 가장 싼 경로부터 사용합니다.

1. CLI + 제한된 꼬리 출력: 전체 실행 로그는 e2e/.runs/ 아래 파일로 저장하고, 컨텍스트에는 종료 코드 + 마지막 일부만 표시합니다. 로그 파일 경로는 항상 인용됩니다.
2. 구조화 리포터: 실패 분석 시 전체 재실행 대신 JSON 리포터 출력에서 실패한 스펙만 선별해 읽습니다.
3. MCP는 조건부: 성능 트레이스, Lighthouse류 감사처럼 CLI로 불가능한 기능에만 MCP 도구를 사용합니다. MCP는 어떤 기본 경로에서도 필수 의존성이 아닙니다.

보고서·트레이스·스크린샷·레코딩은 프로젝트 안의 e2e/ 디렉토리에 저장하고 경로만 인용합니다. 내용을 컨텍스트에 그대로 펼쳐 넣지 않습니다.

--record 플래그를 사용하면 선택한 툴체인의 네이티브 기록 기능으로 실행을 기록합니다.

테스트할 E2E 표면이 감지되지 않으면 (예: 웹/모바일/데스크탑 진입점이 없는 순수 라이브러리), 어떤 마커를 확인했는지 근거와 함께 “E2E 대상 없음“을 보고하고 e2e/ 아티팩트를 만들지 않은 채 정상 종료합니다.

Electron도 Tauri도 아닌 네이티브 데스크탑 앱 (순수 macOS 앱, WinUI, Qt/GTK 등) 이 잡히면 이 분기로 빠지지 않습니다. 데스크탑-네이티브 자동화 레인 (macOS의 axcli, Windows의 FlaUI.WebDriver, Linux의 dogtail) 으로 넘어가 테스트가 정상적으로 진행됩니다. “E2E 대상 없음” 분기는 테스트할 표면이 하나도 없는 순수 라이브러리에만 해당합니다.

/moai e2e의 실행 주체는 e2e-tester 에이전트입니다. 모든 사용자 선택 질문은 MoAI 오케스트레이터가 담당하고, e2e-tester는 선택 결과를 전달받아 실행만 수행합니다.

flowchart TD
    User["사용자 요청"] --> Orchestrator["MoAI 오케스트레이터"]
    Orchestrator --> Detect["e2e-tester
플랫폼 감지 + 툴체인 프로브"]
    Detect --> Ask["오케스트레이터
툴체인·여정 선택 질문"]
    Ask --> Exec["e2e-tester
스크립트 작성 + CLI 실행 + 기록"]
    Exec --> Report["오케스트레이터
결과 보고"]

• /moai fix - 일회성 자동 수정
• /moai loop - 반복 수정 루프
• /moai - 완전 자율 자동화