git clone https://github.com/JasonTeixeira/BDD-Cucumber-Framework
# See repo README for setup
# Typical patterns:
# - npm test / npm run test
# - pytest -q
# - make test

Built a Behavior-Driven Development (BDD) framework using Cucumber and Gherkin that enabled non-technical stakeholders to read, understand, and contribute to test scenarios. Improved collaboration between QA, development, and product teams, resulting in 40% more test coverage and 65% fewer requirements misunderstandings.

• Coverage measured by mapping acceptance criteria → Gherkin scenarios executed in CI.
• Misunderstandings measured via reduced UAT rework/issues after scenario signoff.
• Evidence: Allure-style reports + CI runs linked in Proof.

When I joined the healthcare tech company, they were building a complex patient management system with strict regulatory requirements. The team struggled with:

Critical Stakeholders:

• Product Managers - Defining acceptance criteria
• Business Analysts - Writing requirements documents
• Compliance Officers - Ensuring HIPAA compliance
• QA Engineers - Writing and executing tests
• Developers - Implementing features

Complex Business Rules:

• Patient eligibility verification
• Insurance claim processing
• Prescription validation
• Appointment scheduling
• Medical records access control
• Billing calculations
• Compliance reporting

Communication between technical and non-technical team members was broken:

• Requirements unclear - Developers building wrong features
• Tests disconnected from requirements - QA testing different scenarios than BA described
• No shared understanding - Everyone interpreted requirements differently
• Late bug discovery - Compliance issues found in UAT, not testing
• Manual regression - Business logic tests done manually
• Stakeholder disconnect - Product owners couldn't review test coverage
• Documentation lag - Specs outdated the moment they're written
• Compliance risk - Hard to prove all requirements tested

The communication gaps were expensive:

• $500K in rework - Features built wrong, had to rebuild
• 3-month delays - Compliance issues blocking releases
• 60% requirements change - Misunderstandings discovered late
• Stakeholder frustration - "This isn't what I asked for"
• Audit failures - Can't prove all rules tested
• Technical debt - Tests and docs out of sync
• Team morale - Finger-pointing between teams

The team had tried various approaches:

• Detailed specs - Nobody read 100-page documents
• User stories - Still too technical for business
• Test cases in Excel - Disconnected from automation
• Code comments - Business people can't read code
• Regular meetings - Information lost in translation

We needed a shared language everyone could understand and use.

I designed a BDD framework with these principles:

1. Living Documentation - Tests ARE the specification
2. Ubiquitous Language - Same terms everywhere
3. Executable Specifications - Requirements that run
4. Three Amigos - QA, Dev, BA write scenarios together
5. Outside-In Development - Start with behavior, not implementation

This provided:

• Shared understanding - Everyone reads the same thing
• Automated tests - Scenarios execute as tests
• Living documentation - Always up-to-date
• Early validation - Catch misunderstandings before coding

Why Cucumber?

• Gherkin syntax (Given/When/Then) is business-readable
• Widely adopted, great community
• Multi-language support (we used Python)
• Excellent reporting
• IDE plugins for non-technical users

Why Gherkin?

• Plain English (or any language)
• Business-focused syntax
• Reusable steps
• Easy for stakeholders to read and write
• Maps to test automation

Why Python + behave?

• Team's language
• Great Cucumber implementation (behave)
• Easy step definition writing
• Good IDE support
• Integrates with existing tests

Why Allure Reports?

• Beautiful HTML reports
• Shows Gherkin scenarios
• Test history and trends
• Stakeholder-friendly
• Screenshots and attachments

┌─────────────────────────────────────────────┐
│    Gherkin Feature Files (.feature)         │
│    - Plain English scenarios                │
│    - Readable by everyone                   │
│    - Version controlled                     │
└──────────────────┬──────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────┐
│         Step Definitions (Python)           │
│    - Map Gherkin to code                    │
│    - Reusable steps                         │
│    - Business logic abstraction             │
└──────────────────┬──────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────┐
│         Page Objects / API Clients          │
│    - Implementation details                 │
│    - Technical interactions                 │
│    - Hidden from business layer             │
└──────────────────┬──────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────┐
│         Application Under Test              │
│    - Web UI, APIs, Database                 │
└─────────────────────────────────────────────┘

# features/patient_eligibility.feature
Feature: Patient Eligibility Verification
  As a healthcare provider
  I want to verify patient insurance eligibility
  So that I can confirm coverage before providing services

  Background:
    Given I am logged in as a provider
    And I am on the patient eligibility page

  Scenario: Verify active insurance coverage
    Given a patient "John Smith" with insurance ID "ABC123456"
    And the patient has active coverage with "Blue Cross"
    When I check eligibility for "annual physical"
    Then the eligibility status should be "Approved"
    And the coverage percentage should be "100%"
    And the copay amount should be "$0"

  Scenario: Verify coverage with copay
    Given a patient "Jane Doe" with insurance ID "XYZ789012"
    And the patient has active coverage with "Aetna"
    When I check eligibility for "specialist visit"
    Then the eligibility status should be "Approved"
    And the coverage percentage should be "80%"
    And the copay amount should be "$40"

  Scenario: Handle expired insurance
    Given a patient "Bob Jones" with insurance ID "DEF345678"
    And the patient's insurance expired on "2023-12-31"
    When I check eligibility for "office visit"
    Then the eligibility status should be "Denied"
    And I should see error "Insurance coverage has expired"
    And I should see recommendation "Contact patient to update insurance"

  Scenario Outline: Verify different service types
    Given a patient with insurance ID "<insurance_id>"
    When I check eligibility for "<service_type>"
    Then the eligibility status should be "<status>"
    And the copay amount should be "<copay>"

    Examples:
      | insurance_id | service_type    | status   | copay |
      | ABC123456    | preventive care | Approved | $0    |
      | ABC123456    | emergency care  | Approved | $200  |
      | ABC123456    | surgery         | Approved | $500  |
      | XYZ789012    | lab work        | Approved | $20   |

# features/steps/eligibility_steps.py
from behave import given, when, then
from pages.eligibility_page import EligibilityPage
from api.insurance_api import InsuranceAPI

@given('I am logged in as a provider')
def step_login_provider(context):
    """Login as healthcare provider"""
    context.login_page.login(
        username="provider@hospital.com",
        password="secure_password"
    )
    assert context.login_page.is_logged_in()

@given('I am on the patient eligibility page')
def step_navigate_eligibility(context):
    """Navigate to eligibility page"""
    context.eligibility_page = EligibilityPage(context.driver)
    context.eligibility_page.navigate()

@given('a patient "{name}" with insurance ID "{insurance_id}"')
def step_create_patient(context, name, insurance_id):
    """Create test patient with insurance"""
    context.patient = {
        "name": name,
        "insurance_id": insurance_id
    }
    # Store for use in later steps
    context.eligibility_page.enter_insurance_id(insurance_id)

@given('the patient has active coverage with "{provider}"')
def step_active_coverage(context, provider):
    """Set up active insurance coverage"""
    # Use API to configure test data
    context.insurance_api = InsuranceAPI()
    context.insurance_api.create_coverage(
        insurance_id=context.patient["insurance_id"],
        provider=provider,
        status="active",
        effective_date="2024-01-01",
        end_date="2024-12-31"
    )

@given('the patient's insurance expired on "{date}"')
def step_expired_coverage(context, date):
    """Set up expired insurance"""
    context.insurance_api.create_coverage(
        insurance_id=context.patient["insurance_id"],
        status="expired",
        end_date=date
    )

@when('I check eligibility for "{service_type}"')
def step_check_eligibility(context, service_type):
    """Perform eligibility check"""
    context.result = context.eligibility_page.check_eligibility(
        service_type=service_type
    )

@then('the eligibility status should be "{expected_status}"')
def step_verify_status(context, expected_status):
    """Verify eligibility status"""
    actual_status = context.result.get_status()
    assert actual_status == expected_status, \
        f"Expected status '{expected_status}', got '{actual_status}'"

@then('the coverage percentage should be "{percentage}"')
def step_verify_coverage(context, percentage):
    """Verify coverage percentage"""
    actual = context.result.get_coverage_percentage()
    assert actual == percentage, \
        f"Expected {percentage} coverage, got {actual}"

@then('the copay amount should be "{amount}"')
def step_verify_copay(context, amount):
    """Verify copay amount"""
    actual = context.result.get_copay()
    assert actual == amount, \
        f"Expected copay {amount}, got {actual}"

@then('I should see error "{error_message}"')
def step_verify_error(context, error_message):
    """Verify error message displayed"""
    errors = context.result.get_errors()
    assert error_message in errors, \
        f"Expected error '{error_message}' not found in {errors}"

@then('I should see recommendation "{recommendation}"')
def step_verify_recommendation(context, recommendation):
    """Verify recommendation shown"""
    recommendations = context.result.get_recommendations()
    assert recommendation in recommendations

# features/steps/common_steps.py
"""Common steps used across features"""
from behave import given, when, then
import time

@given('I wait {seconds:d} seconds')
@when('I wait {seconds:d} seconds')
def step_wait(context, seconds):
    """Wait for specified seconds"""
    time.sleep(seconds)

@given('the system date is "{date}"')
def step_set_system_date(context, date):
    """Mock system date for testing"""
    context.time_machine.set_date(date)

@then('I should see "{text}" on the page')
def step_verify_text_visible(context, text):
    """Verify text appears on page"""
    assert context.current_page.contains_text(text)

@then('I should not see "{text}" on the page')
def step_verify_text_not_visible(context, text):
    """Verify text does not appear"""
    assert not context.current_page.contains_text(text)

@when('I click "{button_name}"')
def step_click_button(context, button_name):
    """Click button by name"""
    context.current_page.click_button(button_name)

@when('I enter "{value}" in "{field_name}"')
def step_fill_field(context, value, field_name):
    """Fill form field"""
    context.current_page.fill_field(field_name, value)

# features/environment.py
"""Behave environment configuration"""
from selenium import webdriver
from pages.login_page import LoginPage
import allure

def before_all(context):
    """Setup before all tests"""
    # Configure test environment
    context.base_url = "https://test.hospital.com"
    context.api_url = "https://api.test.hospital.com"

def before_feature(context, feature):
    """Setup before each feature"""
    # Add feature info to report
    allure.dynamic.feature(feature.name)

def before_scenario(context, scenario):
    """Setup before each scenario"""
    # Start browser
    context.driver = webdriver.Chrome()
    context.driver.maximize_window()
    context.driver.implicitly_wait(10)
    
    # Initialize pages
    context.login_page = LoginPage(context.driver)
    context.current_page = context.login_page
    
    # Add scenario info to report
    allure.dynamic.title(scenario.name)
    allure.dynamic.description(scenario.description)

def after_scenario(context, scenario):
    """Cleanup after each scenario"""
    # Take screenshot on failure
    if scenario.status == "failed":
        screenshot = context.driver.get_screenshot_as_png()
        allure.attach(
            screenshot,
            name=f"failure_{scenario.name}",
            attachment_type=allure.attachment_type.PNG
        )
    
    # Close browser
    context.driver.quit()

def after_step(context, step):
    """After each step"""
    # Take screenshot for report
    if hasattr(context, 'driver'):
        screenshot = context.driver.get_screenshot_as_png()
        allure.attach(
            screenshot,
            name=f"step_{step.name}",
            attachment_type=allure.attachment_type.PNG
        )

# Run all features
behave features/

# Run specific feature
behave features/patient_eligibility.feature

# Run with tags
behave --tags=@smoke
behave --tags=@critical --tags=~@wip

# Run with Allure report
behave -f allure_behave.formatter:AllureFormatter \
  -o allure-results/

# Generate and open report
allure generate allure-results/ -o allure-report/
allure open allure-report/

# behave.ini
[behave]
show_skipped = false
show_timings = true
format = progress
color = true
logging_level = INFO

[behave.formatters]
json = behave.formatter.json:JSONFormatter
html = behave_html_formatter:HTMLFormatter
allure = allure_behave.formatter:AllureFormatter

[behave.userdata]
browser = chrome
headless = false
screenshots = true

Collaboration Improvements:

• Requirements misunderstandings: 65% reduction
• BA/QA/Dev alignment: From 50% → 95%
• Feature rework: $500K → $50K (90% reduction)
• Acceptance criteria clarity: +40 points (stakeholder survey)

Test Coverage Improvements:

• Business rule coverage: 55% → 95% (+40 points)
• Compliance scenarios: 30 → 120 (4x increase)
• Edge cases documented: 50 → 200 (4x increase)
• Stakeholder-reviewed scenarios: 0% → 90%

Quality Improvements:

• Compliance audit failures: 5 → 0 (100% elimination)
• Production defects: 25/quarter → 8/quarter (68% reduction)
• Requirements defects: 40% → 10% (75% reduction)
• UAT issues: 60 → 15 (75% reduction)

Team Efficiency:

• Requirements sign-off time: 5 days → 1 day (80% faster)
• Test creation time: Same (business writes scenarios)
• Documentation maintenance: 10 hours/week → 0 (automated)
• Onboarding time: 3 weeks → 1 week (scenarios as docs)

Product Managers:

• 8/10 PMs now write Gherkin scenarios
• Review and approve test coverage
• Contribute edge cases

Business Analysts:

• Write acceptance criteria in Gherkin
• Scenarios become living specs
• No more separate test case docs

Compliance Officers:

• Can verify all regulations tested
• Read scenarios for audit evidence
• Suggest additional compliance tests

Developers:

• Use scenarios to understand requirements
• Implement features to match scenarios
• Run scenarios as unit test supplements

"I can finally read and understand what QA is testing. I've even started writing scenarios myself!" — Product Manager

"Our compliance audits are so much easier now. I can show auditors the Gherkin scenarios and they understand immediately." — Compliance Officer

"The 'Three Amigos' sessions transformed how we work. We catch misunderstandings before any code is written." — Lead Developer

1. Three Amigos sessions - QA, Dev, BA writing scenarios together
2. Living documentation - Scenarios always up-to-date
3. Business language - Stakeholders can read and contribute
4. Reusable steps - Reduced duplication, easier maintenance
5. Allure reports - Beautiful, stakeholder-friendly

1. Start simpler - Tried too many features at once
2. Better step naming - Some steps too technical
3. More training - Stakeholders needed more Gherkin practice
4. Step library sooner - Reusability came late
5. Version control education - Non-tech users struggled with Git

1. BDD is about collaboration, not tools
2. Business language is essential
3. Living documentation beats static docs
4. Invest in stakeholder training
5. Keep scenarios business-focused

• Add API-level BDD tests
• Integrate with requirements management tool
• Add performance BDD scenarios
• Create scenario templates for common patterns
• Add AI-powered scenario suggestions

• Some technical scenarios still needed
• Git workflow challenging for non-technical users
• Step maintenance requires discipline
• Not all features suit BDD approach

Core Technologies:

• Python 3.9+
• behave (Python Cucumber)
• Gherkin
• pytest (integration)

Supporting Tools:

• Allure Framework (reporting)
• Selenium WebDriver
• Requests (API testing)
• PyCharm with Gherkin plugin

CI/CD:

• GitHub Actions
• Docker
• Allure Report hosting

• BDD Best Practices
• Writing Effective Gherkin Scenarios

• Selenium Python Framework
• API Test Automation Framework

---

This framework includes templates and best practices.

GitHub Repository: BDD-Cucumber-Framework

---

Impressed by this project? I'm available for:

• Full-time QA/BDD roles
• Consulting engagements
• BDD training & workshops
• Team coaching

Get in Touch | View Resume | More Projects