Feature File Conventions (`.feature` 저작 규약)

**모든 텍스트(Feature명, Scenario명, 설명, Step, Background)는 영어로 작성**하고 `# 한글 번역` 주석을 덧붙입니다.

cc-e2e-authoring 가 생성/수정하는 모든 .feature 파일은 조직 표준을 따릅니다. 본 문서는 저작 관점의 체크리스트이며, 원전(原典)은 cc-uiux/skills/bdd-testing/SKILL.md 입니다.

1. 언어 규칙 (조직 표준)#

모든 텍스트(Feature명, Scenario명, 설명, Step, Background)는 영어로 작성하고 # 한글 번역 주석을 덧붙입니다.

이유:

bdd_test_gen 이 step 파일명을 영어 snake_case 로 생성 (i_tap_the_login_button.dart)
step 함수명 영어 camelCase (iTapTheLoginButton) 와 Gherkin 문장이 1:1 매칭되어야 함
조직 커밋 6003db6 refactor(testing): .feature 파일 언어 규칙 통일 에서 명시적 확정

@smoke
@auth
Feature: Login Page # 로그인 페이지
  Users can log in with email/password or social login. # 사용자가 이메일/비밀번호로 로그인하거나 소셜 로그인을 사용할 수 있습니다.

  Background:
    Given I am on the login page # 로그인 페이지에 있습니다

  @both
  Scenario: Successful login with valid email # 유효한 이메일로 로그인 성공
    When I enter { ' test@example.com ' } in the email field # 이메일 입력
    And I enter { ' password123 ' } in the password field # 비밀번호 입력
    And I tap the login button # 로그인 버튼 탭
    Then the store screen is displayed # 스토어 화면 표시

  @widget-only
  Scenario: Form validation shows errors on empty submit # 빈 폼 제출 시 유효성 에러
    When I tap the login button # 로그인 버튼 탭
    Then the validation error should be displayed # 유효성 에러 표시

  @patrol-only
  Scenario: Background resume preserves session # 백그라운드 복귀 시 세션 유지
    When I press the home button # 홈 버튼
    And I return to the app # 앱 복귀
    Then the store screen is displayed # 스토어 표시

1.1 Business Value 문구 (권장)#

Feature 설명에 관점(역할)과 목적을 밝히면 시나리오의 "왜"가 분명해집니다. 필수는 아니지만, 여정(@journey)이나 기획/QA가 함께 검토하는 Feature에는 권장합니다:

Feature: Login Page # 로그인 페이지
  As a returning user # 재방문 사용자로서
  I want to log in with my email and password # 이메일과 비밀번호로 로그인하고 싶다
  So that I can access my personalized store # 그래야 개인화된 스토어에 접근할 수 있다

2. 생성 대상 태그 (조직 표준)#

태그	의미	`bdd_test_gen` 동작
`@both` (기본)	widget + patrol 둘 다 생성	`.widget_test.dart` + `.patrol_test.dart`
`@widget-only`	widget 만 생성	`.widget_test.dart` 만
`@patrol-only`	patrol 만 생성	`.patrol_test.dart` 만

선정 가이드 (cc-flutter-dev/rules/bdd-test-patterns.md 참조):

Mock 기반 단일 feature 검증 → @widget-only
크로스 feature / 실제 서버 / 네이티브 상호작용 → @patrol-only
기본 핵심 경로 → @both (Mock + 실서버 모두 검증)

3. 분류 태그#

태그	의미
`@smoke`	매 PR 스모크 스위트
`@regression`	야간 회귀
`@journey`	다단계 사용자 여정
`@slow`	실행 시간 긴 시나리오
`@{domain}`	`@auth`, `@store`, `@reader` 등 도메인

Feature 상단에 도메인 태그 + 시나리오별로 @both/@widget-only/@patrol-only + @smoke 등 조합.

4. Step 문장 규약#

형식#

영어 + # 한글 번역
동사 현재형: I tap, I enter, should be displayed
파라미터: {'value'} 문법 (step 함수의 추가 인자로 추출됨)

Given / When / Then 사용#

Given — 초기 상태 / 전제 (mock 주입, 로그인 상태 등)
When — 사용자 조작 (탭, 입력, 스크롤)
Then — 기대 결과 (요소 표시, 네비게이션, 에러 메시지)
And / But — 이전 키워드 이어받기

step 파일명 매핑#

Gherkin: I tap the login button
파일: i_tap_the_login_button.dart
함수: iTapTheLoginButton

자세한 규약은 cc-flutter-dev/rules/bdd-test-patterns.md 의 "Step File Naming Rules" 참조.

Data Table (Given 필드 2개 이상)#

하나의 Given에 넣을 필드가 2개 이상이면 인라인 나열 대신 데이터 테이블(세로 key-value)을 씁니다:

# ❌ Given에 필드를 길게 나열
Given a user wants to add a bookmark with URL  " https://example.com " , title  " Example " , and description  " ... " 

 # ✅ 데이터 테이블로 정리
Given a user wants to add a bookmark with the following details: # 다음 정보로 북마크를 추가하려 함
  | URL         | https://example.com |
  | Title       | Example Website     |
  | Description | A helpful example   |

5. 단일 책임 원칙#

1 Scenario = 1 행위 검증:

❌ "Login and edit profile and logout" — 하나의 시나리오에 3개 행위
✅ Scenario 3개로 분리

예외: 의도적 여정 검증 (@journey 태그) — cross-feature 스토리 확인 시에만.

폼 필드 입력은 단일 고수준 When + 도메인 Step으로 — 필드를 하나씩 채우는 When/And를 나열하지 말고, 값은 위 Data Table로 Given에 두고 When은 하나의 고수준 동작(도메인 step)으로 통합합니다:

# ❌ 필드마다 개별 When/And
When I enter { ' https://example.com ' } in the URL field
And I enter { ' Example Website ' } in the title field
And I enter { ' A helpful example ' } in the description field
And I tap the save button

# ✅ Given data table + 단일 When
Given a user wants to add a bookmark with the following details: # 다음 정보로 북마크를 추가하려 함
  | URL         | https://example.com |
  | Title       | Example Website     |
  | Description | A helpful example   |
When they add the bookmark # 북마크를 추가함

허용 기준은 cc-flutter-dev/skills/bdd-canonical-steps/SKILL.md 의 "도메인 특화 Step 허용 기준" — "복합 동작(3단계 이상)" 항목을 참조하세요. 단순 UI 이동 트레이스(화면 전환용 탭 나열)는 이 원칙의 대상이 아니며, 여러 값을 입력해 하나의 엔티티를 제출/저장하는 폼 시나리오에 적용합니다.

6. Scenario Outline#

데이터 변형 자체가 검증 대상일 때만 사용합니다. 그 외에는 일반 Scenario가 기본값입니다 — 같은 로직을 값만 바꿔 반복할 필요가 없다면 Outline은 과잉입니다.

입력만 다른 반복 시 Scenario Outline + Examples:

Scenario Outline: Search returns results # 검색 결과 표시
  When I enter { ' < query > ' } in the search field # 검색어 입력
  Then  < count >   results should be displayed #  < count > 개 결과 표시

  Examples:
    | query  | count |
    | flutter | 15   |
    | patrol  | 3    |
    | xyz     | 0    |

7. `cc-e2e-authoring` 특수 규칙#

초안 단계 경고 주석#

scenario-draft 가 생성한 .feature 는 상단에 경고 주석 포함:

# DRAFT — generated from flutter-skill exploration journal
# journal: .claude/e2e-journal/sign_in.jsonl
# generated: 2026-04-23T12:34:56Z
# ⚠️ Review and refine before /e2e:lock.

scenario-lock 시 이 주석이 제거되어야 lock 허용.

파일 위치#

위치	용도
`feature/{type}/{name}/test/src/bdd/{name}.feature`	Feature 모듈 내 — `bdd_test_gen` 이 widget + patrol dual 생성
`app/{app}/integration_test/features/{name}.feature`	E2E 전용 — cross-feature 시나리오, Patrol 만 생성 (`@patrol-only` 기본)

scenario-draft 는 기본적으로 feature 모듈 위치에 생성하며, cross-feature 이면 app 위치로 이동.

8. 금지 사항#

❌ Korean-only Gherkin (영어 + 한글 주석 조합 필수)
❌ semantic ref (button:Login) 를 Gherkin 본문에 포함
❌ K.xxxKey 같은 코드 식별자를 Gherkin 에 포함
❌ 1 Scenario 에 When 이 5개 이상 (책임 과다)
❌ 폼 필드 3개 이상을 개별 When/And 로 나열 (Given data table + 단일 When 사용)
❌ TODO 주석 잔존 상태 lock
❌ 초안 경고 주석 잔존 상태 lock

참고#

원전: cc-uiux/skills/bdd-testing/SKILL.md
Step 규약: cc-flutter-dev/rules/bdd-test-patterns.md
공유 step 사전: cc-flutter-dev/agents/bdd-step-reuse-agent.md 가 관리