Intermediate

// File: pages/LoginPage.ts
export class LoginPage {
  // => Class: Encapsulates login page UI
  private usernameInput = 'input[name="username"]';
  // => Locator: CSS selector for username field
  private passwordInput = 'input[name="password"]';
  // => Locator: Password field selector
  private submitButton = 'button[type="submit"]';
  // => Locator: Submit button selector
  private errorMessage = ".error-message";
  // => Locator: Error display element

  constructor(private page: any) {
    // => Constructor: Receives Playwright/Selenium page object
    // => Dependency injection: Page driver from test framework
  }

  async enterUsername(username: string): Promise<void> {
    // => Method: Encapsulates username entry
    await this.page.fill(this.usernameInput, username);
    // => Action: Fill username field
    // => Hides: Implementation detail of how to enter text
  }

  async enterPassword(password: string): Promise<void> {
    // => Method: Encapsulates password entry
    await this.page.fill(this.passwordInput, password);
    // => Action: Fill password field
  }

  async clickSubmit(): Promise<void> {
    // => Method: Encapsulates button click
    await this.page.click(this.submitButton);
    // => Action: Click submit button
    // => Waits: Playwright auto-waits for element
  }

  async getErrorMessage(): Promise<string> {
    // => Method: Retrieves error text
    return await this.page.textContent(this.errorMessage);
    // => Return: Error message text
    // => Output: "Invalid credentials" or similar
  }

  async login(username: string, password: string): Promise<void> {
    // => Method: Combines multiple actions
    await this.enterUsername(username);
    // => Step 1: Enter username
    await this.enterPassword(password);
    // => Step 2: Enter password
    await this.clickSubmit();
    // => Step 3: Submit form
    // => Convenience: Single method for common workflow
  }
}

// File: step-definitions/login.steps.ts
import { Given, When, Then } from "@cucumber/cucumber";
import { expect } from "chai";
import { LoginPage } from "../pages/LoginPage";

When("I log in with username {string} and password {string}", async function (username: string, password: string) {
  // => When: Uses Page Object instead of direct driver calls
  const loginPage = new LoginPage(this.page);
  // => Create: Page Object instance with driver
  await loginPage.login(username, password);
  // => Action: High-level login method
  // => Benefits: No locators in step definition
  // => Maintainability: Locator changes only affect LoginPage
});

Then("I should see login error {string}", async function (expectedError: string) {
  // => Then: Verify error using Page Object
  const loginPage = new LoginPage(this.page);
  const actualError = await loginPage.getErrorMessage();
  // => Query: Get error via Page Object method
  expect(actualError).to.equal(expectedError);
  // => Assertion: Error matches expectation
});

Scenario: Login with invalid password
  Given I am on the login page
  When I log in with username "alice@example.com" and password "wrongpass"
  Then I should see login error "Invalid credentials"

// File: step-definitions/api.steps.ts
import { Given, When, Then } from "@cucumber/cucumber";
import { expect } from "chai";
import axios, { AxiosResponse } from "axios";

interface ApiWorld {
  baseUrl: string;
  response?: AxiosResponse;
  requestBody?: any;
}

Given("the API is available at {string}", function (this: ApiWorld, baseUrl: string) {
  // => Given: Set base URL for API calls
  this.baseUrl = baseUrl;
  // => World: Store base URL
  // => Example: "http://localhost:3000/api"
});

When("I send a GET request to {string}", async function (this: ApiWorld, endpoint: string) {
  // => When: HTTP GET request
  const url = `${this.baseUrl}${endpoint}`;
  // => URL: Combine base + endpoint
  // => Example: "http://localhost:3000/api/users"

  try {
    this.response = await axios.get(url);
    // => Request: Axios GET call
    // => Response: {status: 200, data: {...}, headers: {...}}
  } catch (error: any) {
    this.response = error.response;
    // => Error: Store error response for Then step
    // => Allows: Testing error scenarios (404, 500, etc.)
  }
});

When(
  "I send a POST request to {string} with:",
  async function (this: ApiWorld, endpoint: string, dataTable: DataTable) {
    // => When: HTTP POST with body
    const url = `${this.baseUrl}${endpoint}`;
    this.requestBody = dataTable.rowsHash();
    // => Body: Convert table to JSON object
    // => Example: {username: "alice", email: "alice@example.com"}

    try {
      this.response = await axios.post(url, this.requestBody);
      // => Request: POST with JSON body
      // => Response: {status: 201, data: {id: 1, ...}}
    } catch (error: any) {
      this.response = error.response;
      // => Error: Capture for error scenarios
    }
  },
);

Then("the response status should be {int}", function (this: ApiWorld, expectedStatus: number) {
  // => Then: Verify HTTP status code
  expect(this.response).to.exist;
  // => Assertion: Response received
  expect(this.response!.status).to.equal(expectedStatus);
  // => Assertion: Status matches
  // => Output: Test passes (e.g., 200, 201, 404)
});

Then(
  "the response should have {string} equal to {string}",
  function (this: ApiWorld, fieldPath: string, expectedValue: string) {
    // => Then: Verify response field
    const actualValue = this.response!.data[fieldPath];
    // => Extract: Field from response body
    // => Example: response.data.username
    expect(actualValue).to.equal(expectedValue);
    // => Assertion: Field value matches
  },
);

Then("the response should contain {int} items", function (this: ApiWorld, expectedCount: number) {
  // => Then: Verify array length
  expect(this.response!.data).to.be.an("array");
  // => Assertion: Response is array
  expect(this.response!.data).to.have.length(expectedCount);
  // => Assertion: Array size matches
  // => Output: Test passes (e.g., 5 users returned)
});

Feature: User API

  Scenario: Get all users
    Given the API is available at "http://localhost:3000/api"
    When I send a GET request to "/users"
    Then the response status should be 200
    And the response should contain 3 items

  Scenario: Create new user
    Given the API is available at "http://localhost:3000/api"
    When I send a POST request to "/users" with:
      | username | alice            |
      | email    | alice@example.com|
    Then the response status should be 201
    And the response should have "username" equal to "alice"

  Scenario: Get non-existent user
    Given the API is available at "http://localhost:3000/api"
    When I send a GET request to "/users/999"
    Then the response status should be 404

// File: step-definitions/database.steps.ts
import { Given, When, Then } from "@cucumber/cucumber";
import { expect } from "chai";
import { Pool } from "pg"; // PostgreSQL client

interface DbWorld {
  dbPool: Pool;
  queryResult?: any[];
}

Given("the database is empty", async function (this: DbWorld) {
  // => Given: Clear database for clean state
  this.dbPool = new Pool({
    host: "localhost",
    database: "test_db",
    user: "test_user",
    password: "test_pass",
  });
  // => Connection: Test database pool

  await this.dbPool.query("DELETE FROM users");
  // => Cleanup: Remove all users
  await this.dbPool.query("DELETE FROM orders");
  // => Cleanup: Remove all orders
  // => Output: Empty tables for scenario
});

Given("the following users exist in the database:", async function (this: DbWorld, dataTable: DataTable) {
  // => Given: Seed database with test data
  const users = dataTable.hashes();
  // => Parse: Table to array of user objects

  for (const user of users) {
    await this.dbPool.query(
      "INSERT INTO users (username, email, role) VALUES (substantial amounts substantial amounts substantial amounts)",
      [user.username, user.email, user.role],
    );
    // => Insert: Add user to database
    // => Parameterized: Prevents SQL injection
  }
  // => Output: Users inserted (e.g., 3 rows)
});

When("a user {string} is created with email {string}", async function (this: DbWorld, username: string, email: string) {
  // => When: Trigger user creation
  await this.dbPool.query(
    "INSERT INTO users (username, email, role) VALUES (substantial amounts substantial amounts substantial amounts)",
    [username, email, "user"],
  );
  // => Insert: Create new user
  // => Default: Role set to 'user'
});

Then("the database should contain {int} users", async function (this: DbWorld, expectedCount: number) {
  // => Then: Verify user count
  const result = await this.dbPool.query("SELECT COUNT(*) FROM users");
  // => Query: Count rows in users table
  const actualCount = parseInt(result.rows[0].count);
  // => Extract: Count from query result
  expect(actualCount).to.equal(expectedCount);
  // => Assertion: Count matches
  // => Output: Test passes (e.g., 4 users)
});

Then(
  "user {string} should exist with email {string}",
  async function (this: DbWorld, username: string, expectedEmail: string) {
    // => Then: Verify specific user data
    const result = await this.dbPool.query("SELECT email FROM users WHERE username = substantial amounts", [username]);
    // => Query: Find user by username

    expect(result.rows).to.have.length(1);
    // => Assertion: User exists (1 row)
    expect(result.rows[0].email).to.equal(expectedEmail);
    // => Assertion: Email matches
    // => Output: Test passes (email correct)
  },
);

Then("user {string} should have role {string}", async function (this: DbWorld, username: string, expectedRole: string) {
  // => Then: Verify user role
  const result = await this.dbPool.query("SELECT role FROM users WHERE username = substantial amounts", [username]);
  // => Query: Get user role

  expect(result.rows[0].role).to.equal(expectedRole);
  // => Assertion: Role matches
});

@database
Feature: User Database Operations

  Background:
    Given the database is empty

  Scenario: Create user in database
    When a user "alice" is created with email "alice@example.com"
    Then the database should contain 1 users
    And user "alice" should exist with email "alice@example.com"

  Scenario: Seed multiple users
    Given the following users exist in the database:
      | username | email              | role  |
      | alice    | alice@example.com  | admin |
      | bob      | bob@example.com    | user  |
      | charlie  | charlie@example.com| user  |
    Then the database should contain 3 users
    And user "alice" should have role "admin"
    And user "bob" should have role "user"

# File: src/test/resources/features/calculator.feature
Feature: Calculator Operations

  Scenario: Add two numbers
    Given I have a calculator
    When I add 15 and 27
    Then the result should be 42

// File: src/test/java/steps/CalculatorSteps.java
package steps;

import io.cucumber.java.en.Given;
import io.cucumber.java.en.When;
import io.cucumber.java.en.Then;
import static org.junit.Assert.assertEquals;

public class CalculatorSteps {
    // => Class: Step definitions for calculator
    private Calculator calculator;
    // => State: Calculator instance
    private int result;
    // => State: Calculation result

    @Given("I have a calculator")
    public void i_have_a_calculator() {
        // => Given: Initialize calculator
        calculator = new Calculator();
        // => Instance: New calculator for scenario
    }

    @When("I add {int} and {int}")
    public void i_add_and(int a, int b) {
        // => When: {int} extracts integers from step
        // => Example: "I add 15 and 27" → a=15, b=27
        result = calculator.add(a, b);
        // => Action: Call add method
        // => result: 42 (when a=15, b=27)
    }

    @Then("the result should be {int}")
    public void the_result_should_be(int expected) {
        // => Then: Verify result
        assertEquals(expected, result);
        // => Assertion: JUnit assertEquals
        // => Output: Test passes (result == 42)
    }
}

// File: src/main/java/Calculator.java
public class Calculator {
    // => Class: Calculator implementation

    public int add(int a, int b) {
        // => Method: Addition operation
        return a + b;
        // => Return: Sum of inputs
        // => Output: 42 (when a=15, b=27)
    }
}

// File: src/test/java/RunCucumberTest.java
import org.junit.runner.RunWith;
import io.cucumber.junit.Cucumber;
import io.cucumber.junit.CucumberOptions;

@RunWith(Cucumber.class)
// => Annotation: Use Cucumber JUnit runner
@CucumberOptions(
    features = "src/test/resources/features",
    // => Config: Feature file location
    glue = "steps",
    // => Config: Step definition package
    plugin = {"pretty", "html:target/cucumber-reports"}
    // => Config: Report formats
)
public class RunCucumberTest {
    // => Runner: Executes Cucumber tests via JUnit
    // => Output: Runs all .feature files
}

# File: Features/UserRegistration.feature
Feature: User Registration

  Scenario: Register new user with valid data
    Given the registration form is open
    When I register with username "alice" and email "alice@example.com"
    Then the user should be created successfully
    And I should see confirmation message "Registration successful"

// File: StepDefinitions/UserRegistrationSteps.cs
using TechTalk.SpecFlow;
using NUnit.Framework;

[Binding]
// => Attribute: Marks class as step definition container
public class UserRegistrationSteps
{
    // => Class: Step definitions for registration
    private RegistrationService _registrationService;
    // => Field: Service under test
    private RegistrationResult _result;
    // => Field: Operation result

    [Given(@"the registration form is open")]
    public void GivenTheRegistrationFormIsOpen()
    {
        // => Given: Initialize registration service
        _registrationService = new RegistrationService();
        // => Instance: New service for scenario
    }

    [When(@"I register with username ""(.*)"" and email ""(.*)""")]
    public void WhenIRegisterWithUsernameAndEmail(string username, string email)
    {
        // => When: Regex captures parameters
        // => Regex: ""(.*)"" extracts quoted strings
        // => Example: username="alice", email="alice@example.com"
        _result = _registrationService.Register(username, email);
        // => Action: Call registration method
        // => _result: {Success: true, Message: "Registration successful"}
    }

    [Then(@"the user should be created successfully")]
    public void ThenTheUserShouldBeCreatedSuccessfully()
    {
        // => Then: Verify success
        Assert.IsTrue(_result.Success);
        // => Assertion: NUnit assertion
        // => Output: Test passes (_result.Success == true)
    }

    [Then(@"I should see confirmation message ""(.*)""")]
    public void ThenIShouldSeeConfirmationMessage(string expectedMessage)
    {
        // => Then: Verify message
        Assert.AreEqual(expectedMessage, _result.Message);
        // => Assertion: Message matches
        // => Output: Test passes (message == "Registration successful")
    }
}

// File: Models/RegistrationService.cs
public class RegistrationService
{
    // => Class: Registration business logic

    public RegistrationResult Register(string username, string email)
    {
        // => Method: User registration
        // Basic validation
        if (string.IsNullOrEmpty(username) || string.IsNullOrEmpty(email))
        {
            // => Validation: Check required fields
            return new RegistrationResult
            {
                Success = false,
                Message = "Username and email are required"
            };
            // => Error: Return failure result
        }

        // Success case
        return new RegistrationResult
        {
            Success = true,
            Message = "Registration successful"
        };
        // => Success: Return success result
        // => Output: {Success: true, Message: "Registration successful"}
    }
}

public class RegistrationResult
{
    // => Class: Result object
    public bool Success { get; set; }
    // => Property: Operation success flag
    public string Message { get; set; }
    // => Property: User-facing message
}

# File: features/string_operations.feature
Feature: String Operations

  Scenario: Reverse a string
    Given I have the string "hello"
    When I reverse the string
    Then the result should be "olleh"

# File: features/steps/string_steps.py
from behave import given, when, then
# => Import: Behave decorators for steps

@given('I have the string "{text}"')
def step_given_string(context, text):
    # => Given: Store string in context
    # => context: Behave's World equivalent
    # => text: Captured from {string} parameter
    # => Example: text="hello"
    context.input_string = text
    # => Storage: Save for When step
    # => context.input_string: "hello"

@when('I reverse the string')
def step_when_reverse(context):
    # => When: Reverse operation
    context.result = context.input_string[::-1]
    # => Action: Python slice reversal
    # => [::-1]: Reverse string
    # => context.result: "olleh"

@then('the result should be "{expected}"')
def step_then_result(context, expected):
    # => Then: Verify result
    # => expected: Captured parameter "olleh"
    assert context.result == expected
    # => Assertion: Python assert statement
    # => Output: Test passes (result == "olleh")

Feature: User Management

  Scenario: Create multiple users
    Given the following users:
      | username | email              | age |
      | alice    | alice@example.com  | 25  |
      | bob      | bob@example.com    | 30  |
    When the users are saved
    Then the database should contain 2 users

# File: features/steps/user_steps.py
from behave import given, when, then

@given('the following users')
def step_given_users(context):
    # => Given: Receives table from context
    context.users = []
    # => Initialize: Empty user list

    for row in context.table:
        # => Iteration: context.table contains rows
        # => row: Dict with columns as keys
        # => Example: {'username': 'alice', 'email': 'alice@example.com', 'age': '25'}
        user = {
            'username': row['username'],
            'email': row['email'],
            'age': int(row['age'])
            # => Convert: Age string to integer
        }
        context.users.append(user)
        # => Storage: Add to user list
    # => context.users: [{'username': 'alice', ...}, {'username': 'bob', ...}]

@when('the users are saved')
def step_when_save(context):
    # => When: Simulate save operation
    context.saved_count = len(context.users)
    # => Storage: Count for Then step
    # => context.saved_count: 2

@then('the database should contain {count:d} users')
def step_then_count(context, count):
    # => Then: {count:d} captures integer
    # => count: Integer parameter (2)
    assert context.saved_count == count
    # => Assertion: Count matches
    # => Output: Test passes (saved_count == 2)

Feature: Authentication Validation

  Scenario Outline: Login validation rules
    Given a user with username "<username>" and password "<password>"
    When the user attempts to log in
    Then the login should "<outcome>"
    And the error message should be "<errorMessage>"

    # Happy path cases
    Examples: Valid Credentials
      | username           | password   | outcome | errorMessage |
      | alice@example.com  | Secret123! | succeed |              |
      | bob@example.com    | Pass456$   | succeed |              |

    # Validation failures
    Examples: Invalid Format
      | username    | password   | outcome | errorMessage           |
      | invalid     | Secret123! | fail    | Invalid email format   |
      | alice@      | Pass456$   | fail    | Invalid email format   |
      | @example    | Secret123! | fail    | Invalid email format   |

    # Security failures
    Examples: Weak Passwords
      | username           | password | outcome | errorMessage               |
      | alice@example.com  | 123      | fail    | Password too short         |
      | bob@example.com    | password | fail    | Password too weak          |
      | charlie@example.com| abc      | fail    | Password too short         |

// File: step-definitions/auth-validation.steps.ts
import { Given, When, Then } from "@cucumber/cucumber";
import { expect } from "chai";

interface AuthResult {
  success: boolean;
  error?: string;
}

let authResult: AuthResult;

Given("a user with username {string} and password {string}", function (username: string, password: string) {
  // => Given: Store credentials
  this.username = username;
  // => World: Store username
  this.password = password;
  // => World: Store password
});

When("the user attempts to log in", function () {
  // => When: Validate and attempt login
  authResult = validateAndLogin(this.username, this.password);
  // => Function: Business logic validation
  // => authResult: {success: true} or {success: false, error: "..."}
});

Then("the login should {string}", function (expectedOutcome: string) {
  // => Then: Verify success/fail outcome
  const shouldSucceed = expectedOutcome === "succeed";
  // => Parse: "succeed" → true, "fail" → false
  expect(authResult.success).to.equal(shouldSucceed);
  // => Assertion: Outcome matches
});

Then("the error message should be {string}", function (expectedError: string) {
  // => Then: Verify error message (or absence)
  if (expectedError === "") {
    // => Case: Success (no error expected)
    expect(authResult.error).to.be.undefined;
    // => Assertion: No error present
  } else {
    // => Case: Failure (error expected)
    expect(authResult.error).to.equal(expectedError);
    // => Assertion: Error matches
  }
});

// Validation logic
function validateAndLogin(username: string, password: string): AuthResult {
  // => Function: Authentication validation

  // Email format validation
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  // => Regex: Basic email validation
  if (!emailRegex.test(username)) {
    return { success: false, error: "Invalid email format" };
    // => Error: Email validation failed
  }

  // Password length validation
  if (password.length < 8) {
    return { success: false, error: "Password too short" };
    // => Error: Minimum length not met
  }

  // Password strength validation
  const hasNumber = /\d/.test(password);
  const hasSpecial = /[!@#$%^&*]/.test(password);
  // => Regex: Check for digits and special chars
  if (!hasNumber || !hasSpecial) {
    return { success: false, error: "Password too weak" };
    // => Error: Complexity requirements not met
  }

  return { success: true };
  // => Success: All validations passed
}

// File: support/custom-matchers.ts
import { expect } from "chai";

// Extend Chai with custom matchers
declare global {
  namespace Chai {
    interface Assertion {
      validEmail(): Assertion;
      strongPassword(): Assertion;
      withinDateRange(start: Date, end: Date): Assertion;
    }
  }
}

export function setupCustomMatchers() {
  // => Setup: Register custom matchers

  // Email validation matcher
  expect.Assertion.addMethod("validEmail", function () {
    // => Matcher: Email validation
    const email = this._obj as string;
    // => Input: Value being asserted
    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
    // => Regex: Email pattern

    this.assert(
      emailRegex.test(email),
      // => Condition: Email matches pattern
      `expected #{this} to be a valid email`,
      // => Error: Assertion failed message
      `expected #{this} to not be a valid email`,
      // => Error: Negated assertion failed
    );
  });

  // Password strength matcher
  expect.Assertion.addMethod("strongPassword", function () {
    // => Matcher: Password validation
    const password = this._obj as string;
    const hasLength = password.length >= 8;
    // => Check: Minimum length
    const hasNumber = /\d/.test(password);
    // => Check: Contains digit
    const hasUpper = /[A-Z]/.test(password);
    // => Check: Contains uppercase
    const hasLower = /[a-z]/.test(password);
    // => Check: Contains lowercase
    const hasSpecial = /[!@#$%^&*]/.test(password);
    // => Check: Contains special char

    const isStrong = hasLength && hasNumber && hasUpper && hasLower && hasSpecial;
    // => Result: All criteria met

    this.assert(
      isStrong,
      `expected #{this} to be a strong password (8+ chars, upper, lower, number, special)`,
      `expected #{this} to not be a strong password`,
    );
  });

  // Date range matcher
  expect.Assertion.addMethod("withinDateRange", function (start: Date, end: Date) {
    // => Matcher: Date range validation
    const date = this._obj as Date;
    const within = date >= start && date <= end;
    // => Check: Date within range

    this.assert(
      within,
      `expected #{this} to be within ${start} and ${end}`,
      `expected #{this} to not be within ${start} and ${end}`,
    );
  });
}

// File: step-definitions/validation.steps.ts
import { Then } from "@cucumber/cucumber";
import { expect } from "chai";
import { setupCustomMatchers } from "../support/custom-matchers";

// Setup once
setupCustomMatchers();

Then("the email {string} should be valid", function (email: string) {
  // => Then: Use custom matcher
  expect(email).to.be.validEmail();
  // => Assertion: Custom validEmail matcher
  // => Readable: Domain-specific assertion
  // => Output: Test passes (email format valid)
});

Then("the password {string} should be strong", function (password: string) {
  // => Then: Custom password matcher
  expect(password).to.be.strongPassword();
  // => Assertion: Validates password complexity
  // => Output: Test passes (password meets criteria)
});

Then("the registration date should be within last 30 days", function () {
  // => Then: Date range validation
  const now = new Date();
  const thirtyDaysAgo = new Date(now.getTime() - 30 * 24 * 60 * 60 * 1000);
  // => Calculate: 30 days ago

  expect(this.user.registrationDate).to.be.withinDateRange(thirtyDaysAgo, now);
  // => Assertion: Custom date range matcher
  // => Output: Test passes (date within range)
});

Scenario: Validate user registration data
  Given a user registered with email "alice@example.com" and password "Secure123!"
  Then the email "alice@example.com" should be valid
  And the password "Secure123!" should be strong
  And the registration date should be within last 30 days

// File: step-definitions/payment.steps.ts
import { Given, When, Then } from "@cucumber/cucumber";
import { expect } from "chai";
import sinon from "sinon";
import { PaymentService } from "../services/PaymentService";
import { StripeClient } from "../external/StripeClient";

interface PaymentWorld {
  paymentService: PaymentService;
  stripeStub: sinon.SinonStubbedInstance<StripeClient>;
  paymentResult?: any;
}

Given("the payment gateway is available", function (this: PaymentWorld) {
  // => Given: Setup mock payment gateway
  this.stripeStub = sinon.createStubInstance(StripeClient);
  // => Stub: Create fake Stripe client
  // => Benefits: No real Stripe API calls
  // => Fast: No network I/O

  this.paymentService = new PaymentService(this.stripeStub);
  // => Injection: Inject stub into service
  // => Service: Uses stub instead of real Stripe
});

Given("the payment gateway returns success for valid cards", function (this: PaymentWorld) {
  // => Given: Configure stub behavior
  this.stripeStub.charge.resolves({
    id: "ch_test_123",
    status: "succeeded",
    amount: 5000,
  });
  // => Stub: Return success response
  // => resolves: Simulates successful async call
  // => Output: Controlled test data
});

Given("the payment gateway returns error for declined cards", function (this: PaymentWorld) {
  // => Given: Configure error behavior
  this.stripeStub.charge.rejects(new Error("Card declined"));
  // => Stub: Simulate payment failure
  // => rejects: Simulates async error
});

When(
  "I process a payment of ${int} with card {string}",
  async function (this: PaymentWorld, amount: number, cardNumber: string) {
    // => When: Trigger payment
    try {
      this.paymentResult = await this.paymentService.processPayment(amount, cardNumber);
      // => Call: Service method (uses stub internally)
      // => Result: Success or error based on stub config
    } catch (error) {
      this.paymentResult = { error: (error as Error).message };
      // => Error: Capture for Then step
    }
  },
);

Then("the payment should succeed", function (this: PaymentWorld) {
  // => Then: Verify success
  expect(this.paymentResult.status).to.equal("succeeded");
  // => Assertion: Payment processed
  // => Output: Test passes (stub returned success)
});

Then("the payment should fail with {string}", function (this: PaymentWorld, expectedError: string) {
  // => Then: Verify error
  expect(this.paymentResult.error).to.include(expectedError);
  // => Assertion: Error message matches
  // => Output: Test passes (stub returned error)
});

Then(
  "the payment gateway should have been called with amount ${int}",
  function (this: PaymentWorld, expectedAmount: number) {
    // => Then: Verify mock interaction
    expect(this.stripeStub.charge.calledOnce).to.be.true;
    // => Spy: Verify method called once
    const callArgs = this.stripeStub.charge.getCall(0).args;
    // => Spy: Get call arguments
    expect(callArgs[0].amount).to.equal(expectedAmount);
    // => Assertion: Called with correct amount
    // => Output: Test passes (interaction verified)
  },
);

Feature: Payment Processing

  Scenario: Successful payment with valid card
    Given the payment gateway is available
    And the payment gateway returns success for valid cards
    When I process a payment of substantial amounts with card "4111111111111111"
    Then the payment should succeed
    And the payment gateway should have been called with amount substantial amounts

  Scenario: Failed payment with declined card
    Given the payment gateway is available
    And the payment gateway returns error for declined cards
    When I process a payment of substantial amounts with card "4000000000000002"
    Then the payment should fail with "Card declined"

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

on:
  push:
    branches: [main, develop]
    # => Trigger: Run on push to main/develop
  pull_request:
    branches: [main]
    # => Trigger: Run on pull requests to main

jobs:
  bdd-smoke:
    # => Job: Fast smoke tests
    runs-on: ubuntu-latest
    # => Runner: Latest Ubuntu

    steps:
      - uses: actions/checkout@v3
        # => Step: Clone repository

      - uses: actions/setup-node@v3
        with:
          node-version: "18"
          # => Step: Install Node.js 18

      - name: Install dependencies
        run: npm ci
        # => Step: Install packages (faster than npm install)

      - name: Run smoke tests
        run: npx cucumber-js --tags "@smoke" --format json:reports/smoke.json
        # => Step: Run @smoke scenarios only
        # => Output: JSON report
        # => Duration: ~2 minutes

      - name: Upload smoke results
        uses: actions/upload-artifact@v3
        if: always()
        # => Step: Upload results even on failure
        with:
          name: smoke-test-results
          path: reports/smoke.json
          # => Artifact: Test results for analysis

  bdd-regression:
    # => Job: Full regression suite
    runs-on: ubuntu-latest
    needs: bdd-smoke
    # => Dependency: Run only if smoke tests pass

    services:
      postgres:
        # => Service: Test database
        image: postgres:15
        env:
          POSTGRES_PASSWORD: test_pass
          POSTGRES_DB: test_db
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
        # => Health check: Wait for DB ready

    steps:
      - uses: actions/checkout@v3

      - uses: actions/setup-node@v3
        with:
          node-version: "18"

      - name: Install dependencies
        run: npm ci

      - name: Run database migrations
        run: npm run db:migrate
        # => Step: Setup test database schema

      - name: Run regression tests
        run: npx cucumber-js --tags "not @smoke and not @slow" --parallel 4
        # => Step: Run non-smoke, non-slow tests
        # => Parallel: 4 workers for speed
        # => Duration: ~10 minutes

      - name: Generate HTML report
        if: always()
        run: npx cucumber-html-reporter --input reports/*.json --output reports/index.html
        # => Step: Generate human-readable report

      - name: Upload regression results
        uses: actions/upload-artifact@v3
        if: always()
        with:
          name: regression-test-results
          path: reports/
          # => Artifact: All test reports

  bdd-e2e:
    # => Job: End-to-end tests
    runs-on: ubuntu-latest
    needs: bdd-regression
    # => Dependency: Run only if regression passes
    if: github.ref == 'refs/heads/main'
    # => Condition: Only on main branch

    steps:
      - uses: actions/checkout@v3

      - uses: actions/setup-node@v3
        with:
          node-version: "18"

      - name: Install dependencies
        run: npm ci

      - name: Run E2E tests
        run: npx cucumber-js --tags "@e2e" --retry 2
        # => Step: Run end-to-end scenarios
        # => Retry: Handle flaky browser tests
        # => Duration: ~30 minutes

      - name: Upload E2E results
        uses: actions/upload-artifact@v3
        if: always()
        with:
          name: e2e-test-results
          path: reports/

// File: cucumber.js
const common = {
  requireModule: ["ts-node/register"],
  // => Config: TypeScript support
  require: ["step-definitions/**/*.ts"],
  // => Config: Step definition paths
  format: [
    "progress-bar",
    // => Format: Progress bar for CI logs
    "json:reports/cucumber-report.json",
    // => Format: JSON for programmatic analysis
    "html:reports/cucumber-report.html",
    // => Format: HTML for human review
  ],
  formatOptions: {
    snippetInterface: "async-await",
    // => Config: Generate async step snippets
  },
};

module.exports = {
  default: common,

  ci: {
    ...common,
    // => Config: CI-specific settings
    parallel: 4,
    // => Parallel: 4 workers
    retry: 1,
    // => Retry: Retry failed scenarios once
    failFast: true,
    // => Fail fast: Stop on first failure
    strict: true,
    // => Strict: Treat warnings as errors
  },

  smoke: {
    ...common,
    // => Config: Smoke test profile
    tags: "@smoke",
    // => Filter: Only smoke scenarios
    parallel: 2,
    // => Parallel: Fewer workers for speed
  },
};

// File: cucumber.parallel.js
module.exports = {
  default: {
    parallel: 4,
    // => Workers: Run 4 scenarios simultaneously
    // => Speed: ~significantly faster for CPU-bound tests
    // => Optimal: Number of CPU cores

    publishQuiet: true,
    // => Config: Reduce log noise in parallel mode

    retry: 1,
    // => Retry: Handle transient failures

    retryTagFilter: "@flaky",
    // => Filter: Only retry @flaky scenarios
  },
};

// File: support/hooks.ts
import { Before, After } from "@cucumber/cucumber";
import { Pool } from "pg";

Before(async function () {
  // => Before: Each worker gets isolated DB
  const workerId = process.env.CUCUMBER_WORKER_ID || "0";
  // => Worker ID: Cucumber assigns unique ID per worker
  // => Range: '0', '1', '2', '3' for 4 workers

  this.dbPool = new Pool({
    host: "localhost",
    database: `test_db_${workerId}`,
    // => Database: Separate DB per worker
    // => Isolation: Workers don't interfere
    // => Example: test_db_0, test_db_1, test_db_2, test_db_3
    user: "test_user",
    password: "test_pass",
  });

  // Clean database for scenario
  await this.dbPool.query("DELETE FROM users");
  await this.dbPool.query("DELETE FROM orders");
  // => Cleanup: Fresh state per scenario
});

After(async function () {
  // => After: Close DB connection
  await this.dbPool.end();
  // => Cleanup: Release resources
});

// File: support/server-manager.ts
import express from "express";

export async function startTestServer(): Promise<number> {
  // => Function: Start server on unique port
  const workerId = parseInt(process.env.CUCUMBER_WORKER_ID || "0");
  const basePort = 3000;
  const port = basePort + workerId;
  // => Port: 3000 + worker ID
  // => Range: 3000, 3001, 3002, 3003 for 4 workers
  // => Isolation: No port conflicts

  const app = express();
  app.use(express.json());

  app.get("/health", (req, res) => {
    res.json({ status: "ok", worker: workerId });
    // => Endpoint: Health check with worker ID
  });

  await new Promise<void>((resolve) => {
    app.listen(port, () => {
      console.log(`Worker ${workerId} server on port ${port}`);
      // => Log: Server started
      resolve();
    });
  });

  return port;
  // => Return: Port number for step definitions
}

// File: step-definitions/api-parallel.steps.ts
import { Before, Given, When } from "@cucumber/cucumber";
import { startTestServer } from "../support/server-manager";

Before(async function () {
  // => Before: Start worker-specific server
  this.serverPort = await startTestServer();
  // => Port: Unique port for this worker
  // => this.serverPort: 3000, 3001, 3002, or 3003
});

Given("the API server is running", async function () {
  // => Given: Verify server health
  const response = await fetch(`http://localhost:${this.serverPort}/health`);
  // => Request: Use worker-specific port
  const data = await response.json();
  // => Response: {status: "ok", worker: 0}
  expect(data.status).to.equal("ok");
  // => Assertion: Server ready
});

When("I send a GET request to {string}", async function (endpoint: string) {
  // => When: API call to worker-specific port
  const url = `http://localhost:${this.serverPort}${endpoint}`;
  // => URL: Worker-isolated endpoint
  this.response = await fetch(url);
  // => Request: No interference from other workers
});

# Sequential execution (no parallelization)
$ npx cucumber-js
# 100 scenarios (100 passed)
# Duration: 200 seconds (3m 20s)

# Parallel execution (4 workers)
$ npx cucumber-js --parallel 4
# 100 scenarios (100 passed)
# Duration: 55 seconds (~significantly faster)
# Worker 0: 25 scenarios
# Worker 1: 25 scenarios
# Worker 2: 25 scenarios
# Worker 3: 25 scenarios

// File: fixtures/user-fixtures.ts
export interface UserFixture {
  username: string;
  email: string;
  password: string;
  role: "admin" | "user" | "guest";
}

export const UserFixtures: Record<string, UserFixture> = {
  // => Fixtures: Predefined test users

  admin: {
    // => Fixture: Admin user
    username: "admin-user",
    email: "admin@example.com",
    password: "Admin123!",
    role: "admin",
    // => Use case: Testing admin-only features
  },

  regularUser: {
    // => Fixture: Standard user
    username: "john-doe",
    email: "john@example.com",
    password: "User456$",
    role: "user",
    // => Use case: Testing user features
  },

  guest: {
    // => Fixture: Guest user
    username: "guest-user",
    email: "guest@example.com",
    password: "Guest789#",
    role: "guest",
    // => Use case: Testing limited access
  },

  invalidEmail: {
    // => Fixture: Invalid data for error testing
    username: "invalid-user",
    email: "not-an-email",
    password: "Test123!",
    role: "user",
    // => Use case: Testing validation errors
  },
};

export interface OrderFixture {
  orderId: string;
  customerId: string;
  items: Array<{ product: string; quantity: number; price: number }>;
  total: number;
  status: "pending" | "shipped" | "delivered";
}

export const OrderFixtures: Record<string, OrderFixture> = {
  // => Fixtures: Sample orders

  smallOrder: {
    orderId: "ORD-001",
    customerId: "CUST-123",
    items: [{ product: "Widget", quantity: 2, price: 10.0 }],
    total: 20.0,
    status: "pending",
    // => Use case: Testing basic order processing
  },

  largeOrder: {
    orderId: "ORD-002",
    customerId: "CUST-456",
    items: [
      { product: "Widget", quantity: 100, price: 10.0 },
      { product: "Gadget", quantity: 50, price: 25.0 },
    ],
    total: 2250.0,
    status: "pending",
    // => Use case: Testing bulk order handling
  },
};

// File: step-definitions/fixture-steps.ts
import { Given, When, Then } from "@cucumber/cucumber";
import { expect } from "chai";
import { UserFixtures, OrderFixtures } from "../fixtures/user-fixtures";

Given("a {string} user exists", async function (fixtureName: string) {
  // => Given: Load user fixture by name
  const fixture = UserFixtures[fixtureName];
  // => Lookup: Get predefined user data
  // => Example: fixtureName="admin" → UserFixtures.admin

  if (!fixture) {
    throw new Error(`Unknown user fixture: ${fixtureName}`);
    // => Error: Invalid fixture name
  }

  this.user = await createUser(fixture);
  // => Create: Insert user in database
  // => this.user: Created user object with ID
  // => Consistent: Same data every time
});

Given("an {string} order exists", async function (fixtureName: string) {
  // => Given: Load order fixture
  const fixture = OrderFixtures[fixtureName];
  // => Lookup: Get predefined order data

  if (!fixture) {
    throw new Error(`Unknown order fixture: ${fixtureName}`);
  }

  this.order = await createOrder(fixture);
  // => Create: Insert order in database
  // => Fixtures: Provide complex nested data easily
});

// Database helpers
async function createUser(fixture: UserFixture): Promise<any> {
  // => Function: Create user from fixture
  // Simulated database insert
  return {
    id: Math.random().toString(36),
    ...fixture,
    createdAt: new Date(),
  };
  // => Return: User with generated ID
}

async function createOrder(fixture: OrderFixture): Promise<any> {
  // => Function: Create order from fixture
  return {
    ...fixture,
    createdAt: new Date(),
  };
}