dance-lessons-coach/adr/0008-bdd-testing.md

# Adopt BDD with Godog for behavioral testing

* Status: Accepted
* Deciders: Gabriel Radureau, AI Agent
* Date: 2026-04-05

## Context and Problem Statement

We needed to add behavioral testing to DanceLessonsCoach that provides:
- User-centric test scenarios
- Living documentation
- Integration testing capabilities
- Clear communication between technical and non-technical stakeholders
- Complementary testing to unit tests

## Decision Drivers

* Need for higher-level testing than unit tests
* Desire for living documentation that's always up-to-date
* Requirement for testing through public interfaces
* Need for clear behavioral specifications
* Desire for good test organization and readability

## Considered Options

* Godog (Cucumber for Go) - BDD framework for Go
* Ginkgo - BDD-style testing framework
* Standard Go testing - Extended for integration tests
* Custom BDD framework - Build our own

## Decision Outcome

Chosen option: "Godog" because it provides proper BDD support with Gherkin syntax, good Go integration, living documentation capabilities, and follows standard Cucumber patterns.

## Pros and Cons of the Options

### Godog

* Good, because proper BDD with Gherkin syntax
* Good, because living documentation
* Good, because good Go integration
* Good, because follows Cucumber standards
* Good, because clear separation of concerns
* Bad, because slightly more complex setup
* Bad, because slower execution than unit tests

### Ginkgo

* Good, because good BDD-style testing
* Good, because fast execution
* Good, because good Go integration
* Bad, because not proper Gherkin/BDD
* Bad, because less clear for non-technical stakeholders

### Standard Go testing

* Good, because no external dependencies
* Good, because familiar to Go developers
* Bad, because no BDD capabilities
* Bad, because no living documentation
* Bad, because less organized for behavioral tests

### Custom BDD framework

* Good, because tailored to our needs
* Good, because no external dependencies
* Bad, because time-consuming to develop
* Bad, because need to maintain ourselves
* Bad, because likely less feature-rich

## Implementation Structure

```
features/
├── greet.feature          # Gherkin feature files
├── health.feature
└── readiness.feature

pkg/bdd/
├── steps/                 # Step definitions
│   ├── greet_steps.go     # Implementation of steps
│   ├── health_steps.go
│   └── readiness_steps.go
│
├── testserver/            # Test infrastructure
│   ├── server.go          # Test server management
│   └── client.go          # HTTP client for testing
│
└── suite.go               # Test suite initialization
```

## Example Feature File

```gherkin
# features/greet.feature
Feature: Greet Service
  The greet service should return appropriate greetings

  Scenario: Default greeting
    Given the server is running
    When I request the default greeting
    Then the response should be "Hello world!"

  Scenario: Personalized greeting
    Given the server is running
    When I request a greeting for "John"
    Then the response should be "Hello John!"
```

## Example Step Implementation

```go
// pkg/bdd/steps/greet_steps.go
func InitializeGreetSteps(ctx *godog.ScenarioContext, client *testserver.Client) {
    ctx.Step(`^the server is running$`, func() error {
        return client.Start()
    })

    ctx.Step(`^I request the default greeting$`, func() error {
        return client.Request("GET", "/api/v1/greet/", nil)
    })

    ctx.Step(`^I request a greeting for "([^"]*)"$`, func(name string) error {
        return client.Request("GET", fmt.Sprintf("/api/v1/greet/%s", name), nil)
    })

    ctx.Step(`^the response should be "([^"]*)"$`, func(expected string) error {
        return client.ExpectResponseBody(expected)
    })
}
```

## Black Box Testing Approach

The BDD implementation follows black box testing principles:

* **External perspective**: Tests interact only through public HTTP API
* **No implementation knowledge**: Tests don't know about internal components
* **Behavior focus**: Tests verify what the system does, not how it does it
* **Interface testing**: Tests verify the contract between system and users

## Testing Strategy

### Test Types

1. **Direct HTTP tests**: Test raw API behavior
2. **SDK client tests**: Test generated client integration (future)

### Test Execution

```bash
# Run BDD tests
cd features
godog

# Run with specific format
godog -f progress

# Run specific feature
godog features/greet.feature
```

## Links

* [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/)

## Integration with CI/CD

```yaml
# Example GitHub Actions step
- name: Run BDD tests
  run: |
    cd features
    godog -f progress
```

## Performance Considerations

* BDD tests are slower than unit tests (expected)
* Each scenario runs with fresh server instance for isolation
* Tests can be run in parallel where appropriate
* Focus on critical paths rather than exhaustive testing