# 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:**
```gherkin
Then the response should be "{\"message\":\"Hello world!\"}"
```

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

**Incorrect patterns that cause "undefined" warnings:**
```go
// 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:
   ```bash
   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 "{\\"([^"]*)\\":\\"([^"]*)\\"}"$`