{
  "id": "page:library-bdd-specification-by-example",
  "_kind": "Page",
  "_file": "wiki/library/bdd-specification-by-example.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "title": "BDD/Specification by Example (Library)",
    "displayName": "BDD/Specification by Example (Library)",
    "slug": "library/bdd-specification-by-example",
    "articlePath": "wiki/library/bdd-specification-by-example.md",
    "article": "\n# BDD/Specification by Example\n\n## Overview\n\nBehavior-Driven Development (BDD), also known as Specification by Example, is a collaborative approach that captures requirements as concrete examples illustrating how the system should behave in specific scenarios. These examples become executable specifications that serve as both documentation and automated tests.\n\n**Creators**: Dan North (BDD, 2006), Gojko Adzic (Specification by Example)\n\n### Key Principles\n\n- **Shared Understanding**: Business and development teams use the same words\n- **Outside-In Development**: Start with what users see and experience\n- **Living Documentation**: Requirements stay current because they're also tests\n- **Three-Step Process**: Discovery → Formulation → Automation\n- **Concrete Examples**: Abstract requirements illustrated with specific scenarios\n- **Executable Specifications**: Tests that verify behavior\n\n## Methodology\n\n### Three-Step Iterative Process\n\n#### 1. Discovery\nCollaborative exploration using Example Mapping to:\n- Identify business rules\n- Generate concrete examples\n- Capture questions and edge cases\n- Validate scope\n- Build shared understanding\n\n#### 2. Formulation\nConvert examples to structured Gherkin scenarios:\n- Given-When-Then format\n- Declarative language\n- Scenario outlines for data-driven tests\n- Reusable steps\n- Clear tags and organization\n\n#### 3. Automation\nImplement executable specifications:\n- Step definitions\n- Test automation\n- Page object patterns\n- Test data management\n- Continuous execution\n\n## Process Workflow\n\n```\nDiscovery Workshop\n    ↓\n[Review Examples & Rules]\n    ↓\nGherkin Formulation\n    ↓\n[Review Scenarios]\n    ↓\nStep Definition Generation\n    ↓\n[Review Steps]\n    ↓\nTest Automation\n    ↓\nLiving Documentation\n    ↓\n[Final Review]\n```\n\n## Usage\n\n### Basic Usage\n\n```javascript\nimport { runProcess } from '@a5c-ai/babysitter-sdk';\n\nconst result = await runProcess('methodologies/bdd-specification-by-example', {\n  projectName: 'E-commerce Platform',\n  feature: 'Shopping cart checkout process',\n  stakeholders: ['Product Owner', 'Developer', 'QA', 'UX Designer'],\n  testFramework: 'cucumber',\n  generateTests: true,\n  createDocumentation: true\n});\n```\n\n### Input Parameters\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `projectName` | string | Yes | - | Project name |\n| `feature` | string | Yes | - | Feature to analyze |\n| `stakeholders` | array | No | `['Product Owner', 'Developer', 'QA']` | Stakeholder roles |\n| `testFramework` | string | No | `'cucumber'` | cucumber, specflow, behave, cypress |\n| `developmentPhase` | string | No | `'greenfield'` | greenfield or brownfield |\n| `generateTests` | boolean | No | `true` | Auto-generate test automation |\n| `createDocumentation` | boolean | No | `true` | Generate living documentation |\n| `existingFeatures` | array | No | `[]` | Existing feature context |\n| `existingScenarios` | array | No | `[]` | Existing scenarios to consider |\n| `existingSteps` | array | No | `[]` | Existing step definitions library |\n\n### Output Structure\n\n```javascript\n{\n  success: boolean,\n  projectName: string,\n  feature: string,\n  discovery: {\n    story: { title, description, businessValue, acceptanceCriteria },\n    rules: [{ id, description, rationale }],\n    examples: [{ id, ruleId, title, context, action, outcome, type }],\n    questions: [{ id, question, answer, priority }],\n    scope: { inScope, outOfScope }\n  },\n  gherkin: {\n    featureFile: string,\n    scenarios: [{ id, title, type, tags, given, when, then, examples }],\n    totalSteps: number,\n    uniqueSteps: [{ text, type, usageCount }]\n  },\n  scenarioAnalysis: {\n    qualityScore: number,\n    issues: [],\n    recommendations: [],\n    coverage: { examplesCovered, examplesTotal, coveragePercentage }\n  },\n  stepDefinitions: {\n    stepDefinitionsCode: string,\n    steps: [{ id, text, type, regex, functionName, parameters, complexity }],\n    newSteps: number,\n    reusedSteps: number\n  },\n  automation: {\n    stepImplementations: [],\n    testData: { testData, fixtures, factories },\n    execution: { total, passed, failed, pending, results }\n  },\n  documentation: {\n    featureDocumentation: string,\n    coverageReport: {},\n    behaviorCatalog: [],\n    traceability: {}\n  },\n  artifacts: {\n    discovery: 'artifacts/bdd/discovery/',\n    features: 'artifacts/bdd/features/',\n    stepDefinitions: 'artifacts/bdd/step-definitions/',\n    automation: 'artifacts/bdd/automation/',\n    documentation: 'artifacts/bdd/docs/'\n  }\n}\n```\n\n## Examples\n\n### Example 1: E-commerce Checkout\n\n```javascript\nconst result = await runProcess('methodologies/bdd-specification-by-example', {\n  projectName: 'ShopNow',\n  feature: 'Guest checkout with multiple payment methods',\n  stakeholders: ['Product Manager', 'Developer', 'QA', 'Payment Team'],\n  testFramework: 'cucumber',\n  developmentPhase: 'brownfield',\n  existingFeatures: ['user-authentication', 'shopping-cart']\n});\n```\n\n**Discovery Output**:\n- 8 business rules identified\n- 15 concrete examples (happy path, edge cases, errors)\n- 3 questions clarified\n- Clear scope boundaries\n\n**Gherkin Output**:\n- 15 scenarios (12 scenarios + 3 scenario outlines)\n- 45 total steps, 22 unique steps\n- Quality score: 92/100\n- Tags: @checkout, @payment, @guest, @smoke, @regression\n\n**Automation Output**:\n- 22 step definitions (15 new, 7 reused)\n- 3 page objects created\n- Test execution: 15/15 passing\n- Living documentation generated\n\n### Example 2: User Registration\n\n```javascript\nconst result = await runProcess('methodologies/bdd-specification-by-example', {\n  projectName: 'SocialApp',\n  feature: 'User registration with email verification',\n  testFramework: 'cypress',\n  generateTests: true,\n  createDocumentation: true\n});\n```\n\n**Discovery Output**:\n- 5 business rules\n- 12 examples covering various scenarios\n- Email validation rules\n- Password strength requirements\n- Rate limiting behavior\n\n**Gherkin Output**:\n```gherkin\nFeature: User Registration\n  As a new user\n  I want to create an account\n  So that I can access the platform\n\n  Background:\n    Given the registration page is displayed\n    And no user is currently logged in\n\n  Scenario: Successful registration with valid details\n    Given I am on the registration page\n    When I enter valid email \"user@example.com\"\n    And I enter strong password \"SecurePass123!\"\n    And I confirm the password\n    And I accept terms and conditions\n    And I click register button\n    Then I should see \"Verification email sent\"\n    And I should receive a verification email\n    And my account should be created in pending state\n\n  Scenario Outline: Registration fails with invalid email\n    Given I am on the registration page\n    When I enter email \"<email>\"\n    And I enter valid password details\n    And I click register button\n    Then I should see error \"<error>\"\n    And my account should not be created\n\n    Examples:\n      | email              | error                    |\n      | invalid.email      | Invalid email format     |\n      | user@              | Invalid email format     |\n      | @example.com       | Invalid email format     |\n      | existing@email.com | Email already registered |\n```\n\n### Example 3: API Feature\n\n```javascript\nconst result = await runProcess('methodologies/bdd-specification-by-example', {\n  projectName: 'Payment API',\n  feature: 'Process refund with validation',\n  testFramework: 'cucumber',\n  stakeholders: ['API Developer', 'QA', 'Business Analyst'],\n  generateTests: true\n});\n```\n\n**Discovery Output**:\n- API contract rules\n- Validation scenarios\n- Error handling examples\n- Idempotency requirements\n\n## Tasks\n\n### Discovery Workshop Task\n**Purpose**: Collaborative exploration using Example Mapping\n**Output**: Stories, rules, examples, questions, scope\n**Approach**: Multi-stakeholder perspective, concrete examples\n\n### Clarify Questions Task\n**Purpose**: Address open questions from discovery\n**Output**: Answers, additional examples, assumptions\n**Approach**: Domain expertise, consistency checking\n\n### Gherkin Formulation Task\n**Purpose**: Convert examples to Given-When-Then scenarios\n**Output**: Feature files, scenarios, step inventory\n**Approach**: Declarative language, reusable steps, best practices\n\n### Analyze Scenario Quality Task\n**Purpose**: Assess scenario quality and coverage\n**Output**: Quality score, issues, recommendations\n**Approach**: Best practices validation, coverage analysis\n\n### Step Definition Task\n**Purpose**: Generate step definition stubs\n**Output**: Step definitions code, regex patterns\n**Approach**: Framework-specific conventions, reusability\n\n### Analyze Step Reuse Task\n**Purpose**: Identify reusable steps and duplicates\n**Output**: Reuse metrics, recommendations\n**Approach**: Pattern matching, consolidation opportunities\n\n### Implement Step Task\n**Purpose**: Implement step with working code\n**Output**: Implementation code, page objects, helpers\n**Approach**: Testing patterns, error handling, idempotency\n\n### Generate Test Data Task\n**Purpose**: Create test data and fixtures\n**Output**: Test data sets, fixtures, factories\n**Approach**: Realistic data, boundary values, privacy\n\n### Execute Tests Task\n**Purpose**: Run automated tests\n**Output**: Execution results, pass/fail metrics\n**Approach**: Framework execution, result analysis\n\n### Generate Living Documentation Task\n**Purpose**: Create feature documentation from scenarios\n**Output**: Feature docs, coverage report, behavior catalog\n**Approach**: Stakeholder-readable, test-linked, visual\n\n### Generate Traceability Task\n**Purpose**: Link requirements to scenarios to tests\n**Output**: Traceability matrix, coverage gaps\n**Approach**: Bidirectional mapping, gap analysis\n\n## Integration Points\n\n### With Spec-Driven Development\nBDD provides detailed acceptance criteria that complement spec-driven development:\n```javascript\n// First: Create specification\nconst spec = await runProcess('methodologies/spec-driven-development', { ... });\n\n// Then: Add BDD scenarios for each user story\nfor (const story of spec.specification.userStories) {\n  const bdd = await runProcess('methodologies/bdd-specification-by-example', {\n    feature: story.title,\n    stakeholders: ['Product Owner', 'Developer', 'QA']\n  });\n}\n```\n\n### With Example Mapping\nUse Example Mapping methodology for discovery phase:\n```javascript\n// Example Mapping workshop\nconst mapping = await runProcess('methodologies/example-mapping', { ... });\n\n// Convert to BDD scenarios\nconst bdd = await runProcess('methodologies/bdd-specification-by-example', {\n  feature: mapping.story,\n  existingExamples: mapping.examples\n});\n```\n\n### With ATDD/TDD\nBDD scenarios drive test-driven development:\n```javascript\nconst bdd = await runProcess('methodologies/bdd-specification-by-example', {\n  generateTests: true\n});\n\n// Use scenarios for ATDD\nconst atdd = await runProcess('methodologies/atdd', {\n  acceptanceCriteria: bdd.gherkin.scenarios\n});\n```\n\n## Best Practices\n\n### Discovery Workshop\n1. Include diverse stakeholders (business, dev, QA, UX)\n2. Use Example Mapping format (story, rules, examples, questions)\n3. Focus on concrete examples, not abstract requirements\n4. Identify edge cases and error scenarios\n5. Time-box discussions (15-25 minutes per story)\n6. Capture questions immediately\n\n### Gherkin Writing\n1. Use declarative language (what, not how)\n2. Write scenarios from user perspective\n3. Keep scenarios independent and isolated\n4. One scenario = one behavior\n5. Use scenario outlines for data-driven tests\n6. Tag appropriately (@smoke, @regression, @slow)\n7. Make scenarios readable by non-technical stakeholders\n\n### Step Definitions\n1. Create reusable, focused steps\n2. Use regex for parameter capture\n3. Follow Page Object Model pattern\n4. Keep step implementations simple\n5. Extract complex logic to helper functions\n6. Make steps idempotent\n7. Add meaningful assertion messages\n\n### Test Automation\n1. Run tests frequently (CI/CD)\n2. Keep tests fast and reliable\n3. Isolate test data\n4. Clean up after tests\n5. Handle async operations properly\n6. Make tests deterministic\n7. Monitor for flaky tests\n\n### Living Documentation\n1. Keep documentation in sync with tests\n2. Make it accessible to all stakeholders\n3. Include visual diagrams\n4. Link to test results\n5. Highlight test status\n6. Update automatically\n7. Version with code\n\n## Test Frameworks\n\n### Cucumber (JavaScript/TypeScript)\n```javascript\nconst result = await runProcess('methodologies/bdd-specification-by-example', {\n  testFramework: 'cucumber',\n  // Generates .feature files and .js step definitions\n});\n```\n\n### SpecFlow (.NET/C#)\n```javascript\nconst result = await runProcess('methodologies/bdd-specification-by-example', {\n  testFramework: 'specflow',\n  // Generates .feature files and .cs step definitions\n});\n```\n\n### Behave (Python)\n```javascript\nconst result = await runProcess('methodologies/bdd-specification-by-example', {\n  testFramework: 'behave',\n  // Generates .feature files and .py step definitions\n});\n```\n\n### Cypress (JavaScript)\n```javascript\nconst result = await runProcess('methodologies/bdd-specification-by-example', {\n  testFramework: 'cypress',\n  // Generates .feature files and cypress test specs\n});\n```\n\n## Common Patterns\n\n### Outside-In Development\nStart with acceptance tests (outside) and work inward:\n1. Write feature/scenario (acceptance test)\n2. Run test (red)\n3. Write unit tests for components (TDD)\n4. Implement components\n5. Integration\n6. Acceptance test passes (green)\n\n### Example Mapping Workshop\nVisual collaborative technique:\n- Story (yellow card)\n- Rules (blue cards)\n- Examples (green cards)\n- Questions (red cards)\n\n### Scenario Structure\n```gherkin\nScenario: <Clear, concise title from user perspective>\n  Given <Context/Preconditions>\n  And <More context>\n  When <Action/Event>\n  And <More actions>\n  Then <Expected outcome>\n  And <More expectations>\n```\n\n### Scenario Outline Pattern\n```gherkin\nScenario Outline: <Title with parameters>\n  Given <context with <parameter>>\n  When <action with <parameter>>\n  Then <outcome with <parameter>>\n\n  Examples:\n    | parameter | expected |\n    | value1    | result1  |\n    | value2    | result2  |\n```\n\n## Quality Metrics\n\nThe process tracks quality metrics:\n\n- **Scenario Quality Score**: 0-100 based on best practices\n- **Example Coverage**: % of discovery examples covered by scenarios\n- **Step Reusability**: % of steps reused vs. total steps\n- **Test Success Rate**: % of passing scenarios\n- **Traceability Completeness**: % of rules linked to tested scenarios\n- **Documentation Freshness**: Last update vs. code changes\n\n## Artifacts Generated\n\n### Discovery Phase\n- `artifacts/bdd/discovery/example-map.md` - Visual example map\n- `artifacts/bdd/discovery/rules.json` - Business rules\n- `artifacts/bdd/discovery/questions.json` - Questions and answers\n\n### Formulation Phase\n- `artifacts/bdd/features/feature.feature` - Gherkin feature file\n- `artifacts/bdd/analysis/scenario-quality.md` - Quality analysis\n\n### Automation Phase\n- `artifacts/bdd/step-definitions/steps.*` - Step definitions\n- `artifacts/bdd/automation/page-objects/` - Page object models\n- `artifacts/bdd/automation/test-data/` - Test data and fixtures\n- `artifacts/bdd/automation/test-report.html` - Test execution report\n\n### Documentation Phase\n- `artifacts/bdd/docs/feature-documentation.md` - Living documentation\n- `artifacts/bdd/docs/traceability-matrix.md` - Requirements traceability\n- `artifacts/bdd/docs/coverage-report.md` - Test coverage analysis\n\n## References\n\n### Official Resources\n- [Cucumber BDD Guide](https://cucumber.io/docs/bdd/)\n- [Cucumber Documentation](https://cucumber.io/docs/cucumber/)\n- [SpecFlow Documentation](https://specflow.org/documentation/)\n- [Behave Documentation](https://behave.readthedocs.io/)\n\n### Books\n- **\"Specification by Example\"** by Gojko Adzic\n- **\"The Cucumber Book\"** by Matt Wynne & Aslak Hellesoy\n- **\"BDD in Action\"** by John Ferguson Smart\n- **\"Discovery: Explore behaviour using examples\"** by Gáspár Nagy & Seb Rose\n\n### Articles & Guides\n- [BDD on Wikipedia](https://en.wikipedia.org/wiki/Behavior-driven_development)\n- [Monday.com BDD Guide 2026](https://monday.com/blog/rnd/behavior-driven-development/)\n- [BrainHub BDD 2025](https://brainhub.eu/library/behavior-driven-development)\n- [Dan North's Blog - Introducing BDD](https://dannorth.net/introducing-bdd/)\n- [Gojko Adzic - Specification by Example](https://gojko.net/books/specification-by-example/)\n\n### Tools\n- [Cucumber](https://cucumber.io/) - BDD framework for multiple languages\n- [SpecFlow](https://specflow.org/) - BDD for .NET\n- [Behave](https://behave.readthedocs.io/) - BDD for Python\n- [Cypress Cucumber Preprocessor](https://github.com/badeball/cypress-cucumber-preprocessor) - Gherkin for Cypress\n- [Example Mapping](https://cucumber.io/blog/bdd/example-mapping-introduction/) - Discovery workshop technique\n\n## Troubleshooting\n\n### Low Quality Score\n- Review scenario independence\n- Check for imperative language\n- Ensure proper Given-When-Then structure\n- Verify stakeholder readability\n\n### Poor Step Reusability\n- Make steps more generic\n- Extract common patterns\n- Use proper parameterization\n- Review step naming conventions\n\n### Failing Tests\n- Check test data validity\n- Verify environment setup\n- Review async handling\n- Check for test dependencies\n\n### Documentation Out of Sync\n- Run documentation generation after changes\n- Set up automated regeneration\n- Review CI/CD integration\n- Check artifact paths\n\n## License\n\nPart of the Babysitter SDK orchestration framework.\n",
    "documents": [
      "specialization:bdd-specification-by-example"
    ]
  },
  "outgoingEdges": [
    {
      "from": "page:library-bdd-specification-by-example",
      "to": "specialization:bdd-specification-by-example",
      "kind": "documents"
    }
  ],
  "incomingEdges": [
    {
      "from": "page:index",
      "to": "page:library-bdd-specification-by-example",
      "kind": "contains_page"
    }
  ]
}