tdd-workshop/README.md

TDD Workshop

A hands-on, 2-hour workshop for learning Test-Driven Development through deliberate practice.

---

Workshop Overview

This workshop teaches the RED-GREEN-REFACTOR cycle through:

1. Live demonstration (FizzBuzz kata)
2. Hands-on practice (Password Validator or Shopping Cart)
3. Group reflection and retrospective

Target audience: Developers familiar with TDD concepts but lacking hands-on practice
Duration: 2 hours
Language: Dart

---

Repository Structure

tdd-workshop/
├── README.md (you are here)           # Workshop overview
├── WORKSHOP_PLAN.md                   # Complete facilitator schedule & scripts
├── FACILITATOR_GUIDE.md               # Quick reference for facilitators
├── TDD_REFERENCE_CARD.md              # One-page handout for participants
├── SETUP_GUIDE.md                     # Installation & troubleshooting
│
├── fizzbuzz/                          # Live demo kata
│   ├── README.md                      # Kata overview
│   ├── DEMO_SCRIPT.md                 # Step-by-step demo guide (15 min)
│   ├── lib/fizzbuzz.dart              # Final implementation
│   └── test/fizzbuzz_test.dart        # Progressive tests
│   └── .git/                          # Git history shows TDD progression!
│
├── password_validator/                # Hands-on exercise (Option A)
│   ├── README.md                      # Exercise instructions
│   ├── DEMO_SCRIPT.md                 # Facilitator reference guide
│   ├── lib/
│   │   ├── password_validator.dart    # Starter code (TODO)
│   │   └── password_validator_solution.dart  # Reference solution
│   └── test/
│       └── password_validator_test.dart      # Tests to uncomment step-by-step
│
└── shopping_cart/                     # Hands-on exercise (Option B)
    ├── README.md                      # Exercise instructions
    ├── DEMO_SCRIPT.md                 # Facilitator reference guide
    ├── lib/
    │   ├── shopping_cart.dart         # Starter code (TODO)
    │   └── shopping_cart_solution.dart       # Reference solution
    └── test/
        └── shopping_cart_test.dart           # Tests to uncomment step-by-step

---

For Facilitators

Quick Start

1. Read the plan:

   • Start with WORKSHOP_PLAN.md for complete details
   • Review FACILITATOR_GUIDE.md for quick reference
   • Study fizzbuzz/DEMO_SCRIPT.md for the live demo
   • Review kata demo scripts:
     • password_validator/DEMO_SCRIPT.md (reference for helping stuck participants)
     • shopping_cart/DEMO_SCRIPT.md (reference for helping stuck participants)

2. Practice the demo:

   cd fizzbuzz
   git log --oneline  # See the RED-GREEN-REFACTOR commits
   

   Each commit shows one step of the TDD cycle.

3. Prepare materials:

   • See "Pre-Workshop Preparation" in WORKSHOP_PLAN.md
   • Share SETUP_GUIDE.md with participants 1 week before
   • Have TDD_REFERENCE_CARD.md ready to share

4. Day of workshop:

   • Arrive 15 minutes early
   • Test projector/screen sharing
   • Write schedule on whiteboard
   • Have solution files ready (don't share early!)

Key Documents

Document	Purpose
WORKSHOP_PLAN.md	Complete schedule, scripts, checklists
FACILITATOR_GUIDE.md	Quick reference, kata insights
fizzbuzz/DEMO_SCRIPT.md	Minute-by-minute live demo walkthrough
password_validator/DEMO_SCRIPT.md	Reference guide for helping stuck participants
shopping_cart/DEMO_SCRIPT.md	Reference guide for helping stuck participants
TDD_REFERENCE_CARD.md	Participant handout (print or share digitally)
SETUP_GUIDE.md	For participants before workshop

---

For Participants

Before the Workshop

1. Complete setup: Follow SETUP_GUIDE.md to install Dart and verify tests run
2. Verify installation:

   cd password_validator
   dart pub get
   dart test  # Should see "All tests skipped" or passing
   

3. Bookmark reference: Have TDD_REFERENCE_CARD.md ready during the workshop

During the Workshop

1. Watch the live demo — See RED-GREEN-REFACTOR in action (FizzBuzz)
2. Choose a kata:
   • Password Validator: Rules-based validation, interesting refactoring
   • Shopping Cart: Stateful domain object, data structure decisions
3. Follow the workflow:
   • Uncomment one test at a time
   • Make it RED (watch it fail)
   • Make it GREEN (minimal code to pass)
   • Refactor (clean up duplication)
   • Repeat

Kata Instructions

Password Validator

• Open password_validator/README.md for instructions
• Implement validation rules one at a time
• Step 6 is the refactoring challenge (rules as data)

Shopping Cart

• Open shopping_cart/README.md for instructions
• Build a shopping cart with add, remove, total, discount
• Discover when to use Map vs List (Step 3)
• Learn Value Object pattern (Step 5)

---

What You'll Learn

The TDD Rhythm

• RED: Write a failing test (proves it can fail)
• GREEN: Write minimal code to pass (make it work)
• REFACTOR: Clean up code (make it right)
• REPEAT: Next test

Design Insights

Through hands-on practice, you'll discover:

Password Validator:

• How duplication in tests reveals duplication in code
• Rules as data (Open-Closed Principle)
• Refactoring with tests as a safety net

Shopping Cart:

• How tests drive data structure choices (List → Map)
• Value Objects for validation
• Stateful domain modeling

General:

• Tests as living documentation
• Design emerges from simple tests
• Small steps lead to robust solutions

---

After the Workshop

Continue Practicing

Explore the tdd-katas repository for more practice: https://github.com/dhemasnurjaya/tdd-katas

It contains 5 complete katas with git commit history showing every RED-GREEN-REFACTOR step:

1. Roman Numerals — Table-driven algorithms
2. Bowling Game — State management and look-ahead logic
3. Gilded Rose — Refactoring legacy code safely
4. String Calculator — Bug hunting with TDD
5. Mars Rover — Command pattern and value objects

Resources

Reference materials:

• TDD_REFERENCE_CARD.md — Quick reference for TDD practice

Books:

• Test-Driven Development by Kent Beck
• Clean Code by Robert C. Martin
• Growing Object-Oriented Software, Guided by Tests by Freeman & Pryce

Online practice:

• Kata-Log: https://kata-log.rocks
• Exercism: https://exercism.org
• Coding Dojo: https://codingdojo.org

---

Running the Katas

Password Validator

cd password_validator
dart pub get
dart test

Shopping Cart

cd shopping_cart
dart pub get
dart test

FizzBuzz (Demo)

cd fizzbuzz
dart pub get
dart test

# See TDD progression through git history
git log --oneline

---

Troubleshooting

See SETUP_GUIDE.md for detailed troubleshooting of common issues:

• Dart installation problems
• dart pub get failures
• Test execution errors
• IDE setup

---

Questions?

For facilitators:

• Review WORKSHOP_PLAN.md for comprehensive guidance
• Check FACILITATOR_GUIDE.md for kata-specific insights

For participants:

• During workshop: Raise your hand or ask facilitator
• Before workshop: Contact your facilitator with setup questions
• After workshop: Continue practicing with tdd-katas repository

---

Philosophy

"Clean code that works." — Ron Jeffries

TDD is a discipline, not a burden. The rhythm becomes automatic with practice:

• Tests first (even for "obvious" code)
• Small steps (one test at a time)
• Refactor fearlessly (tests protect you)

The goal: Build muscle memory for the RED-GREEN-REFACTOR cycle.

---

License

This workshop material is provided for educational purposes. Feel free to adapt and use for your own workshops.

---

Ready to start? Facilitators: See WORKSHOP_PLAN.md. Participants: See SETUP_GUIDE.md.