/marionette — 실행 중인 앱을 손대지 않고 조종하는 "인형술사"#

한마디로#

실제로 켜져 있는 Flutter 앱을 소스 코드를 고치지 않고 마치 인형처럼 조종해 주는 도구입니다. 버튼을 눌러 보고, 글자를 입력해 보고, 화면을 캡처하면서 "이 화면·이 컴포넌트가 제대로 동작하는지" 자동으로 점검합니다.

누가·언제 쓰나요#

• 이미 실행 중인 앱을 직접 클릭·입력해 보며 동작을 확인하고 싶을 때
• 디자인 시스템(CoUI) 컴포넌트나 화면들을 한꺼번에 둘러보며 회귀 점검(regression sweep) 을 하고 싶을 때
• 여러 화면을 빠르게 훑어 깨진 곳이 없는지 스모크 테스트하고 싶을 때
• 특정 버튼 같은 컴포넌트 하나의 동작만 콕 집어 검증하고 싶을 때

코드를 바꾸지 않으므로, QA·디자이너·기획자도 "지금 만들어진 화면이 실제로 잘 도는지" 확인하는 데 활용할 수 있습니다.

무엇을 해주나요#

• 실행 중인 앱에 자동으로 연결해, 탭·텍스트 입력·핫 리로드·스크린샷을 대신 수행합니다.
• 점검 결과(스크린샷 등)를 .claude/docs/marionette/<run_id>/ 폴더에 정리해 남겨 줍니다.
• 한 번에 여러 화면을 돌아보거나, 컴포넌트 하나만 깊게 검증하는 등 상황에 맞게 골라 쓸 수 있습니다.

어떻게 쓰나요#

# 처음 한 번만 — 설치 및 초기 연결 준비
/marionette setup

# Widgetbook 카탈로그 전체를 돌며 회귀 점검
/marionette sweep --catalogue=coui

# 주요 화면들을 빠르게 스모크 테스트
/marionette smoke --routes=/home,/posts,/settings

# 컴포넌트 하나만 콕 집어 검증
/marionette verify-component --type=PrimaryButton --usecase=destructive

• setup: 맨 처음 딱 한 번만 실행하는 설치·등록 단계입니다.
• sweep: --catalogue로 지정한 목록(예: coui)을 쭉 훑어 각 항목을 캡처·조작합니다.
• smoke: --routes에 적은 화면들만 빠르게 점검합니다(,로 구분).
• verify-component: --type(컴포넌트 종류)과 --usecase(사용 예시)를 지정해 하나만 검증합니다.
• 아무 하위 명령 없이 /marionette만 실행하면, 실행 중인 앱을 찾아 자동 연결한 뒤 현재 화면만 스모크 테스트합니다.

안에서 무슨 일이 벌어지나요#

하위 명령을 적지 않고 그냥 실행했을 때 기본 동작은 다음과 같습니다.

1. 표준 포트(기본 8181)에서 실행 중인 Flutter 앱이 있는지 찾습니다.
2. 앱을 찾으면 자동으로 연결(connect) 합니다.
3. 지금 보고 있는 현재 화면만 스모크 테스트합니다.

# First time only
/marionette setup

# Drive a Widgetbook regression sweep
/marionette sweep --catalogue=coui

# Smoke test top-level routes
/marionette smoke --routes=/home,/posts,/settings

# Verify a single component
/marionette verify-component --type=PrimaryButton --usecase=destructive