dance-lessons-coach/.vibe/skills/bdd-testing/references/GODOG_PATTERNS.md

Godog Pattern Requirements

This document captures the critical pattern requirements from our validated BDD implementation.

Important Requirements for Step Definitions

Step Pattern Matching

Godog has very specific requirements for step pattern matching. To avoid "undefined" warnings:

1. Use the exact regex pattern that Godog suggests in its error messages
2. Use the exact parameter names that Godog suggests (arg1, arg2, etc.)
3. Match the feature file syntax exactly including quotes and JSON formatting

Example

Feature file step:

Then the response should be "{\"message\":\"Hello world!\"}"

Correct step definition:

ctx.Step(`^the response should be "{\"([^"]*)\":\"([^"]*)"}"$`, func(arg1, arg2 string) error {
    // Implementation here
    return nil
})

Incorrect patterns that cause "undefined" warnings:

// Wrong: Different regex pattern
ctx.Step(`^the response should be "{\"message\":\"([^"]*)"}"$`, func(message string) error {
    // ...
})

// Wrong: Different parameter names
ctx.Step(`^the response should be "{\"([^"]*)\":\"([^"]*)"}"$`, func(key, value string) error {
    // ...
})

Current Implementation Strategy

Step Definition Strategy

1. First eliminate "undefined" warnings by using Godog's exact suggested patterns
2. Return godog.ErrPending initially to confirm pattern matching works
3. Then implement actual validation logic

Debugging "Undefined" Steps

If you see "undefined" warnings:

1. Run the tests to see Godog's suggested pattern:

   go test ./features/... -v
   

2. Copy the exact regex pattern from the error message

3. Copy the exact parameter names (arg1, arg2, etc.)

4. Update your step definition to match exactly

Common Mistakes

The "undefined" warnings are not a Godog bug - they occur when step definitions don't match Godog's expected patterns exactly:

• Using different regex patterns than what Godog suggests
• Using descriptive parameter names instead of arg1, arg2
• Not escaping quotes properly in JSON patterns
• Trying to be "clever" with regex optimization

Solution: Always use the exact pattern and parameter names that Godog suggests in its error messages.

Best Practices

1. Follow Godog's suggestions exactly - Copy-paste the pattern and parameter names
2. Test pattern matching first - Use godog.ErrPending to verify patterns work
3. Then implement logic - Replace godog.ErrPending with actual validation
4. Don't over-optimize regex - Use the patterns Godog provides, even if they seem verbose
5. One pattern per step type - Use generic patterns to cover similar steps

Why This Matters

Godog's step matching is very specific by design:

• It needs to reliably match feature file steps to code
• It provides exact patterns to ensure consistency
• Following its suggestions guarantees your steps will be recognized

Remember: The "undefined" warnings are Godog telling you exactly how to fix your step definitions!

Critical Pattern Fix

File: pkg/bdd/steps/steps.go Line: 80 Issue: Step pattern must use double escaping (4 backslashes + quote) not single escaping (2 backslashes + quote) Pattern: ^the response should be "{\\"([^"]*)\\":\\"([^"]*)\\"}"$