전문가용 시작

이 매뉴얼은 Playwright나 Maestro를 한 번이라도 만져봤고, e2e 테스트가 왜 불안정한지 겪어봤고, Claude Code 또는 Codex로 작업을 맡겨본 적 있는 독자를 가정합니다. 페이지 객체(POM)라는 말을 들어봤다는 정도면 충분합니다. 디렉터리 구조와 인증 재사용, 트랙 분리는 다음 섹션 architecture에서 설명합니다.

다른 ddakit 베이스를 써본 적 있으면 먼저 이 차이부터 짚어야 합니다. chrome-ext나 saas-base는 앱을 만듭니다. e2e-base는 앱을 만들지 않습니다. 이미 있는 외부 앱이 설명대로 동작하는지를 자동으로 검증합니다. 그래서 build-and-package, real-backend, customize-design 같은 “만드는 베이스” 섹션이 여기에는 없고, 그 대신 tracks, analyze-and-design, verification이 들어갑니다.

산출물은 테스트 스위트이고 대상 시스템은 외부에 있다

검증 대상은 대상 시스템(SUT, System Under Test)이라고 부릅니다. 본인이 만든 앱일 수도 있고 남이 만든 앱일 수도 있으며, 배포된 URL이거나 로컬 dev server이거나 빌드 바이너리이거나 Expo, RN, 네이티브 빌드입니다. e2e-base를 fork 해서 얻는 산출물은 그 대상 시스템 옆에 붙는 tests/ 트리입니다. 앱 소스가 아닙니다.

이 전제가 매뉴얼 전체를 관통합니다. “테스트할 앱을 어떻게 만드나”라는 질문은 여기서 다루지 않습니다. 그 질문은 다른 베이스가 다룹니다.

3 트랙

타겟 종류에 따라 트랙을 고릅니다. 셋 다 한 스위트에 공존할 수 있고, 보통은 한두 개만 씁니다.

트랙	기본 도구	대안
web	Playwright	Cypress(레거시 호환 시만)
electron	Playwright _electron	@wdio/electron-service(패키징 빌드 검증)
mobile	Maestro	Detox(RN), Appium(범용), XCUITest/Espresso(네이티브)

트랙별로 페이지를 나누지 않습니다. 셋이 같은 Phase 1~6 워크플로우를 공유하고 차이는 흐름이 아니라 도구 세부 사항에 있어서, 도구 설정은 tracks 한 페이지에 표로 모았습니다.

S6 운영 환경 금지

가장 먼저 정해 둔 가드레일 하나만 여기서 짚습니다. 테스트는 운영 환경의 대상 시스템과 운영 환경 DB에 절대 붙지 않습니다. 로컬, 스테이징, 전용 테스트 환경만 씁니다. “테스트하려면 운영 서버에 붙이면 되겠지”가 이 도메인에서 가장 위험한 오해입니다. 나머지 보안 기준선 S1~S8과 금지 패턴은 verification에 모았습니다.

자동화 진입점은 한 곳을 가리킨다

Claude Code 쪽 진입점은 .claude/agents/와 .claude/skills/이고, Codex 쪽은 저장소 루트의 AGENTS.md입니다. 두 경로 모두 결국 AI_AUTOMATION.md 하나를 읽습니다. 테스트 아키텍처 규칙, 보안 기준선 S1S8, 금지 패턴, 여섯 관점 검증 채점 기준, Phase 16 흐름이 전부 거기 모여 있습니다. 두 도구가 같은 기준 문서를 공유하니까 Claude Code에서 내린 결정이 Codex 세션에서도 그대로 적용됩니다.

무오염 원칙

베이스를 막 fork 한 시점에는 tests/가 비어 있습니다. feature_list.json, active.md, progress.md 같은 런타임 산출물도 없습니다. fork 한 사람의 첫 프로젝트 시작(/start)이 빈 템플릿을 생성하고, 거기서부터 Phase가 진행되는 동안 채워집니다. 이 매뉴얼이 가르치는 것은 그 빈 골격이 Phase 흐름을 거치며 어떻게 채워지는지의 절차이지, e2e-base 자체의 reference 테스트 코드가 아닙니다.

라이선스

매뉴얼과 랜딩 페이지는 공개돼 있지만 템플릿 자체는 상업 라이선스 모델을 따릅니다. fork 한 코드의 재배포는 허용되지 않습니다.

이 매뉴얼이 가정하지 않는 것

OS별 설치 분기, Playwright 브라우저나 Maestro CLI 설치 화면, 터미널이 처음인 사람을 위한 단계별 안내는 여기에 없습니다. 그쪽이 필요하면 비개발자용 매뉴얼을 봅니다. 같은 베이스를 다른 방식으로 설명한 짝입니다.

다음

다음 섹션은 architecture입니다. tests/{web,electron,mobile} 디렉터리가 어떻게 나뉘는지, 페이지 객체와 fixtures가 어떻게 묶이는지, 시나리오 한 줄이 어떻게 테스트 한 개가 되는지를 다이어그램 두 개와 함께 봅니다.