5.2 KiB

Raw Blame History

TDD Methodology Expansion Pack - Installation Guide

Quick Start

Copy files to your BMAD installation:

# From the expansion pack directory
cp -r agents/* /path/to/your/bmad-core/agents/
cp -r tasks/* /path/to/your/bmad-core/tasks/
cp -r templates/* /path/to/your/bmad-core/templates/
cp -r scripts/* /path/to/your/bmad-core/scripts/

Update your configuration: Add to bmad-core/core-config.yaml:

tdd:
  enabled: true
  require_for_new_stories: true
  allow_red_phase_ci_failures: true
  default_test_type: unit
  test_runner:
    auto_detect: true
  coverage:
    min_threshold: 0.75

Verify installation:

# Check that TDD commands are available
bmad qa --help | grep tdd
bmad dev --help | grep tdd

Try the demo:

cd examples/tdd-demo
# Follow the demo instructions

Detailed Configuration

Core Configuration Options

# bmad-core/core-config.yaml
tdd:
  # Enable/disable TDD functionality
  enabled: true

  # Require TDD for all new stories
  require_for_new_stories: true

  # Allow CI failures during red phase
  allow_red_phase_ci_failures: true

  # Default test type for new tests
  default_test_type: unit # unit|integration|e2e

  # Test runner configuration
  test_runner:
    auto_detect: true
    fallback_command: 'npm test'
    timeout_seconds: 300

  # Coverage configuration
  coverage:
    min_threshold: 0.75
    report_path: 'coverage/lcov.info'
    fail_under_threshold: true

Test Runner Detection

The expansion pack includes auto-detection for common test runners:

JavaScript/TypeScript: Jest, Vitest, Mocha
Python: pytest, unittest
Java: Maven Surefire, Gradle Test
Go: go test
C#/.NET: dotnet test

Configure custom runners in bmad-core/config/test-runners.yaml:

custom_runners:
  my_runner:
    pattern: 'package.json'
    test_command: 'npm run test:custom'
    watch_command: 'npm run test:watch'
    coverage_command: 'npm run test:coverage'
    report_paths:
      - 'coverage/lcov.info'
      - 'test-results.xml'

CI/CD Integration

GitHub Actions

name: TDD Workflow

on: [push, pull_request]

jobs:
  tdd-validation:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: TDD Guard
        run: |
          chmod +x bmad-core/scripts/tdd-guard.sh
          ./bmad-core/scripts/tdd-guard.sh          
        continue-on-error: ${{ contains(github.head_ref, 'red') }}

      - name: Run Tests
        run: |
          # Your test command (auto-detected by BMAD)
          npm test          

      - name: Coverage Report
        uses: codecov/codecov-action@v3
        with:
          file: coverage/lcov.info

GitLab CI

tdd_guard:
  script:
    - chmod +x bmad-core/scripts/tdd-guard.sh
    - ./bmad-core/scripts/tdd-guard.sh
  allow_failure:
    - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^red-/'

test:
  script:
    - npm test
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: coverage/cobertura-coverage.xml

File Structure

After installation, your BMAD structure should include:

bmad-core/
├── agents/
│   ├── qa.md          # Enhanced with TDD commands
│   └── dev.md         # Enhanced with TDD commands
├── tasks/
│   ├── test-design.md # Enhanced with TDD support
│   ├── write-failing-tests.md
│   ├── tdd-implement.md
│   └── tdd-refactor.md
├── templates/
│   ├── story-tdd-template.md
│   ├── tdd-quality-gates.md
│   └── tdd-ci-template.yml
├── scripts/
│   └── tdd-guard.sh
└── config/
    └── test-runners.yaml

Verification

1. Configuration Check

# Verify TDD is enabled
bmad config --show | grep tdd.enabled

2. Agent Commands Check

# Verify TDD commands are available
bmad qa *tdd-start --help
bmad qa *write-failing-tests --help
bmad dev *tdd-implement --help

3. Demo Run

# Run the complete demo
cd examples/tdd-demo
bmad story 1.1-user-validation.md --tdd

Troubleshooting

Issue: "TDD commands not found"

Solution: Ensure tdd.enabled: true in config and restart BMAD orchestrator

Issue: "Test runner not detected"

Solution: Configure fallback command or add custom runner detection

Issue: "CI failing on red phase"

Solution: Set allow_red_phase_ci_failures: true and use branch naming convention

Issue: "Guard script permission denied"

Solution: chmod +x bmad-core/scripts/tdd-guard.sh

Uninstall

To remove the TDD expansion pack:

Set tdd.enabled: false in config

Remove TDD-specific files (optional):

rm bmad-core/tasks/write-failing-tests.md
rm bmad-core/tasks/tdd-implement.md
rm bmad-core/tasks/tdd-refactor.md
rm bmad-core/templates/story-tdd-template.md
rm bmad-core/templates/tdd-quality-gates.md
rm bmad-core/scripts/tdd-guard.sh

Restore original agent files from backup (if needed)

Support

For installation support:

Check the README.md for comprehensive documentation
Review the MIGRATION.md for existing project integration
Follow standard BMAD-METHOD support channels

5.2 KiB Raw Blame History