fiatcode
3d94c96ed2
- Password Validator kata with starter code and tests - Shopping Cart kata with starter code and tests - FizzBuzz reference code (from live demo) - Setup guide and TDD reference card - No solutions included (participants implement themselves)
434 lines
9.3 KiB
Markdown
434 lines
9.3 KiB
Markdown
# 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)
|
|
```bash
|
|
brew tap dart-lang/dart
|
|
brew install dart
|
|
```
|
|
|
|
#### Linux (using apt)
|
|
```bash
|
|
sudo apt-get update
|
|
sudo apt-get install dart
|
|
```
|
|
|
|
#### Windows (using Chocolatey)
|
|
```bash
|
|
choco install dart-sdk
|
|
```
|
|
|
|
#### All Platforms (Manual Download)
|
|
Download from: https://dart.dev/get-dart
|
|
|
|
### 2. Verify Dart Installation
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
```bash
|
|
cd password_validator
|
|
dart pub get
|
|
cd ..
|
|
```
|
|
|
|
**Expected output:** `Got dependencies!` or similar success message
|
|
|
|
#### Shopping Cart
|
|
```bash
|
|
cd shopping_cart
|
|
dart pub get
|
|
cd ..
|
|
```
|
|
|
|
#### FizzBuzz (Demo)
|
|
```bash
|
|
cd fizzbuzz
|
|
dart pub get
|
|
cd ..
|
|
```
|
|
|
|
---
|
|
|
|
## Verification
|
|
|
|
Let's make sure everything works!
|
|
|
|
### Test 1: Run Password Validator Tests
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
cd shopping_cart
|
|
dart test
|
|
```
|
|
|
|
**Expected output:** Same as above (all tests skipped or passing)
|
|
|
|
### Test 3: Run FizzBuzz Tests
|
|
|
|
```bash
|
|
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:
|
|
```bash
|
|
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:
|
|
```bash
|
|
which dart
|
|
```
|
|
|
|
2. If nothing shows up, add Dart to PATH:
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
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:
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
dart --version
|
|
```
|
|
|
|
2. If version is below 3.0.0, update Dart:
|
|
```bash
|
|
# macOS
|
|
brew upgrade dart
|
|
|
|
# Linux
|
|
sudo apt-get update
|
|
sudo apt-get install dart
|
|
|
|
# Windows
|
|
choco upgrade dart-sdk
|
|
```
|
|
|
|
3. Re-run:
|
|
```bash
|
|
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:
|
|
```bash
|
|
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. 🚀
|