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

Start with validation scenarios - Use Scenario Outline for multiple test cases
Test edge cases - Empty strings, null values, invalid formats
Verify database state - Check records were created/updated correctly
Mock external dependencies - Use Given steps for API mocks
Follow naming conventions - Consistent scenario names and file naming
Reuse patterns - Copy from similar existing features
Keep scenarios focused - One concept per scenario
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

bdd-feature-generator