dance-lessons-coach/pkg/bdd

BDD Testing Framework

This directory contains the Behavior-Driven Development (BDD) testing framework for the dance-lessons-coach project, implementing the architecture described in ADR 0024.

🗺️ Architecture Overview

The BDD framework follows a modular, isolated test suite architecture with these key components:

📁 Directory Structure

pkg/bdd/
├── README.md                  # This file
├── context/                   # Feature-specific test contexts
│   ├── auth_context.go        # Authentication test context
│   └── config_context.go       # Configuration test context
├── helpers/                   # Test synchronization helpers
│   └── synchronization.go     # Wait functions and utilities
├── parallel/                  # Parallel test execution
│   ├── port_manager.go        # Port allocation system
│   └── resource_monitor.go    # Resource tracking
├── steps/                     # Step definitions
│   ├── auth_steps.go          # Authentication steps
│   ├── config_steps.go         # Configuration steps
│   ├── greet_steps.go          # Greeting steps
│   ├── health_steps.go         # Health check steps
│   ├── jwt_retention_steps.go  # JWT retention steps
│   └── steps.go               # Main step registration
├── suite.go                   # Test suite initialization
├── suite_feature.go           # Feature-specific suite support
└── testserver/                # Test server implementation
    ├── client.go             # HTTP test client
    └── server.go            # Test server with config

🎯 Core Components

1. Test Server

Location: pkg/bdd/testserver/

The test server provides a real HTTP server instance for black-box testing:

• Hybrid Testing: Runs in-process (not external process)
• Configuration: Loads feature-specific configs from features/*/*-test-config.yaml
• Database: Manages PostgreSQL connections with proper isolation
• Port Management: Uses feature-specific ports (9192-9196)

Key Functions:

• NewServer() - Creates test server instance
• Start() - Starts server with feature-specific configuration
• initDBConnection() - Initializes database connection
• createTestConfig() - Loads feature-specific configuration

2. Step Definitions

Location: pkg/bdd/steps/

Step definitions implement the Gherkin scenarios using Godog:

• Domain-Specific: Organized by feature area (auth, config, greet, etc.)
• Reusable: Common patterns in common_steps.go
• Exact Matching: Uses Godog's exact regex patterns

Example:

// greet_steps.go
func (gs *GreetSteps) iRequestAGreetingFor(name string) error {
    return gs.client.Request("GET", fmt.Sprintf("/api/v1/greet/%s", name), nil)
}

3. Synchronization Helpers

Location: pkg/bdd/helpers/

Helpers provide robust waiting mechanisms for async operations:

• Timeout Support: All functions include timeout parameters
• Polling: Uses context-based polling with configurable intervals
• Common Patterns: Covers server readiness, config reload, API availability

Available Helpers:

• waitForServerReady() - Waits for server to be ready
• waitForConfigReload() - Detects configuration changes
• waitForCondition() - Generic condition waiting
• waitForV2APIEnabled() - Checks v2 API availability

4. Parallel Testing

Location: pkg/bdd/parallel/

Parallel execution infrastructure for CI/CD optimization:

• Port Management: PortManager allocates unique ports
• Resource Monitoring: Tracks memory, goroutines, CPU usage
• Controlled Parallelism: ParallelTestRunner limits concurrency

Key Features:

• Thread-safe port allocation
• Resource limit enforcement
• Timeout detection
• Comprehensive monitoring

5. Feature Contexts

Location: pkg/bdd/context/

Feature-specific test contexts for better organization:

• AuthContext: User management and authentication
• ConfigContext: Configuration file handling
• Extensible: Easy to add new feature contexts

🚀 Test Execution

Running All Tests

# Default: Run all features sequentially
go test ./features/...

# With environment variables
DLC_DATABASE_HOST=localhost DLC_DATABASE_PORT=5432 \
DLC_DATABASE_USER=postgres DLC_DATABASE_PASSWORD=postgres \
DLC_DATABASE_NAME=dance_lessons_coach_bdd_test \
DLC_DATABASE_SSL_MODE=disable \
go test ./features/...

Feature-Specific Testing

# Test specific feature
./scripts/test-feature.sh greet

# Test with specific tags
./scripts/test-by-tag.sh @smoke greet

Parallel Testing

# Run all features in parallel
./scripts/test-all-features-parallel.sh

# Run specific features in parallel
# (Requires PostgreSQL container running)

Tag-Based Testing

# List available tags
./scripts/run-bdd-tests.sh list-tags

# Run smoke tests
./scripts/run-bdd-tests.sh run @smoke

# Run critical tests for auth
./scripts/run-bdd-tests.sh run @critical @auth

📋 Test Organization

Feature Structure

Each feature follows this structure:

features/{feature}/
├── {feature}.feature       # Gherkin scenarios
├── {feature}-test-config.yaml # Feature-specific config
└── {feature}_test.go       # Go test runner

Configuration Files

Feature-specific YAML files define test environment:

# features/greet/greet-test-config.yaml
server:
  host: "127.0.0.1"
  port: 9194

database:
  host: "localhost"
  port: 5432
  name: "dance_lessons_coach_greet_test"

api:
  v2_enabled: true

Tagging System

Comprehensive tagging for selective test execution:

• Feature Tags: @auth, @config, @greet, @health, @jwt
• Priority Tags: @smoke, @critical, @basic, @advanced
• Component Tags: @api, @v2, @database, @security

See features/BDD_TAGS.md for complete documentation.

🔧 Database Management

Database Creation

The framework handles database creation automatically:

1. PostgreSQL Container: Uses Docker (dance-lessons-coach-postgres)
2. Feature Databases: Creates dance_lessons_coach_{feature}_test per feature
3. Cleanup: Automatically drops databases after tests

Database Creation Flow:

1. Check if database exists
2. Create if missing (createdb command)
3. Run tests with isolated database
4. Cleanup (dropdb command)

Configuration

Database settings come from:

• Environment variables (DLC_DATABASE_*)
• Feature-specific config files
• Default values for development

🧪 Best Practices

Step Definition Patterns

// ✅ DO: Use Godog's exact regex patterns
ctx.Step(`^I request a greeting for "([^"]*)"$`, sc.iRequestAGreetingFor)

// ❌ DON'T: Use different patterns
ctx.Step(`^I request greeting "(.*)"$`, sc.iRequestAGreetingFor)

Test Isolation

• Each feature has unique port and database
• No shared state between features
• Cleanup after each test run
• Feature-specific configuration

Synchronization

// ✅ DO: Use helpers for async operations
helpers.waitForServerReady(client, 30*time.Second)

// ❌ DON'T: Use fixed sleep times
time.Sleep(5 * time.Second)

Context Management

// ✅ DO: Use feature-specific contexts
switch featureName {
case "auth":
    authCtx = context.NewAuthContext(client)
    context.InitializeAuthContext(ctx, client)
}

📈 Performance Optimization

Parallel Execution

• Use scripts/test-all-features-parallel.sh for CI/CD
• Limit parallelism based on system resources
• Monitor resource usage with ResourceMonitor

Selective Testing

• Run only relevant tests with tag filtering
• Use @smoke for quick validation
• Use @critical for essential path testing

Resource Management

• Set appropriate timeouts
• Limit maximum goroutines
• Monitor memory usage
• Cleanup resources promptly

🔧 Troubleshooting

Common Issues

Issue	Cause	Solution
Undefined steps	Step pattern mismatch	Use Godog's exact suggested patterns
Port conflicts	Multiple servers	Check port allocation in config files
Database connection	PostgreSQL not running	Start with docker compose up -d postgres
Test isolation	Shared state	Verify unique ports/databases per feature

Debugging

# Verbose output
go test ./features/... -v

# Check specific feature
cd features/greet && go test -v .

# List available tags
./scripts/run-bdd-tests.sh list-tags

📚 Documentation

• ADR 0024: BDD Test Organization and Isolation Strategy
• BDD_TAGS.md: Complete tag reference
• Godog Documentation: https://github.com/cucumber/godog

🎯 Future Enhancements

• Test Impact Analysis: Track which tests are affected by code changes
• Flaky Test Detection: Automatically identify and quarantine flaky tests
• Performance Benchmarking: Monitor test execution times
• AI-Assisted Testing: Automated test generation and optimization

This BDD framework provides a robust foundation for behavior-driven development in the dance-lessons-coach project, ensuring test reliability, maintainability, and scalability.