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:

```bash
# 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:

```bash
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

```bash
# From project root
cd /Users/gabrielradureau/Work/Vibe/dance-lessons-coach
go test ./features/... -v
```

### Run Specific Feature

```bash
# 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

```bash
# 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:

```gherkin
# 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/`:

```go
// 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`:

```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:

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

## Additional Resources

- [Godog GitHub](https://github.com/cucumber/godog)
- [Godog Documentation](https://github.com/cucumber/godog#readme)
- [Cucumber Documentation](https://cucumber.io/docs/gherkin/)
- [BDD Introduction](https://dannorth.net/introducing-bdd/)

## 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