사전 준비

이 단계는 한 번만 하면 됩니다. 이미 깔려 있는 항목은 건너뛰면 됩니다.

여기서 까는 건 두 묶음으로 나뉩니다. 먼저 어느 트랙을 고르든 공통으로 필요한 것(Node, git, 패키지 매니저, Claude Code)을 깔고, 트랙별 테스트 도구(웹/데스크톱은 Playwright 브라우저, 모바일은 Maestro)는 무엇을 테스트할지 정하기에서 트랙을 고른 다음에 깝니다. 그러니 이 페이지에서는 공통 묶음을 먼저 끝내 두면 됩니다.

운영체제별 차이

항목	macOS	Windows	Linux
사용하는 터미널	`Terminal.app` 또는 iTerm2	WSL2 위의 Ubuntu 권장. PowerShell도 가능하지만 안내가 길어집니다.	배포판이 제공하는 셸
검증 상태	검증됨	WSL2 먼저 깐 다음 그 안에서 모든 명령 실행	검증됨

Windows에서는 WSL2 설치 안내를 먼저 끝낸 다음 이쪽으로 돌아오세요. 이 매뉴얼의 모든 명령은 WSL2 위 Ubuntu 셸 안에서 실행한다고 가정합니다. 다만 모바일 트랙은 사정이 다릅니다. iOS 시뮬레이터는 macOS에서만 돌고, Android 에뮬레이터도 WSL2 안에서는 까다롭습니다. 모바일 트랙을 쓸 거면 macOS 또는 Linux 본체를 권합니다.

1) Node.js 20 이상

macOS와 Linux는 nvm 권장

터미널을 열고 한 줄씩 실행합니다.

# nvm (Node Version Manager) 설치
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 새 터미널을 열거나, 다음 두 줄을 붙여 넣어 nvm을 지금 바로 활성화
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# Node 20 설치 후 사용
nvm install 20
nvm use 20

설치 검증

node --version    # v20.x.x 가 출력되어야 정상
npm --version     # 10.x.x 비슷한 숫자가 출력되면 정상

둘 중 하나라도 아무것도 출력되지 않는다면 트러블슈팅의 “Node가 설치되지 않습니다” 항목으로 갑니다.

새 터미널에서 node --version이 다시 안 떠 있다면 nvm 활성화 두 줄이 셸 시작 파일에 안 들어간 상태입니다. zsh라면 ~/.zshrc, bash라면 ~/.bashrc를 열고 nvm 설치 출력 끝부분에 보였던 export NVM_DIR=... 두 줄이 들어가 있는지 확인하세요. 없으면 손으로 붙여 넣고 새 터미널을 엽니다.

2) git

macOS

xcode-select --install

이 명령은 git만 따로 깔지 않고 Apple의 Command Line Tools 묶음을 설치합니다. 작은 다이얼로그 창이 떠서 동의를 받고 설치가 시작됩니다. git이 이미 깔려 있으면 안내 메시지만 한 줄 띄우고 끝납니다.

Linux와 WSL2

sudo apt update && sudo apt install -y git

설치 검증

git --version    # git version 2.x.x

처음이라면 본인 정보를 한 번 등록해 둡니다.

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

3) 패키지 매니저 — pnpm 권장

이 base는 어느 패키지 매니저든 돌지만 pnpm을 권합니다. 한 줄로 깔립니다.

npm install -g pnpm

설치 검증

pnpm --version    # 8.x 또는 9.x 비슷한 숫자가 나오면 정상

어느 매니저를 쓸지는 첫 실행 단계의 /2-setup-base에서 한 번 묻고 .claude/state/package-manager.json에 박힙니다. 그 뒤로는 본인이 고른 매니저가 자동으로 쓰입니다.

4) Claude Code

공식 설치 안내는 docs.claude.com/ko/docs/claude-code/quickstart에 있습니다. 설치 후 claude를 한 번 실행해 로그인하거나 API 키를 등록합니다.

claude --version

버전 번호가 출력되면 준비 완료입니다. Claude Code 대신 OpenAI Codex CLI를 써도 됩니다. 그 경우 진입점은 저장소 루트의 AGENTS.md이고 같은 흐름이 그대로 적용됩니다. 처음이라면 Claude Code를 권합니다.

5) 트랙별 테스트 도구 — 트랙을 고른 뒤에

여기서부터는 본인 앱이 어느 트랙인지에 따라 까는 게 달라집니다. 그 결정은 무엇을 테스트할지 정하기에서 합니다. 지금은 어떤 도구를 깔게 될지만 미리 봐 두면 됩니다.

웹 또는 데스크톱(Electron) 트랙이면 Playwright 브라우저. 의존성을 설치한 다음 한 줄로 받습니다.

pnpm exec playwright install --with-deps chromium

이 명령은 테스트가 띄울 실제 브라우저를 받습니다. 처음에는 용량이 커서 몇 분 걸립니다. base의 init.sh도 @playwright/test가 의존성에 보이면 이 줄을 자동으로 돌려 줍니다.

모바일 트랙이면 Maestro CLI.

curl -Ls "https://get.maestro.mobile.dev" | bash

설치 후 새 터미널에서 maestro --version이 떠야 정상입니다. 자세한 안내는 docs.maestro.dev에 있습니다.

아직 트랙을 안 정했다면 이 5번은 건너뛰고 다음 단계로 가도 됩니다. 트랙을 고른 뒤에 base가 어느 도구가 필요한지 알려 줍니다.

6) 테스트 환경변수 파일

base 안에는 .env.test.example이라는 파일이 들어 있습니다. 테스트에 필요한 환경변수의 이름 목록만 적혀 있고 실제 값은 비어 있습니다. 이걸 복사해서 본인 값을 채울 파일을 만듭니다.

cp .env.test.example .env.test.local

.env.test.local은 .gitignore에 들어 있어 git에 올라가지 않습니다. 테스트 계정 비밀번호 같은 실제 값은 이 파일에만 둡니다.

공통 묶음(Node, git, 패키지 매니저, Claude Code)이 자리를 잡았다면 내려받기와 설치로 갑니다. 트랙별 도구는 그 뒤에 트랙을 고르면서 깝니다.