📝 docs: consolidate documentation and add comprehensive ADRs\n\n## Summary\nMajor documentation restructuring to improve clarity, reduce redundancy,

and preserve complete architectural context for AI/developer reference.\n\n## Changes\n\n### Documentation Consolidation 🗂️\n- Simplified README.md by ~100 lines (25% reduction)\n- Removed redundant sections (project structure, configuration, API docs)\n- Added strategic cross-references between README.md and AGENTS.md\n- README.md now focused on user onboarding and basic usage\n- AGENTS.md maintained as complete technical reference\n\n### Architecture Decision Records ✅\n- Added comprehensive ADR directory with 9 decision records:\n * 0001-go-1.26.1-standard.md\n * 0002-chi-router.md\n * 0003-zerolog-logging.md (enhanced with Zap analysis)\n * 0004-interface-based-design.md\n * 0005-graceful-shutdown.md\n * 0006-configuration-management.md\n * 0007-opentelemetry-integration.md\n * 0008-bdd-testing.md\n * 0009-hybrid-testing-approach.md\n- Added adr/README.md with guidelines and template\n- Enhanced Zerolog ADR with detailed performance benchmarking vs Zap\n\n### Content Organization 📝\n- README.md: User-focused guide with quick start and basic examples\n- AGENTS.md: Developer/AI-focused complete technical reference\n- ADR directory: Architectural decision history and rationale\n\n## Impact\n- ✅ Better user onboarding experience\n- ✅ Preserved complete technical context for AI agents\n- ✅ Reduced maintenance burden through consolidation\n- ✅ Improved discoverability of advanced documentation\n- ✅ Established ADR process for future decisions\n\n## Related\n- Resolves documentation redundancy issues\n- Prepares for BDD implementation with clear context\n- Supports future Swagger integration decisions\n- Maintains project history for new contributors\n\nGenerated by Mistral Vibe.\nCo-Authored-By: Mistral Vibe <vibe@mistral.ai>
2026-04-04 15:48:27 +02:00
parent 3c1aaea789
commit 95596b5e12
12 changed files with 1471 additions and 98 deletions
--- a/adr/0008-bdd-testing.md
+++ b/adr/0008-bdd-testing.md
@@ -0,0 +1,185 @@
+# 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