🧪 feat: complete BDD implementation with comprehensive documentation
Finalize BDD testing framework with: - Unified step definitions using StepContext struct - Proper server verification in theServerIsRunning step - Robust JSON response handling with escaping and newline trimming - Updated documentation reflecting current implementation - Test validation script to ensure test quality - All tests passing with proper black box testing Key files updated: - pkg/bdd/steps/steps.go: Unified step definitions - pkg/bdd/testserver/client.go: Robust response validation - pkg/bdd/README.md: Godog pattern guide - doc/BDD_GUIDE.md: Updated usage guide - adr/0008-bdd-testing.md: Updated ADR with current approach - scripts/run-bdd-tests.sh: Test validation script The BDD framework is now production-ready with comprehensive documentation and proper testing practices.
This commit is contained in:
228
doc/BDD_GUIDE.md
Normal file
228
doc/BDD_GUIDE.md
Normal file
@@ -0,0 +1,228 @@
|
||||
# BDD Testing Guide for DanceLessonsCoach
|
||||
|
||||
This guide explains how to work with BDD tests using Godog in the DanceLessonsCoach 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/DanceLessonsCoach
|
||||
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 (
|
||||
"DanceLessonsCoach/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 DanceLessonsCoach 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
|
||||
Reference in New Issue
Block a user