트러블슈팅

이 페이지는 사람들이 가장 자주 멈추는 자리를 모아 둔 곳입니다. 본인이 보고 있는 증상과 가까운 항목을 찾아 그 아래 안내를 따라가 보세요. 여기에 없는 증상이라면 에러 메시지를 그대로 복사해서 Claude Code에 붙여 넣고 “이거 어떻게 고쳐?”라고 물으면 다음에 시도할 만한 한 수가 보통 따라옵니다.

테스트가 돌릴 때마다 결과가 흔들립니다

같은 테스트가 어떤 때는 통과하고 어떤 때는 실패한다면 flaky입니다. 가장 흔한 원인은 테스트가 화면이 다 뜨기 전에 다음 동작을 해 버리는 자리입니다.

코드 안에 임의로 몇 초 기다리는 대기(하드 sleep, waitForTimeout 같은 것)가 들어 있으면 그게 flaky의 1순위 원인입니다. 빠른 컴퓨터에서는 통과하고 느린 컴퓨터에서는 실패합니다. 이건 본인이 직접 고치지 말고 AI에게 “이 테스트에 하드 sleep이 들어 있어서 흔들려요. 화면이 준비되면 자동으로 기다리는 방식으로 바꿔 줘”라고 시키면 됩니다.

flaky가 검증에서 두 번 잡혀 blocked까지 가면 AI가 막혔을 때의 /recover-from-blocked로 풀어 갑니다.

Playwright 브라우저가 안 깔려 있습니다

web 또는 electron 트랙에서 테스트를 돌렸는데 “browser not found”, “Executable doesn’t exist” 같은 메시지가 보입니다. 테스트가 띄울 실제 브라우저를 아직 안 받은 상태입니다.

pnpm exec playwright install --with-deps chromium

이 한 줄로 받습니다. 처음에는 용량이 커서 몇 분 걸립니다. 이게 네트워크에서 막히면 잠시 후 다시 시도합니다. base의 init.sh도 이 줄을 자동으로 돌리지만, 도중에 끊겼다면 직접 한 번 더 돌려야 합니다.

브라우저 바이너리는 CI에서도 캐싱하지 않고 매번 새로 받습니다. 버전이 어긋나면 더 골치 아픈 자리가 생기기 때문입니다. 그래서 매번 받는 게 정상입니다.

Maestro CLI가 없습니다

mobile 트랙에서 “command not found: maestro”가 보입니다. Maestro를 아직 안 깐 상태입니다.

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

설치 후 새 터미널을 열고 maestro --version이 떠야 정상입니다. 설치했는데도 안 보인다면 셸 시작 파일에 경로가 안 들어간 경우입니다. 설치 출력 끝부분에 적힌 안내를 따라 경로를 추가하고 새 터미널을 엽니다.

로그인이 안 되거나 인증에서 막힙니다

테스트가 로그인 단계에서 멈추거나 “401”, “403”, “unauthorized” 같은 메시지가 보입니다. 거의 항상 .env.test.local이 빠졌거나 비어 있는 자리입니다.

먼저 파일이 있는지 봅니다.

ls -la .env.test.local

파일이 없으면 사전 준비의 6번처럼 cp .env.test.example .env.test.local부터 다시 합니다. 파일은 있는데 테스트 계정 비밀번호 같은 값이 비어 있다면 그 값을 채웁니다.

값을 고친 다음에는 테스트를 다시 돌려야 반영됩니다. 그리고 이 자리에 쓰는 계정은 반드시 전용 테스트 계정이어야 합니다. 본인이 실제로 쓰는 계정으로 테스트하면 그 계정의 데이터가 흔들립니다.

테스트가 화면 요소를 못 찾습니다

“locator not found”, “no element matches”, “element is not visible” 같은 메시지가 보입니다. 테스트가 누르려는 버튼이나 입력 칸을 화면에서 못 찾은 자리입니다. 둘 중 하나입니다.

본인 앱의 화면이 바뀌어서 그 요소가 사라졌거나 이름이 달라진 경우. 이건 본인 앱 쪽 변화이니 테스트를 그에 맞게 고쳐야 합니다.

또는 테스트가 요소를 화면 구조(CSS나 XPath) 위치로 찾고 있어서, 화면이 조금만 바뀌어도 못 찾게 된 경우. 이 base는 요소를 구조 위치가 아니라 보이는 글자나 버튼 역할로 찾는 걸 권합니다. 그래야 화면이 바뀌어도 잘 버팁니다. AI에게 “이 셀렉터가 화면 구조에 의존해서 깨져요. 보이는 글자나 역할로 찾도록 바꿔 줘”라고 시키면 됩니다. 그 요소에 보이는 라벨(예: “저장”, “로그인”)을 같이 알려 주면 더 정확합니다.

Electron 메인 프로세스에 접근이 안 됩니다

electron 트랙에서 다이얼로그나 메뉴, 트레이 아이콘을 클릭하려는 테스트가 막히거나, 메인 프로세스 쪽 동작이 잡히지 않습니다.

Electron 앱의 네이티브 UI(파일 열기 다이얼로그, 시스템 메뉴, 트레이)는 테스트가 직접 클릭할 수 없습니다. 이건 한계입니다. 대신 그 동작을 흉내 내는 방식으로 짜야 합니다. 이 자리는 비개발자가 직접 손보기 어려우니 AI에게 “이 다이얼로그를 직접 클릭하지 말고 메인 프로세스 쪽에서 흉내 내는 방식으로 바꿔 줘”라고 시키는 게 빠릅니다. 자세한 패턴은 전문가용 매뉴얼에 있습니다.

로컬 Linux에서 electron 테스트를 돌리는데 창이 안 뜨고 막힌다면 화면 없는 환경이라 그렇습니다. xvfb-run으로 감싸 돌려야 합니다.

CI에서 테스트가 깨지거나 샤딩이 어긋납니다

GitHub Actions에서 테스트가 로컬과 다르게 깨진다면 보통 환경 차이입니다. 브라우저가 매번 새로 설치되는지, 테스트 환경변수가 GitHub의 시크릿 저장소에 들어 있는지 확인합니다. .env.test.local은 git에 안 올라가니 CI에서는 그 값을 별도로 등록해 둬야 합니다.

샤딩(테스트를 여러 조각으로 나눠 병렬로 돌리는 것)이 어긋나 결과가 일부만 보인다면 조각들의 결과를 합치는 단계가 빠졌을 수 있습니다. 이 자리는 비개발자 영역을 벗어나니 전문가용 매뉴얼의 CI 페이지에서 시작하거나, AI에게 워크플로 파일을 보여 주고 고쳐 달라고 하는 게 낫습니다.

그 밖에

이 페이지에 같은 증상이 없다면 두 가지를 더 시도해 볼 수 있습니다.

먼저, 에러 메시지 전체를 복사해 Claude Code에 붙여 넣고 “이거 고쳐 줘”라고 입력합니다. 다음에 시도할 한 수를 보통 잘 짚어 줍니다. 더 자세한 출력이 필요하면 .claude/state/last-run.log에 마지막 실행의 전체 로그가 들어 있습니다.

그래도 풀리지 않으면 GitHub 이슈를 열거나 팀 Slack에 글을 올립니다. 다음 세 가지를 함께 적어 주세요.

• 어디서 막혔는지 (어느 트랙, 어느 흐름, 어느 명령)
• 에러 메시지 전체
• 환경 정보 (운영체제, Node 버전, 트랙과 도구)

AI 워크플로 자체가 같은 자리에서 두 번 맴도는 막힘은 이 페이지가 아니라 AI가 막혔을 때의 영역입니다.