dance-lessons-coach/documentation/BDD_GUIDE.md

BDD Testing Guide for DanceLessonsCoach

This guide explains how to work with BDD tests using Godog in the DanceLessonsCoach project.

Installation

Modern Go Approach (Recommended)

The idiomatic and modern way to install Godog for developers joining the project:

# Install Godog as a Go tool (recommended approach)
go install github.com/cucumber/godog/cmd/godog@latest

This installs the godog binary in your $GOPATH/bin directory. Make sure this directory is in your PATH.

Alternative: Using go run

You can also run Godog directly without installing:

go run github.com/cucumber/godog/cmd/godog@latest

Project Setup

The project already includes Godog as a dependency in go.mod. The BDD tests are integrated into the standard Go testing framework.

Running BDD Tests

Run All BDD Tests

# From project root
cd /Users/gabrielradureau/Work/Vibe/DanceLessonsCoach
go test ./features/... -v

Run Specific Feature

# Run only greet feature
go test ./features/... -v -run "TestBDD/Greet"

# Run only health feature
go test ./features/... -v -run "TestBDD/Health"

# Run only readiness feature
go test ./features/... -v -run "TestBDD/Readiness"

Different Output Formats

# Progress format (default)
go test ./features/... -v

# Pretty format
go test ./features/... -v -godog.format=pretty

# JSON format
go test ./features/... -v -godog.format=json

# HTML report
go test ./features/... -v -godog.format=html > report.html

Project Structure

features/
├── bdd_test.go           # Main test entry point
├── greet.feature         # Greet service feature
└── health.feature        # Health endpoint feature

pkg/bdd/
├── steps/                # Step definitions
│   └── steps.go          # All step definitions
│
├── testserver/          # Test infrastructure
│   ├── server.go         # Test server management
│   └── client.go         # HTTP client for testing
│
├── suite.go             # Test suite initialization
└── README.md            # BDD usage guide

Writing New Features

1. Create Feature File

Create a new .feature file in the features/ directory using Gherkin syntax:

# features/new_feature.feature
Feature: New Feature
  Description of the new feature

  Scenario: Happy path
    Given some precondition
    When I perform an action
    Then I should see the expected result

2. Implement Step Definitions

Create a corresponding step definition file in pkg/bdd/steps/:

// pkg/bdd/steps/new_feature_steps.go
package steps

import (
    "DanceLessonsCoach/pkg/bdd/testserver"
    "github.com/cucumber/godog"
)

func InitializeNewFeatureSteps(ctx *godog.ScenarioContext, client *testserver.Client) {
    ctx.Step(`^some precondition$`, func() error {
        // Implementation
        return nil
    })

    ctx.Step(`^I perform an action$`, func() error {
        // Implementation
        return nil
    })

    ctx.Step(`^I should see the expected result$`, func() error {
        // Implementation
        return nil
    })
}

3. Register Steps

Add your step initialization to pkg/bdd/suite.go:

func InitializeScenario(ctx *godog.ScenarioContext) {
    server := testserver.NewServer()
    client := testserver.NewClient(server)

    // Initialize all steps using the unified approach
    steps.InitializeAllSteps(ctx, client)

    // ... cleanup code
}

Best Practices

Test Organization

• One feature per file: Keep feature files focused on a single capability
• Clear scenario names: Use descriptive scenario names that explain the behavior
• Reusable steps: Create reusable step definitions when possible
• Black box testing: Test through public APIs only, no internal knowledge

Performance

• Parallel execution: Godog supports parallel scenario execution
• Isolated scenarios: Each scenario should be independent
• Cleanup: Always cleanup resources in After hooks

Debugging

• Verbose output: Use -v flag for detailed output
• Step-by-step: Run with -godog.tags=@focus to run specific scenarios
• Dry run: Check step definitions without running tests

Troubleshooting

Server not starting

If tests fail with "server did not become ready", check:

• Port conflicts: lsof -i :8080
• Server logs: Check if server process starts properly
• Configuration: Verify config.yaml settings

Missing step definitions

If you see "undefined steps", you need to:

1. Implement the missing step definitions
2. Register them in the suite initialization
3. Re-run the tests

Test isolation issues

Ensure each scenario:

• Starts with a clean state
• Doesn't depend on other scenarios
• Properly cleans up resources

CI/CD Integration

Add BDD tests to your CI pipeline:

# Example GitHub Actions step
- name: Run BDD Tests
  run: go test ./features/... -v

Additional Resources

• Godog GitHub
• Godog Documentation
• Cucumber Documentation
• BDD Introduction

Modern Go Testing Practices

The DanceLessonsCoach project follows modern Go testing practices:

1. Standard library integration: BDD tests use go test
2. No global installation required: Godog is a Go module dependency
3. Cross-platform: Works on all Go-supported platforms
4. IDE integration: Works with Go tools and IDEs
5. Dependency management: Versioned through go.mod

This approach ensures that:

• All developers use the same Godog version
• No manual installation steps are needed
• Tests work consistently across environments
• CI/CD integration is straightforward