BDD: From Requirements to Automation

Feature: Cash Withdrawal
  As a customer
  I want to withdraw cash from an ATM
  So that I can access my money

  Background:
    Given the customer has a valid account
    And the ATM has sufficient cash

  Scenario: Successful withdrawal within balance
    Given the customer has a balance of $100
    When the customer requests $50
    Then the cash should be dispensed
    And the balance should be $50
    And a receipt should be provided

  Scenario: Insufficient funds
    Given the customer has a balance of $30
    When the customer requests $50
    Then the withdrawal should be rejected
    And an error message "Insufficient funds" should be displayed
    And no cash should be dispensed

# Bad - Imperative (how)
Scenario: User registration
  Given I am on the homepage
  When I click "Sign Up"
  And I fill in "email" with "user@example.com"
  And I fill in "password" with "Pass123!"
  And I fill in "confirm password" with "Pass123!"
  And I click "Create Account"
  Then I should see "Welcome"

# Good - Declarative (what)
Scenario: User registration
  Given I am a new visitor
  When I register with valid credentials
  Then I should be logged in
  And I should see a welcome message

# Bad - Repetitive scenarios
Scenario: Login with invalid password
  Given a user exists with email "user@example.com"
  When I login with email "user@example.com" and password "wrong"
  Then I should see an error "Invalid credentials"

Scenario: Login with invalid email
  Given a user exists with email "user@example.com"
  When I login with email "wrong@example.com" and password "Pass123!"
  Then I should see an error "Invalid credentials"

# Good - Scenario Outline
Scenario Outline: Login validation
  Given a user exists with email "user@example.com" and password "Pass123!"
  When I login with email "<email>" and password "<password>"
  Then I should see an error "<error>"

  Examples:
    | email              | password  | error               |
    | user@example.com   | wrong     | Invalid credentials |
    | wrong@example.com  | Pass123!  | Invalid credentials |
    | user@example.com   | Pass123   | Invalid credentials |
    |                    | Pass123!  | Email required      |
    | user@example.com   |           | Password required   |

# Background runs before EACH scenario
Feature: Shopping Cart

  Background:
    Given I am logged in as "customer@example.com"
    And my cart is empty

  Scenario: Add item to cart
    When I add "iPhone 15" to cart
    Then my cart should contain 1 item

  Scenario: Add multiple items
    When I add "iPhone 15" to cart
    And I add "AirPods Pro" to cart
    Then my cart should contain 2 items

# Bad - Testing multiple behaviors
Scenario: User workflow
  Given I am logged in
  When I view my profile
  Then I should see my name
  When I edit my profile
  And I change my name to "New Name"
  Then my name should be updated
  When I logout
  Then I should be logged out

# Good - Separate scenarios
Scenario: View profile
  Given I am logged in
  When I view my profile
  Then I should see my current information

Scenario: Update profile name
  Given I am logged in
  And I am on my profile page
  When I change my name to "New Name"
  Then my profile should show "New Name"

@critical @smoke
Feature: Authentication

  @fast
  Scenario: Login with valid credentials
    Given a user exists
    When I login with valid credentials
    Then I should be logged in

  @slow @integration
  Scenario: Login with SSO
    Given SSO is configured
    When I login via Google
    Then I should be logged in

  @wip
  Scenario: Two-factor authentication
    # Work in progress

cucumber --tags "@smoke and not @wip"
cucumber --tags "@critical or @smoke"

public class AuthenticationSteps {

    private User user;
    private LoginPage loginPage;
    private DashboardPage dashboardPage;
    private String errorMessage;

    @Given("a user exists with email {string} and password {string}")
    public void aUserExistsWithEmailAndPassword(String email, String password) {
        user = UserFactory.createUser(email, password);
        userRepository.save(user);
    }

    @Given("I am logged in as {string}")
    public void iAmLoggedInAs(String email) {
        user = userRepository.findByEmail(email);
        sessionManager.login(user);
    }

    @When("I login with email {string} and password {string}")
    public void iLoginWithEmailAndPassword(String email, String password) {
        loginPage = new LoginPage(driver);
        try {
            dashboardPage = loginPage.login(email, password);
        } catch (LoginException e) {
            errorMessage = e.getMessage();
        }
    }

    @When("I login with valid credentials")
    public void iLoginWithValidCredentials() {
        iLoginWithEmailAndPassword(user.getEmail(), user.getPassword());
    }

    @Then("I should be logged in")
    public void iShouldBeLoggedIn() {
        assertThat(dashboardPage).isNotNull();
        assertThat(sessionManager.isLoggedIn()).isTrue();
    }

    @Then("I should see an error {string}")
    public void iShouldSeeAnError(String expectedError) {
        assertThat(errorMessage).contains(expectedError);
    }

    @After
    public void cleanup() {
        if (user != null) {
            userRepository.delete(user);
        }
        sessionManager.logout();
    }
}

@CucumberContextConfiguration
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
public class CucumberSpringConfiguration (as discussed in [Serenity BDD Integration: Living Documentation and Advanced Test Reporting](/blog/serenity-bdd-integration)) {

    @LocalServerPort
    private int port;

    @Before
    public void setup() {
        RestAssured.port = port;
    }
}

public class StepDefinitions {

    @Autowired
    private UserService userService;

    @Autowired
    private TestRestTemplate restTemplate;

    // Steps can now use autowired dependencies
}

Scenario: Register user with profile
  When I register with the following details:
    | email              | name       | age | city      |
    | john@example.com   | John Doe   | 30  | New York  |
  Then the user should be created

@When("I register with the following details:")
public void iRegisterWithTheFollowingDetails(DataTable dataTable) {
    Map<String, String> data = dataTable.asMap(String.class, String.class);

    User user = User.builder()
        .email(data.get("email"))
        .name(data.get("name"))
        .age(Integer.parseInt(data.get("age")))
        .city(data.get("city"))
        .build();

    registrationService.register(user);
}

// Or with list of objects
@When("I register multiple users:")
public void iRegisterMultipleUsers(DataTable dataTable) {
    List<User> users = dataTable.asList(User.class);
    users.forEach(registrationService::register);
}

// features/support/world.js
const { setWorldConstructor, Before, After } = require('@cucumber/cucumber');
const { chromium } = require('playwright');

class CustomWorld {
  async init() {
    this.browser = await chromium.launch();
    this.context = await this.browser.newContext();
    this.page = await this.context.newPage();
  }

  async cleanup() {
    await this.page?.close();
    await this.context?.close();
    await this.browser?.close();
  }
}

setWorldConstructor(CustomWorld);

Before(async function() {
  await this.init();
});

After(async function() {
  await this.cleanup();
});

// features/step_definitions/authentication.steps.js
const { Given, When, Then } = require('@cucumber/cucumber');
const { expect } = require('@playwright/test');

Given('a user exists with email {string}', async function(email) {
  this.user = await createUser({ email, password: 'Test123!' });
});

When('I login with email {string} and password {string}',
  async function(email, password) {
    await this.page.goto('http://localhost:3000/login');
    await this.page.fill('[name="email"]', email);
    await this.page.fill('[name="password"]', password);
    await this.page.click('button[type="submit"]');
  }
);

Then('I should be logged in', async function() {
  await this.page.waitForURL('**/dashboard');
  const userMenu = await this.page.locator('[data-testid="user-menu"]');
  await expect(userMenu).toBeVisible();
});

# Features/Authentication.feature
Feature: User Authentication
  As a user
  I want to securely access my account
  So that I can manage my data

  Scenario: Login with valid credentials
    Given a user exists with email "user@example.com"
    When I login with valid credentials
    Then I should be redirected to the dashboard
    And I should see a welcome message

// StepDefinitions/AuthenticationSteps.cs
[Binding]
public class AuthenticationSteps
{
    private readonly ScenarioContext _scenarioContext;
    private readonly IUserService _userService;
    private readonly LoginPage _loginPage;
    private User _user;
    private string _welcomeMessage;

    public AuthenticationSteps(
        ScenarioContext scenarioContext,
        IUserService userService,
        LoginPage loginPage)
    {
        _scenarioContext = scenarioContext;
        _userService = userService;
        _loginPage = loginPage;
    }

    [Given(@"a user exists with email ""(.*)""")]
    public async Task GivenAUserExistsWithEmail(string email)
    {
        _user = await _userService.CreateUserAsync(new User
        {
            Email = email,
            Password = "Test123!",
            Name = "Test User"
        });

        _scenarioContext["User"] = _user;
    }

    [When(@"I login with valid credentials")]
    public async Task WhenILoginWithValidCredentials()
    {
        var user = _scenarioContext.Get<User>("User");
        await _loginPage.LoginAsync(user.Email, "Test123!");
    }

    [Then(@"I should be redirected to the dashboard")]
    public void ThenIShouldBeRedirectedToTheDashboard()
    {
        var currentUrl = _loginPage.Driver.Url;
        currentUrl.Should().Contain("/dashboard");
    }

    [Then(@"I should see a welcome message")]
    public void ThenIShouldSeeAWelcomeMessage()
    {
        _welcomeMessage = _loginPage.GetWelcomeMessage();
        _welcomeMessage.Should().Contain("Welcome");
    }

    [AfterScenario]
    public async Task Cleanup()
    {
        if (_user != null)
        {
            await _userService.DeleteUserAsync(_user.Id);
        }
    }
}

Scenario: Create order with multiple items
  When I create an order with items:
    | Product     | Quantity | Price |
    | iPhone 15   | 1        | 999   |
    | AirPods Pro | 2        | 249   |
  Then the order total should be $1497

[When(@"I create an order with items:")]
public void WhenICreateAnOrderWithItems(Table table)
{
    var items = table.CreateSet<OrderItem>();

    _order = new Order
    {
        CustomerId = _customer.Id,
        Items = items.ToList()
    };

    _orderService.CreateOrder(_order);
}

public class OrderItem
{
    public string Product { get; set; }
    public int Quantity { get; set; }
    public decimal Price { get; set; }
}

# features/authentication.feature
Feature: User Authentication

  Background:
    Given the application is running

  Scenario: Successful login
    Given a user exists with email "user@example.com"
    When I login with email "user@example.com" and password "Test123!"
    Then I should be logged in
    And I should see my dashboard

# features/steps/authentication_steps.py
from behave import given, when, then
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC

@given('the application is running')
def step_app_running(context):
    context.driver.get('http://localhost:3000')

@given('a user exists with email "{email}"')
def step_user_exists(context, email):
    context.user = create_user(
        email=email,
        password='Test123!',
        name='Test User'
    )
    context.users_to_cleanup.append(context.user.id)

@when('I login with email "{email}" and password "{password}"')
def step_login(context, email, password):
    context.driver.get('http://localhost:3000/login')

    email_field = context.driver.find_element(By.NAME, 'email')
    password_field = context.driver.find_element(By.NAME, 'password')
    submit_button = context.driver.find_element(By.CSS_SELECTOR, 'button[type="submit"]')

    email_field.send_keys(email)
    password_field.send_keys(password)
    submit_button.click()

@then('I should be logged in')
def step_should_be_logged_in(context):
    wait = WebDriverWait(context.driver, 10)
    wait.until(EC.url_contains('/dashboard'))

@then('I should see my dashboard')
def step_see_dashboard(context):
    wait = WebDriverWait(context.driver, 10)
    dashboard = wait.until(
        EC.presence_of_element_located((By.ID, 'dashboard'))
    )
    assert dashboard.is_displayed()

# features/environment.py
from selenium import webdriver
from selenium.webdriver.chrome.options import Options

def before_all(context):
    """Runs once before all features"""
    context.config = load_config()

def before_feature(context, feature):
    """Runs before each feature"""
    if 'webdriver' in feature.tags:
        chrome_options = Options()
        chrome_options.add_argument('--headless')
        context.driver = webdriver.Chrome(options=chrome_options)

def before_scenario(context, scenario):
    """Runs before each scenario"""
    context.users_to_cleanup = []

def after_scenario(context, scenario):
    """Runs after each scenario"""
    # Cleanup test data
    for user_id in context.users_to_cleanup:
        delete_user(user_id)

    # Screenshot on failure
    if scenario.status == 'failed' and hasattr(context, 'driver'):
        screenshot_name = f"screenshots/{scenario.name}.png"
        context.driver.save_screenshot(screenshot_name)

def after_feature(context, feature):
    """Runs after each feature"""
    if hasattr(context, 'driver'):
        context.driver.quit()

Scenario: Register multiple users
  When I register users:
    | name       | email              | role  |
    | John Doe   | john@example.com   | admin |
    | Jane Smith | jane@example.com   | user  |
  Then both users should be created

@when('I register users:')
def step_register_users(context):
    for row in context.table:
        user = create_user(
            name=row['name'],
            email=row['email'],
            role=row['role']
        )
        context.users_to_cleanup.append(user.id)

# Generate Cucumber JSON
mvn test -Dcucumber.plugin="json:target/cucumber.json"

# Generate HTML report
npx cucumber-html-reporter \
  --jsonFile=target/cucumber.json \
  --output=target/cucumber-report.html

<!-- pom.xml -->
<dependency>
    <groupId>io.qameta.allure</groupId>
    <artifactId>allure-cucumber7-jvm</artifactId>
</dependency>

# Run tests with Allure
mvn test -Dcucumber.plugin="io.qameta.allure.cucumber7jvm.AllureCucumber7Jvm"

# Generate and serve report
allure serve target/allure-results

# generate_docs.py
import json
from pathlib import Path

def generate_feature_docs(cucumber_json_path):
    with open(cucumber_json_path) as f:
        features = json.load(f)

    docs = ["# Test Scenarios Documentation\n"]

    for feature in features:
        docs.append(f"## {feature['name']}\n")
        docs.append(f"{feature['description']}\n")

        for element in feature['elements']:
            status = "✅" if all(s['result']['status'] == 'passed'
                               for s in element['steps']) else "❌"

            docs.append(f"### {status} {element['name']}\n")

            for step in element['steps']:
                step_status = "✓" if step['result']['status'] == 'passed' else "✗"
                docs.append(f"- {step_status} {step['keyword']}{step['name']}\n")

            docs.append("\n")

    Path('documentation.md').write_text(''.join(docs))

# Usage
generate_feature_docs('target/cucumber.json')

from atlassian import Confluence

def publish_to_confluence(feature_files, confluence_space, confluence_page):
    confluence = Confluence(
        url='https://your-instance.atlassian.net',
        username='your-email@example.com',
        password='your-api-token'
    )

    content = generate_html_from_features(feature_files)

    confluence.update_page(
        page_id=confluence_page,
        title='Automated Test Scenarios',
        body=content
    )

# .github/workflows/bdd-tests.yml
name: BDD Tests

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@v3

      - name: Set up JDK 17
        uses: actions/setup-java@v3
        with:
          java-version: '17'
          distribution: 'temurin'

      - name: Cache Maven packages
        uses: actions/cache@v3
        with:
          path: ~/.m2
          key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }}

      - name: Run BDD tests
        run: mvn test -Dcucumber.filter.tags="@smoke"

      - name: Generate Allure Report
        if: always()
        run: |
          mvn allure:report
          mvn allure:serve &

      - name: Publish test results
        if: always()
        uses: actions/upload-artifact@v3
        with:
          name: test-results
          path: |
            target/cucumber-reports
            target/allure-results

      - name: Comment PR with results
        if: github.event_name == 'pull_request'
        uses: actions/github-script@v6
        with:
          script: |
            const fs = require('fs');
            const results = JSON.parse(
              fs.readFileSync('target/cucumber.json', 'utf8')
            );

            const passed = results.filter(f =>
              f.elements.every(e =>
                e.steps.every(s => s.result.status === 'passed')
              )
            ).length;

            const total = results.length;

            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `## BDD Test Results\n✅ ${passed}/${total} features passed`
            });

pipeline {
    agent any

    stages {
        stage('Checkout') {
            steps {
                checkout scm
            }
        }

        stage('Build') {
            steps {
                sh 'mvn clean compile'
            }
        }

        stage('BDD Tests - Smoke') {
            steps {
                sh 'mvn test -Dcucumber.filter.tags="@smoke"'
            }
        }

        stage('BDD Tests - Regression') {
            when {
                branch 'main'
            }
            steps {
                sh 'mvn test -Dcucumber.filter.tags="not @wip"'
            }
        }

        stage('Generate Reports') {
            steps {
                cucumber buildStatus: 'SUCCESS',
                    reportTitle: 'BDD Test Report',
                    fileIncludePattern: '**/*.json',
                    trendsLimit: 10

                allure([
                    includeProperties: false,
                    jdk: '',
                    properties: [],
                    reportBuildPolicy: 'ALWAYS',
                    results: [[path: 'target/allure-results']]
                ])
            }
        }
    }

    post {
        always {
            junit 'target/surefire-reports/*.xml'
            archiveArtifacts artifacts: 'target/cucumber-reports/**/*'
        }

        failure {
            emailext(
                subject: "BDD Tests Failed: ${env.JOB_NAME} - ${env.BUILD_NUMBER}",
                body: "Check console output at ${env.BUILD_URL}",
                to: "${env.CHANGE_AUTHOR_EMAIL}"
            )
        }
    }
}

@RunWith(Cucumber.class)
@CucumberOptions(
    features = "src/test/resources/features",
    glue = "stepdefinitions",
    plugin = {"json:target/cucumber-report.json"},
    tags = "@smoke"
)
public class RunCucumberTest {
}

<!-- pom.xml -->
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <configuration>
        <parallel>methods</parallel>
        <threadCount>4</threadCount>
        <perCoreThreadCount>true</perCoreThreadCount>
    </configuration>
</plugin>

# Bad - too detailed, brittle
Scenario: Search for products
  Given I am on the homepage
  When I click the search icon in the top right corner
  And I type "laptop" in the search box with id "search-input"
  And I press the Enter key
  Then I should see a loading spinner for 2 seconds
  And I should see 15 products displayed in a grid layout
  And each product should have an image, title, price, and rating

# Good - focuses on behavior
Scenario: Search for products
  Given I am on the homepage
  When I search for "laptop"
  Then I should see relevant product results

# Bad - scenarios depend on previous ones
Scenario: Create user
  When I create user "john@example.com"
  Then user should be created

Scenario: Update user # Assumes previous scenario ran
  When I update user "john@example.com" name to "John Doe"
  Then name should be updated

# Good - each scenario is independent
Scenario: Update user name
  Given a user exists with email "john@example.com"
  When I update the user's name to "John Doe"
  Then the user's name should be "John Doe"

# Bad - testing implementation
Scenario: Password hashing
  When a user registers with password "secret123"
  Then the password should be hashed with bcrypt
  And the hash should start with "$2a$"

# Good - testing behavior
Scenario: Secure password storage
  When a user registers with password "secret123"
  Then the password should not be stored in plain text
  And the user should be able to login with "secret123"