Feature Test Bundle — unit + BDD dual + E2E 3-layer 동시 스캐폴드#

한마디로 (비개발자용)#

새 기능을 만들면 "이게 제대로 작동하는지 확인하는 검사 도구(테스트)"도 같이 있어야 합니다. 이 스킬은 그 검사 도구 3종 세트를 명령어 한 번으로 한꺼번에 준비해 주는 자동 조립 라인입니다. 마치 새 가전제품을 출고하기 전, 부품 검사·기능 검사·실사용 검사를 한 번에 세팅해 주는 품질 관리 라인과 같습니다. 검사의 '틀'을 만들어 주고, 세부 내용은 사람이나 다른 도구가 채워 넣습니다.

무엇을·언제 (비개발자용)#

• 무엇을 해주나요
  • 작은 부품 단위 검사(Unit), 사용자 시나리오 검사(BDD), 여러 화면을 넘나드는 실제 흐름 검사(E2E) 세 가지 검사 틀을 한 번에 만들어 줍니다.
  • 검사 틀만 자동으로 만들고, 비워 둔 부분(채워야 할 곳)을 목록으로 알려 줍니다.
  • 만든 직후 자동으로 한 번 검사를 돌려서, 빠진 부분이 없는지 미리 점검합니다.
• 언제 작동하나요
  • /e2e:kick-off {기능이름} 명령을 실행했을 때
  • 새 기능 구현을 막 끝내고 검사 초안을 빠르게 갖추고 싶을 때
  • 코드 제출(PR) 전에 "검사 3종이 모두 걸려 있는지" 확인하고 싶을 때

핵심 용어 (비개발자용)#

목적#

기능 구현 완료 직후 다음을 하나의 명령 으로 준비:

1. Unit 레이어 — UseCase, Repository, BLoC 단위 테스트 (Mocktail + bloc_test)
2. BDD Dual 레이어 — .feature + TestDriver step + bdd_test_gen → *.widget_test.dart + *.patrol_test.dart
3. E2E 시나리오 레이어 — cross-feature 가 필요하면 integration_test/features/ 로 이관 + test_bundle.dart 등록

각 레이어는 기존 조직 스킬에 위임 — 본 스킬은 오케스트레이션만 담당합니다.

트리거#

• /e2e:kick-off {feature} 실행
• 기능 구현 직후 테스트 초안을 빠르게 갖추고 싶을 때
• PR 제출 전에 "테스트 3 레이어가 모두 걸려 있는지" 확인할 때

전제#

• feature 모듈 이미 존재 (feature/{type}/{name}/) — 없으면 cc-bricks-feature 또는 cc-flutter-dev:feature:* 로 먼저 scaffold
• 해당 feature 의 도메인/데이터/프레젠테이션 3 레이어 코드가 최소 작성됨
• package/test_driver, bdd_test_gen 의존성 pubspec 에 반영
• (선택) flutter-skill MCP 사용 가능 — 탐색 단계 수행 시에만 필요

동작#

1. 사전 조사#

1. feature/{type}/{name}/lib/ 를 읽어 UseCase, BLoC, Repository 목록 수집
2. feature/{type}/{name}/test/src/ 에 기존 테스트 파일 조사 — 중복 생성 방지
3. feature/{type}/{name}/test/src/bdd/{name}.feature 유무 판단
4. .claude/e2e-lock.json 에서 해당 feature 의 lock 된 시나리오 파악 (재저작 방지)

2. Unit 레이어 스캐폴드 (cc-uiux:unit-testing 위임)#

각 UseCase / BLoC / Repository 에 대해 테스트 파일 생성:

• UseCase: test/src/domain/usecase/{use_case_name}_test.dart

  • Mocktail 로 Repository mock
  • should return entity when repository succeeds / should return failure when repository fails 기본 2 테스트

• BLoC: test/src/presentation/bloc/{bloc_name}_test.dart

  • bloc_test 의 blocTest() 사용
  • emits [Loading, Loaded] / emits [Loading, Error] 기본 시나리오

• Repository: test/src/data/repository/{repository_name}_test.dart

  • DataSource mock
  • 주요 메서드별 성공/실패 케이스

실제 스캐폴드는 cc-flutter-dev/commands/test.md 의 /test unit {target} 템플릿을 호출하여 일관성 유지.

3. BDD 레이어 스캐폴드#

3a. .feature 파일 확보

flag { .feature 존재 여부 }
├── 존재 → 그대로 사용 (경고 주석 제거 상태여야 함)
└── 없음
    ├── flutter-skill 세션 실행 가능 → /e2e:explore → /e2e:draft 연속 호출 제안
    └── 아니면 → 최소 skeleton 생성 (영어 + 한글 주석 포맷, @both 태그)

Skeleton 예시:

# DRAFT — auto-generated skeleton by feature-test-bundle
# generated: {timestamp}
# ⚠️ Replace placeholder steps with actual scenarios before /e2e:lock.

@smoke
@{feature_domain}
Feature: {Feature PascalCase} # {한글 이름}
  {one-line user value} # {한글 번역}

  Background:
    Given I am on the {feature} page # {feature} 페이지에 있다

  @both
  Scenario: Happy path for {feature} # {feature} 정상 흐름
    When I tap the {primary_action} button # {primary_action} 버튼 탭
    Then the {expected_state} should be displayed # {expected_state} 표시

3b. TestDriver step 파일 스캐폴드

.feature 의 Given/When/Then 을 파싱해 각 문장에 대응하는 step 파일 템플릿 생성:

• 파일명: snake_case 영어 (i_tap_the_sign_in_button.dart)
• 함수명: camelCase (iTapTheSignInButton)
• 본문은 TestDriver 인자 + TODO 주석 (사람이 채움)
• 필요한 K 상수가 package/test_driver/lib/src/key/k.dart 에 없으면 key-harden-targets.md 에 추가 등록

3c. build.yaml 확인·갱신

해당 feature 패키지의 build.yaml 에 bdd_test_gen|dual_test_gen 활성 확인. 없으면 표준 블록 추가:

targets:
  $default:
    builders:
      bdd_test_gen|dual_test_gen:
        enabled: true
        generate_for:
          - test/src/bdd/*.feature
        options:
          stepFolder: step

3d. 코드 생성

cd feature/{type}/{name}
dart run build_runner build --delete-conflicting-outputs

결과: *.widget_test.dart + *.patrol_test.dart (필요 시 *.widget_test.dart 만).

백엔드 정책 — Patrol/E2E 레이어 기본값 = 로컬 풀스택. 자동 생성되는 *.patrol_test.dart (BDD dual 의 Patrol 측) 와 아래 4 의 cross-feature E2E 레이어는 기본적으로 로컬 풀스택 백엔드를 대상으로 한다 — serverpod start 한 명령이 백엔드 서버 + 내장 Postgres + Flutter 앱을 함께 기동하며(Docker·docker-compose 불필요), 앱은 dev flavor 에서 http://localhost:8080/ 로 연결된다. 핫리로드가 막히면 serverpod start 터미널에서 R 키로 서버+앱 강제 재시작. Staging 은 폴백(nightly/CI 또는 로컬 풀스택 기동 불가 시)이며 앱의 기존 client/OpenApiService/flavor 폴백 설정을 따른다 — base-URL 하드코딩 금지. unit + widget 레이어의 mock 은 그대로 유지 (위 2 / BDD widget_test 의 mock BLoC). 이 노트는 Patrol· integration 레이어에만 적용된다. 셋업·MCP 연동은 serverpod-local-fullstack, serverpod-mcp-guide 스킬 참조. (3.x / legacy: 로컬 DB 는 docker compose up -d 로 기동, 통합테스트는 withServerpod + dart test -t integration — API 동일.)

4. E2E 시나리오 레이어 (선택적)#

.feature 의 시나리오 중 cross-feature 또는 @patrol-only @journey 로 판단되는 시나리오:

1. app/{app}/integration_test/features/{name}.feature 로 이관
2. integration_test/scenarios/{name}_{scenario_slug}_test.dart 생성
3. test_bundle.dart 에 import 추가
4. run_all_scenarios.sh 갱신

판단 휴리스틱:

• @journey 태그
• step 에서 2개 이상 feature 의 페이지 전이
• 실 백엔드 연동 필요 (기본 = 로컬 풀스택 serverpod start + 내장 Postgres, Staging 폴백 → serverpod-local-fullstack)

5. 검증 (/pr:preflight 위임)#

스캐폴드 생성 직후 cc-dev-cycle:pr:preflight --scope={feature-packages} 를 자동 호출:

각 레이어 실패 원인은 preflight 리포트에 그룹화해 제시. /pr:preflight 의 정책은 cc-dev-cycle/rules/pr-preflight-policy.md 참조.

6. 리포트#

사용자에게 출력:

• 생성된 테스트 파일 수 (레이어별)
• TODO 주석이 남은 step 파일 목록 (사람이 채워야 함)
• 다음 단계 제안:
  • TODO 해결 → /e2e:explore 로 실제 조작 확인 → /e2e:draft → /e2e:lock
  • 또는 빠른 경로: cc-flutter-dev:test 에이전트로 unit/widget 완성

출력#

Unit 레이어#

• feature/{type}/{name}/test/src/domain/usecase/*_test.dart
• feature/{type}/{name}/test/src/presentation/bloc/*_test.dart
• feature/{type}/{name}/test/src/data/repository/*_test.dart

BDD Dual 레이어#

• feature/{type}/{name}/test/src/bdd/{name}.feature (신규 or 기존)
• feature/{type}/{name}/test/src/bdd/step/*.dart — TestDriver step 템플릿
• feature/{type}/{name}/test/src/bdd/{name}.widget_test.dart — 자동 생성
• feature/{type}/{name}/test/src/bdd/{name}.patrol_test.dart — 자동 생성
• feature/{type}/{name}/build.yaml — bdd_test_gen 설정 확인

E2E 시나리오 레이어 (선택)#

• app/{app}/integration_test/features/{name}.feature
• app/{app}/integration_test/scenarios/{name}_{scenario}_test.dart
• test_bundle.dart, run_all_scenarios.sh 업데이트

위임 매트릭스#

금지 사항#

• ❌ 기존 조직 스킬(cc-uiux:*, cc-flutter-dev:*) 의 템플릿을 재정의
• ❌ .widget_test.dart, .patrol_test.dart 자동 생성물 수동 편집
• ❌ .feature 를 Korean-only 로 생성 (영어 + 한글 주석 필수)
• ❌ flutter-skill MCP 를 본 스킬 내에서 직접 호출 — /e2e:explore 커맨드를 통해서만
• ❌ lock 된 feature 의 기존 시나리오 덮어쓰기 — draft 로 별도 생성

실패 케이스#

참고#

• 조직 테스트 원전:
  • cc-uiux/skills/unit-testing/SKILL.md
  • cc-uiux/skills/widget-testing/SKILL.md
  • cc-uiux/skills/bdd-testing/SKILL.md
  • cc-uiux/skills/integration-testing/SKILL.md
• 패턴 룰: cc-flutter-dev/rules/bdd-test-patterns.md
• 공유 step: cc-flutter-dev/agents/bdd-step-reuse-agent.md
• 로컬 풀스택 백엔드(Patrol/E2E 기본): serverpod-local-fullstack, serverpod-mcp-guide
• 본 플러그인 연계: skills/exploration, skills/scenario-draft, skills/key-hardening, skills/step-implement, skills/scenario-lock