tdd-workshop-exercises/SETUP_GUIDE.md

Workshop Setup Guide

Complete these steps BEFORE the workshop to ensure smooth experience.

---

Prerequisites

Required Software

• Dart SDK version 3.0.0 or higher
• Git (for cloning the repository)
• A code editor (VS Code, IntelliJ IDEA, or any editor you prefer)

Recommended (Optional)

• VS Code Extensions:
  • Dart (official)
  • Flutter (if working with Flutter projects)
• IntelliJ/Android Studio Plugins:
  • Dart plugin
  • Flutter plugin (if applicable)

---

Installation Steps

1. Install Dart SDK

macOS (using Homebrew)

brew tap dart-lang/dart
brew install dart

Linux (using apt)

sudo apt-get update
sudo apt-get install dart

Windows (using Chocolatey)

choco install dart-sdk

All Platforms (Manual Download)

Download from: https://dart.dev/get-dart

2. Verify Dart Installation

dart --version

Expected output: Something like Dart SDK version: 3.x.x

If you see an error, Dart isn't in your PATH. See Troubleshooting section below.

3. Clone the Workshop Repository

git clone <repository-url>
cd tdd-workshop

(Your facilitator will provide the actual repository URL)

4. Set Up Each Kata

Navigate to each kata directory and install dependencies:

Password Validator

cd password_validator
dart pub get
cd ..

Expected output: Got dependencies! or similar success message

Shopping Cart

cd shopping_cart
dart pub get
cd ..

FizzBuzz (Demo)

cd fizzbuzz
dart pub get
cd ..

---

Verification

Let's make sure everything works!

Test 1: Run Password Validator Tests

cd password_validator
dart test

Expected output:

All tests skipped.

OR

00:00 +0: All tests passed!

If you see errors, see Troubleshooting section.

Test 2: Run Shopping Cart Tests

cd shopping_cart
dart test

Expected output: Same as above (all tests skipped or passing)

Test 3: Run FizzBuzz Tests

cd fizzbuzz
dart test

Expected output:

00:00 +5: All tests passed!

(FizzBuzz has completed tests)

---

IDE Setup (Optional but Recommended)

Visual Studio Code

1. Install VS Code: https://code.visualstudio.com/

2. Install Dart extension:

   • Open VS Code
   • Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
   • Search for "Dart"
   • Install the official Dart extension

3. Open the workshop folder:

   code tdd-workshop
   

4. Verify syntax highlighting works:

   • Open password_validator/lib/password_validator.dart
   • Code should be colorized
   • You should see IntelliSense when typing

IntelliJ IDEA / Android Studio

1. Install IntelliJ IDEA (Community Edition is free): https://www.jetbrains.com/idea/

2. Install Dart plugin:

   • Go to Settings → Plugins
   • Search for "Dart"
   • Install and restart

3. Open the workshop folder:

   • File → Open → Navigate to tdd-workshop

---

Day-of-Workshop Checklist

Have these ready BEFORE the workshop starts:

• Laptop charged (or bring charger)
• Workshop repository cloned and dependencies installed
• All verification tests passing
• Code editor open with workshop directory loaded
• Terminal window ready
• This reference card bookmarked: TDD_REFERENCE_CARD.md

Optional nice-to-haves:

• Two monitor setup (or large screen for split view)
• Comfortable keyboard
• Water/coffee nearby

---

Troubleshooting

Problem: dart: command not found

Cause: Dart isn't in your system PATH

Fix (macOS/Linux):

1. Find where Dart is installed:

   which dart
   

2. If nothing shows up, add Dart to PATH:

   # For Homebrew installation on macOS
   echo 'export PATH="$PATH:/usr/local/opt/dart/libexec"' >> ~/.zshrc
   source ~/.zshrc
   
   # For manual installation
   echo 'export PATH="$PATH:/path/to/dart-sdk/bin"' >> ~/.zshrc
   source ~/.zshrc
   

3. Verify:

   dart --version
   

Fix (Windows):

1. Search for "Environment Variables" in Start menu
2. Click "Edit system environment variables"
3. Click "Environment Variables"
4. Find "Path" in System variables
5. Add the path to dart-sdk/bin (e.g., C:\tools\dart-sdk\bin)
6. Restart terminal and verify: dart --version

---

Problem: dart pub get fails with network error

Cause: Firewall, proxy, or network restrictions

Fix:

1. Check internet connection

2. If behind corporate proxy:

   # Set proxy (replace with your proxy details)
   export HTTP_PROXY=http://proxy.company.com:8080
   export HTTPS_PROXY=http://proxy.company.com:8080
   dart pub get
   

3. If still failing, try:

   dart pub get --verbose
   

   (Shows detailed error messages)

---

Problem: dart pub get succeeds but dart test fails with package errors

Cause: Corrupted package cache

Fix:

# Clear pub cache and reinstall
dart pub cache repair
cd password_validator
dart pub get
dart test

---

Problem: Tests run but show errors like "Target of URI doesn't exist"

Cause: Dependencies not installed or IDE not recognizing them

Fix:

1. Run dart pub get again in that directory
2. Restart your IDE
3. If using VS Code, run command: "Dart: Restart Analysis Server"
   • Ctrl+Shift+P (Cmd+Shift+P on Mac) → Search for "Dart: Restart"

---

Problem: VS Code doesn't recognize Dart files

Cause: Dart extension not installed or not enabled

Fix:

1. Open Extensions (Ctrl+Shift+X)
2. Search "Dart"
3. Make sure official Dart extension is installed and enabled
4. Restart VS Code

---

Problem: Tests are running but output is hard to read

Fix:

# Run tests with verbose output
dart test --reporter=expanded

# Run specific test file
dart test test/password_validator_test.dart

---

Problem: Getting "version solving failed" errors

Cause: Dart SDK version mismatch

Fix:

1. Check your Dart version:

   dart --version
   

2. If version is below 3.0.0, update Dart:

   # macOS
   brew upgrade dart
   
   # Linux
   sudo apt-get update
   sudo apt-get install dart
   
   # Windows
   choco upgrade dart-sdk
   

3. Re-run:

   dart pub get
   

---

Problem: Can't clone repository (Git not installed)

Fix:

1. Install Git:

   • macOS: brew install git
   • Linux: sudo apt-get install git
   • Windows: Download from https://git-scm.com/

2. Verify:

   git --version
   

3. Try cloning again

---

Still Having Issues?

During the workshop:

• Arrive 10 minutes early and ask the facilitator for help
• Bring this troubleshooting guide with you

Before the workshop:

• Email the facilitator with:
  • Output of dart --version
  • Full error message from the failing command
  • Your operating system

---

Workspace Layout Suggestions

Option 1: Split Screen (Recommended for Beginners)

┌──────────────────┬──────────────────┐
│                  │                  │
│  Editor          │  Editor          │
│  (lib/ files)    │  (test/ files)   │
│                  │                  │
│                  │                  │
├──────────────────┴──────────────────┤
│  Terminal (dart test)               │
└─────────────────────────────────────┘

Option 2: Two Monitors

Monitor 1               Monitor 2
┌──────────────┐        ┌──────────────┐
│              │        │              │
│  Editor      │        │  Browser     │
│  (Full)      │        │  - Workshop  │
│              │        │    guide     │
│              │        │  - Reference │
│              │        │    card      │
└──────────────┘        └──────────────┘

Option 3: Single Screen (Compact)

┌─────────────────────────────────────┐
│  Editor (maximized)                 │
│  Tabs: lib file | test file         │
│                                     │
│                                     │
│                                     │
└─────────────────────────────────────┘
Use Alt+Tab to switch to terminal

---

Quick Command Reference

Task	Command
Run all tests	dart test
Run specific test file	dart test test/password_validator_test.dart
Run tests with detailed output	dart test --reporter=expanded
Watch mode (re-run on changes)	dart test --watch (experimental)
Install dependencies	dart pub get
Check Dart version	dart --version
Clear pub cache	dart pub cache repair

---

Support During Workshop

If you have issues during the workshop:

1. Raise your hand — facilitator will come to you
2. Ask a neighbor — pair programming is encouraged
3. Check this guide — most issues are covered here

---

You're all set! See you at the workshop. 🚀