BDD Feature File Generator

Generate .feature files for Golang Clean Architecture projects using established BDD patterns and existing step definitions.

Critical Constraints

• ONLY use existing step definitions - Never create new step definitions
• Follow exact patterns from existing feature files
• All feature files must be created in /test/integration/features/
• Examine existing features before creating new ones

When to Use

Activate this skill when:

• Creating BDD feature files for API testing
• Writing Gherkin scenarios for integration tests
• Generating Cucumber/Godog test specifications
• Developing test scenarios for REST endpoints
• Creating validation test suites
• Setting up database state verification tests
• Testing external API integrations
• Validating event publishing (SNS/SQS)

Workflow

1. Gather Requirements

Ask the user for:

• Feature name and purpose
• API endpoint(s) and methods
• Request/response field structures
• Validation rules needed
• Database tables affected
• External API dependencies
• Events to publish/consume
• Error codes and messages

2. Analyze Similar Features

Check existing features in /test/integration/features/ for:

• Similar endpoint patterns (create, update, list, delete)
• Validation scenario structures
• Error handling patterns
• Database setup approaches

3. Generate Feature File

File Structure

• Location: /test/integration/features/feature-name.feature
• Name: Use kebab-case (e.g., create-user.feature)
• Always include: #language: en and #utf-8 headers

Background Section

Set up common test prerequisites:

• Clear tables and headers
• Environment variables
• AWS secrets
• External API mocks
• Test data preparation
• Authentication headers

Scenarios Structure

Validation Scenarios (use Scenario Outline):

• Required field validation (empty string and null)
• Invalid value validation
• Format validation (email, phone, etc.)
• Business rule validation

Success Scenarios:

• Minimal required fields
• All fields populated
• Database state verification
• External API call verification
• Event publishing verification

Error Scenarios:

• Not found (404)
• Unauthorized (401)
• Forbidden (403)
• Conflict/Duplicate (409)
• Internal errors (500)

4. Apply Patterns

Error Response Structure

Then the status returned should be 400
And the response should contain the field "error.code" equal to "PREFIX-01400"
And the response should contain the field "error.description" equal to "Bad request"
And the response should contain the field "error.error_details.0.attribute" equal to "<attribute>"
And the response should contain the field "error.error_details.0.messages.0" equal to "<message>"

Error Code Format

• Pattern: PREFIX-ERRNUM
• PREFIX: 3-letter module code (e.g., USR, CLI, ORD)
• ERRNUM: 5-digit number (01400, 01404, etc.)

Special Values

• "not nil" - Assert non-null/non-empty
• "nil" - Assert null/empty
• null - JSON null in examples
• "" - Empty string

Tags Convention

• Always include @all
• Add feature-specific tag
• Add category tags:
  • @success
  • @error
  • @contract_fields_validation
  • @response_validation
  • @database_validation
  • @external_api
  • @events

Quick Reference

Step Definitions

For complete step definitions, see: references/step-definitions.md

Key categories:

• Given: Environment setup, database state, API mocks
• When: HTTP requests, event processing
• Then: Response validation, database checks, event verification

Patterns & Examples

For detailed patterns, see: references/patterns-examples.md

Includes:

• Complete feature file structure
• Common scenario patterns
• Error handling examples
• Naming conventions

Template

Use the template at: assets/feature-template.feature

Copy and customize for new features.

Examples

Create Entity Feature

@all @create_entity
Feature: Create entity functionality

  Background:
    Given the tables are empty
    And the header is empty
    And the "API_KEY" env var is set to "test-key"

  @create_entity @contract_fields_validation
  Scenario Outline: Create entity failure - bad request
    When I call "POST" "/v1/entities" with the following payload
    """
    {
        "name": <n>,
        "type": <type>
    }
    """
    Then the status returned should be 400
    And the response should contain the field "error.code" equal to "ENT-01400"
    And the response should contain the field "error.error_details.0.attribute" equal to "<attribute>"
    And the response should contain the field "error.error_details.0.messages.0" equal to "<message>"

    Examples:
      | name    | type    | attribute | message                    |
      | ""      | "valid" | name      | REQUIRED_ATTRIBUTE_MISSING |
      | null    | "valid" | name      | REQUIRED_ATTRIBUTE_MISSING |
      | "valid" | ""      | type      | REQUIRED_ATTRIBUTE_MISSING |

List with Pagination

@all @list_entities
Feature: List entities functionality

  @list_entities @pagination
  Scenario: List entities with pagination
    Given the "entities" exists
    """
    [
      {"id": "1", "name": "Entity 1"},
      {"id": "2", "name": "Entity 2"},
      {"id": "3", "name": "Entity 3"}
    ]
    """
    When I call "GET" "/v1/entities?page_size=2&page=1"
    Then the status returned should be 200
    And the response should contain the field "items" array length equal to 2
    And the response should contain the field "pagination.total" equal to "3"

Best Practices

1. Start with validation scenarios - Use Scenario Outline for multiple test cases
2. Test edge cases - Empty strings, null values, invalid formats
3. Verify database state - Check records were created/updated correctly
4. Mock external dependencies - Use Given steps for API mocks
5. Follow naming conventions - Consistent scenario names and file naming
6. Reuse patterns - Copy from similar existing features
7. Keep scenarios focused - One concept per scenario
8. Use meaningful test data - Realistic values, not "test123"

Important Notes

• Never create new step definitions - work within existing ones
• Always check /test/integration/features/ for similar features first
• Maintain consistency with existing error codes and response structures
• Feature files are created BEFORE implementation code
• Use the exact step definition syntax - no variations allowed