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

# 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

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

# Run BDD tests
cd features
godog

# Run with specific format
godog -f progress

# Run specific feature
godog features/greet.feature

Links

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

Integration with CI/CD

# 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