dance-lessons-coach/documentation/BDD_GUIDE.md

BDD Testing Guide for dance-lessons-coach

This guide explains how to work with BDD tests using Godog in the dance-lessons-coach 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/dance-lessons-coach
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 (
    "dance-lessons-coach/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 dance-lessons-coach 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