bdd-practices

BDD Practices

Specify features in Gherkin format and optionally connect them to automated tests.

Core Philosophy:

• Feature First: .feature specification first, implementation later
• Specification by Example: concrete scenarios instead of abstract requirements
• Living Documentation: .feature = executable documentation (valuable even without automation)

The Value of .feature Files

The .feature file itself is:

• Requirements specification - Structured with Given/When/Then
• Acceptance Criteria - Clarifies completion criteria
• Edge case documentation - Organizes exceptional situations
• Team communication tool - Readable even by non-developers

Even when used only as a specification without automation, it provides sufficient value.

Phase 1: Discovery

When discussing a new feature or requirement:

1. Understanding requirements

   • Clearly understand the feature requested by the user
   • Ask the user about ambiguous parts

2. Example Mapping

   • Derive Rules and Examples
   • Identify edge cases
   • Create a list of questions

3. Create a list of scenarios

   • List core scenarios (Happy Path)
   • List exception scenarios (Edge Cases)
   • Prioritization criteria:
     1. Happy Path (normal flow) - first
     2. Most common exception cases
     3. Business-critical cases
     4. Edge cases - later
   • Example: "We will proceed with the following scenarios in order: 1) valid login, 2) wrong password, 3) non-existent user"

4. User confirmation

   • Show the list of scenarios
   • Check for missing cases

5. Proceed to Phase 2

---

Phase 2: Formulation

Write scenarios in Gherkin format:

1. Decide file location

   • Within the project, features/ directory (recommended)
   • Check whether existing .feature files exist
   • Confirm with the user

2. Write .feature file

   Feature: 기능명
     기능에 대한 설명
   
     Scenario: 시나리오명
       Given 전제조건
       When 행동
       Then 결과
   

3. Gherkin writing principles

   • Only one behavior per scenario
   • Use concrete example data
   • Do not expose implementation details (UI elements, DB queries, etc.)
   • Write in business language

4. Language selection

   • When using Korean keywords, on the first line of the file add # language: ko add
   • Non-developer collaboration, Korean domain → Korean recommended
   • Global team, open source → English recommended

5. Detailed syntax: resources/01-gherkin-syntax.md Reference (including Korean keywords)

6. User confirmation

   • Show the written scenarios
   • "Does this scenario accurately reflect the requirements?"

7. ldoc integration (optional)

   • .feature can be used as ldoc's requirements document
   • docs/requirements/ or features/ recommended to place in the directory

8. Proceed to Phase 3

---

Phase 3: Automation (optional)

To connect .feature to automated tests:

1. Check whether to automate

   • If only the specification is needed → complete in Phase 2
   • If automated tests are needed → proceed below

2. Detailed guide: resources/02-automation.md reference

   • Write Step definitions (Python/JavaScript)
   • Configure pytest-bdd, behave, cucumber-js
   • RED → GREEN → REFACTOR cycle

3. tdd-practices integration

   • Keep Step definitions thin
   • Develop complex internal logic with tdd-practices

---

AI Red Flags 🚨

If any of the following signs appear, stop immediately and report to the user:

• 🚨 Starting implementation without a .feature

  • BDD is specification first, implementation later
  • "I will write the scenario first"

• 🚨 Attempting to run tests without Step definitions

  • Tests cannot run without Step definitions
  • Do not skip Phase 3

• 🚨 Implementing features not in the scenario

  • Implement only the behavior defined in the .feature
  • Additional features go into new scenarios

• 🚨 Exposing implementation details in the .feature

  • "Click the button" ❌
  • "Attempt to log in" ✅

---

tdd-practices integration

BDD vs TDD:

• BDD: scenario level (.feature → Step definitions)
• TDD: unit level (test → function/class)

Integration point: when complex logic is needed in the automation step

• Keep Step definitions thin
• Develop internal logic with tdd-practices' RED-GREEN-REFACTOR

---

Examples

Write feature specification (no automation)

User: "주문 취소 기능 명세해줘"
→ Phase 1: 시나리오 도출
  - 배송 전 취소 → 전액 환불
  - 배송 중 취소 → 불가
  - 배송 완료 후 → 반품 절차
→ Phase 2: features/order-cancel.feature 생성
→ 완료 (명세 문서로 활용)

Full BDD flow (including automation)

User: "로그인 기능 BDD로 구현해줘"
→ Phase 1-2: .feature 작성
→ Phase 3: resources/02-automation.md 참조
→ Step definitions + 구현

Add scenarios to an existing .feature

User: "비밀번호 찾기 시나리오 추가해줘"
→ Phase 1: 시나리오 도출
→ Phase 2: 기존 .feature에 추가

---

Technical Details

• Gherkin detailed syntax: resources/01-gherkin-syntax.md
• Automation guide: resources/02-automation.md
• Template: templates/crud.feature, templates/auth.feature
• Unit test integration: tdd-practices