BDD with SpecFlow in C#: Gherkin, Step Definitions & Real-World Pitfalls

# ── Terminal: scaffold the solution ──────────────────────────────────────────

# 1. Create a blank solution
dotnet new sln -n VendingMachine

# 2. Production code project
dotnet new classlib -n VendingMachine.Core -o src/VendingMachine.Core
dotnet sln add src/VendingMachine.Core/VendingMachine.Core.csproj

# 3. SpecFlow test project (xUnit runner)
dotnet new xunit -n VendingMachine.Specs -o tests/VendingMachine.Specs
dotnet sln add tests/VendingMachine.Specs/VendingMachine.Specs.csproj

# 4. Reference production code from the test project
dotnet add tests/VendingMachine.Specs reference src/VendingMachine.Core

# 5. Add SpecFlow NuGet packages
dotnet add tests/VendingMachine.Specs package SpecFlow
dotnet add tests/VendingMachine.Specs package SpecFlow.xUnit
dotnet add tests/VendingMachine.Specs package SpecFlow.Tools.MsBuild.Generation

# ── tests/VendingMachine.Specs/VendingMachine.Specs.csproj ────────────────────
# After adding packages, verify this appears in the .csproj:
#
# <ItemGroup>
#   <PackageReference Include="SpecFlow" Version="3.9.74" />
#   <PackageReference Include="SpecFlow.xUnit" Version="3.9.74" />
#   <PackageReference Include="SpecFlow.Tools.MsBuild.Generation" Version="3.9.74" />
# </ItemGroup>
#
# SpecFlow also needs this property to generate .feature.cs files:
# <GenerateAssemblyInfo>false</GenerateAssemblyInfo>  ← only if you hit duplicate attribute errors

# 6. Build — the MsBuild generator runs here and produces *.feature.cs files
dotnet build

# ── Folder layout after setup ─────────────────────────────────────────────────
# VendingMachine/
# ├── src/
# │   └── VendingMachine.Core/         ← production code
# │       └── VendingMachineService.cs
# └── tests/
#     └── VendingMachine.Specs/
#         ├── Features/                ← .feature files live here
#         │   └── Dispensing.feature
#         ├── StepDefinitions/         ← C# step binding classes
#         │   └── DispensingSteps.cs
#         └── Support/                 ← hooks, context objects, DI setup
#             ├── Hooks.cs
#             └── VendingMachineContext.cs

# tests/VendingMachine.Specs/Features/Dispensing.feature

Feature: Vending Machine Dispensing
  As a thirsty customer
  I want to insert money and select a product
  So that I receive my drink and the correct change

  # Background runs before EVERY scenario in this file.
  # Use it only for setup that genuinely applies to all scenarios.
  Background:
    Given the vending machine is stocked with the following products
      | ProductCode | Name        | PriceInCents | Quantity |
      | A1          | Cola        | 150          | 5        |
      | B2          | Water       | 100          | 3        |
      | C3          | OrangeJuice | 200          | 0        |

  # ── Happy path ────────────────────────────────────────────────────────────
  Scenario: Customer receives product and exact change
    Given the customer inserts 200 cents
    When the customer selects product "A1"
    Then the customer receives "Cola"
    And the customer receives 50 cents change
    And the machine stock for "A1" decreases by 1

  # ── Out-of-stock guard ─────────────────────────────────────────────────────
  Scenario: Customer selects an out-of-stock product
    Given the customer inserts 200 cents
    When the customer selects product "C3"
    Then the customer receives an out-of-stock error
    And the customer receives 200 cents change

  # ── Insufficient funds ────────────────────────────────────────────────────
  Scenario: Customer inserts too little money
    Given the customer inserts 50 cents
    When the customer selects product "A1"
    Then the customer receives an insufficient funds error
    But the machine retains 50 cents

  # ── Data-driven with Scenario Outline ─────────────────────────────────────
  # Each row in Examples becomes a separate, independently-named test method.
  # Placeholders in <angle brackets> are substituted per row.
  Scenario Outline: Change calculation across multiple price points
    Given the customer inserts <InsertedCents> cents
    When the customer selects product "<ProductCode>"
    Then the customer receives "<ExpectedProduct>"
    And the customer receives <ExpectedChange> cents change

    Examples:
      | InsertedCents | ProductCode | ExpectedProduct | ExpectedChange |
      | 150           | A1          | Cola            | 0              |
      | 200           | A1          | Cola            | 50             |
      | 200           | B2          | Water           | 100            |
      | 300           | B2          | Water           | 200            |

// ── src/VendingMachine.Core/VendingMachineService.cs ─────────────────────────

namespace VendingMachine.Core;

public record Product(string Code, string Name, int PriceInCents, int Quantity);

public class DispensingResult
{
    public Product? DispensedProduct { get; init; }
    public int ChangeInCents        { get; init; }
    public string? ErrorMessage     { get; init; }
    public bool Success             => ErrorMessage is null;
}

public class VendingMachineService
{
    // Mutable stock dictionary — keyed by product code
    private readonly Dictionary<string, Product> _stock;
    private int _insertedCents;

    public VendingMachineService(IEnumerable<Product> initialStock)
    {
        _stock = initialStock.ToDictionary(p => p.Code);
    }

    public void InsertMoney(int cents) => _insertedCents += cents;

    public DispensingResult SelectProduct(string productCode)
    {
        if (!_stock.TryGetValue(productCode, out var product))
            return new DispensingResult { ErrorMessage = "UNKNOWN_PRODUCT", ChangeInCents = _insertedCents };

        if (product.Quantity == 0)
        {
            // Return all money — machine never keeps money for out-of-stock
            int refund = _insertedCents;
            _insertedCents = 0;
            return new DispensingResult { ErrorMessage = "OUT_OF_STOCK", ChangeInCents = refund };
        }

        if (_insertedCents < product.PriceInCents)
            return new DispensingResult { ErrorMessage = "INSUFFICIENT_FUNDS" };

        int change = _insertedCents - product.PriceInCents;
        _insertedCents = 0;

        // Decrement stock — records are immutable so we replace the entry
        _stock[productCode] = product with { Quantity = product.Quantity - 1 };

        return new DispensingResult { DispensedProduct = product, ChangeInCents = change };
    }

    public int GetStockQuantity(string productCode) =>
        _stock.TryGetValue(productCode, out var p) ? p.Quantity : 0;

    public int RetainedCents => _insertedCents;
}

// ── tests/VendingMachine.Specs/Support/VendingMachineContext.cs ───────────────
// This is the shared-state bag injected across step definition classes.
// One instance per scenario — created and disposed by SpecFlow's BoDi container.

namespace VendingMachine.Specs.Support;

using VendingMachine.Core;

public class VendingMachineContext
{
    // The system under test — populated by Background steps
    public VendingMachineService? Machine { get; set; }

    // The result of the most recent SelectProduct call
    public DispensingResult? LastResult { get; set; }

    // Track initial quantities so we can assert decrements
    public Dictionary<string, int> InitialQuantities { get; } = new();
}

// ── tests/VendingMachine.Specs/StepDefinitions/DispensingSteps.cs ─────────────

namespace VendingMachine.Specs.StepDefinitions;

using TechTalk.SpecFlow;
using TechTalk.SpecFlow.Assist;   // for table.CreateSet<T>()
using VendingMachine.Core;
using VendingMachine.Specs.Support;
using Xunit;

// [Binding] tells SpecFlow to scan this class for step definitions and hooks.
[Binding]
public sealed class DispensingSteps
{
    // Context injected by BoDi — same instance shared with any other step class
    // that also accepts VendingMachineContext in its constructor this scenario.
    private readonly VendingMachineContext _ctx;

    public DispensingSteps(VendingMachineContext ctx)
    {
        _ctx = ctx;
    }

    // ── Background step ──────────────────────────────────────────────────────
    // Table.CreateSet<T>() uses the column headers as property names (case-insensitive).
    // It handles int conversion automatically via the Assist library.
    [Given(@"the vending machine is stocked with the following products")]
    public void GivenTheMachineIsStockedWithProducts(Table stockTable)
    {
        var products = stockTable.CreateSet<Product>();   // maps rows → Product records
        _ctx.Machine = new VendingMachineService(products);

        // Snapshot initial quantities so assertions can check decrements
        foreach (var product in products)
            _ctx.InitialQuantities[product.Code] = product.Quantity;
    }

    // ── Given steps ──────────────────────────────────────────────────────────
    // {int} is a SpecFlow Expression — matches one or more digits, auto-converts to int.
    [Given(@"the customer inserts {int} cents")]
    public void GivenCustomerInsertsMoney(int cents)
    {
        _ctx.Machine!.InsertMoney(cents);
    }

    // ── When steps ───────────────────────────────────────────────────────────
    // {string} matches a double-quoted string in Gherkin and strips the quotes.
    [When(@"the customer selects product {string}")]
    public void WhenCustomerSelectsProduct(string productCode)
    {
        // Store result on context so Then steps can assert against it
        _ctx.LastResult = _ctx.Machine!.SelectProduct(productCode);
    }

    // ── Then steps ───────────────────────────────────────────────────────────
    [Then(@"the customer receives {string}")]
    public void ThenCustomerReceivesProduct(string expectedProductName)
    {
        Assert.NotNull(_ctx.LastResult);
        Assert.True(_ctx.LastResult.Success, $"Expected success but got error: {_ctx.LastResult.ErrorMessage}");
        Assert.Equal(expectedProductName, _ctx.LastResult.DispensedProduct?.Name);
    }

    [Then(@"the customer receives {int} cents change")]
    public void ThenCustomerReceivesChange(int expectedChangeInCents)
    {
        Assert.Equal(expectedChangeInCents, _ctx.LastResult!.ChangeInCents);
    }

    [Then(@"the customer receives an out-of-stock error")]
    public void ThenCustomerReceivesOutOfStockError()
    {
        Assert.Equal("OUT_OF_STOCK", _ctx.LastResult!.ErrorMessage);
    }

    [Then(@"the customer receives an insufficient funds error")]
    public void ThenCustomerReceivesInsufficientFundsError()
    {
        Assert.Equal("INSUFFICIENT_FUNDS", _ctx.LastResult!.ErrorMessage);
    }

    // "But" steps use [Then] — SpecFlow treats But identically to Then at runtime.
    [Then(@"the machine retains {int} cents")]
    public void ThenMachineRetainsMoney(int expectedRetainedCents)
    {
        Assert.Equal(expectedRetainedCents, _ctx.Machine!.RetainedCents);
    }

    [Then(@"the machine stock for {string} decreases by {int}")]
    public void ThenStockDecreases(string productCode, int decrementAmount)
    {
        int initial  = _ctx.InitialQuantities[productCode];
        int current  = _ctx.Machine!.GetStockQuantity(productCode);
        Assert.Equal(decrementAmount, initial - current);
    }
}

// ── tests/VendingMachine.Specs/Support/Hooks.cs ───────────────────────────────
// Hooks that run outside the step definitions — clean lifecycle management.

namespace VendingMachine.Specs.Support;

using TechTalk.SpecFlow;

[Binding]
public sealed class Hooks
{
    // [BeforeScenario] runs before every scenario.
    // If you need to reset external state (e.g. a real DB), do it here.
    // The VendingMachineContext is already fresh per-scenario via BoDi,
    // so we only need this hook if we have truly external resources.
    [BeforeScenario]
    public void LogScenarioStart(ScenarioContext scenarioContext)
    {
        Console.WriteLine($"[START] {scenarioContext.ScenarioInfo.Title}");
    }

    [AfterScenario]
    public void LogScenarioResult(ScenarioContext scenarioContext)
    {
        var status = scenarioContext.TestError is null ? "PASSED" : "FAILED";
        Console.WriteLine($"[{status}] {scenarioContext.ScenarioInfo.Title}");

        // In a real suite you'd flush logs, take screenshots, or reset DB here.
    }
}

// ── tests/VendingMachine.Specs/specflow.json ──────────────────────────────────
// This file controls SpecFlow runtime behaviour.
// Place it in the test project root alongside the .csproj.

/*
{
  "$schema": "https://specflow.org/specflow-default.json",
  "language": { "feature": "en" },
  "bindingCulture": { "name": "en-US" },
  "runtime": {
    "missingOrPendingStepsOutcome": "Error"
  }
}
*/
// ↑ missingOrPendingStepsOutcome: "Error" means an unbound step breaks the build.
//   Change to "Pending" locally during active development so you can run partial suites.

// ── tests/VendingMachine.Specs/AssemblyInfo.cs ────────────────────────────────
// Controls xUnit's parallelism — must sit at assembly level.

using Xunit;

// CollectionPerAssembly: all test classes share one thread unless you opt individual
// classes into a named Collection. Use CollectionPerClass for full scenario isolation.
[assembly: CollectionBehavior(CollectionBehavior.CollectionPerClass, DisableTestParallelization = false)]

// ── Feature file with tags ────────────────────────────────────────────────────
// Dispensing.feature (tag examples shown inline as comments)
//
//   @smoke                           ← applies to all scenarios below until next tag group
//   Scenario: Customer receives product and exact change
//     ...
//
//   @slow @integration
//   Scenario: Customer sees stock sync with warehouse API
//     ...

// ── CLI: run only @smoke scenarios ───────────────────────────────────────────
// dotnet test tests/VendingMachine.Specs --filter 'Category=smoke'

// ── tests/VendingMachine.Specs/Support/SmokeHooks.cs ─────────────────────────
// Hook that fires ONLY for scenarios tagged @smoke

namespace VendingMachine.Specs.Support;

using TechTalk.SpecFlow;

[Binding]
public sealed class SmokeHooks
{
    private readonly ScenarioContext _scenarioContext;

    public SmokeHooks(ScenarioContext scenarioContext)
    {
        _scenarioContext = scenarioContext;
    }

    // The string argument to [BeforeScenario] is a tag filter.
    // This method only executes when the current scenario carries @smoke.
    [BeforeScenario("smoke")]
    public void ConfigureSmokeEnvironment()
    {
        Console.WriteLine($"Smoke setup for: {_scenarioContext.ScenarioInfo.Title}");
        // e.g. set a lighter timeout, skip WireMock, use in-memory repos
    }

    // ── Parallel isolation demo ───────────────────────────────────────────────
    // BAD — static field will cause race conditions in parallel runs:
    // private static VendingMachineService? _sharedMachine;  // ← NEVER DO THIS

    // GOOD — injected context is per-scenario, thread-safe:
    // private readonly VendingMachineContext _ctx;  // ← injected via constructor
}

// ── Advanced: registering custom services in BoDi ────────────────────────────
// If you need interfaces (e.g. IProductRepository), register them in a BeforeScenario hook.

[Binding]
public sealed class DependencyRegistration
{
    private readonly IObjectContainer _container; // BoDi's IoC container

    public DependencyRegistration(IObjectContainer container)
    {
        _container = container;
    }

    [BeforeScenario]
    public void RegisterScenarioDependencies()
    {
        // Register a fake repository for every scenario.
        // BoDi will inject IProductRepository wherever it's requested in step classes.
        // Swap for a real implementation in @integration-tagged scenarios.
        _container.RegisterTypeAs<InMemoryProductRepository, IProductRepository>();
    }
}

// Marker interface and stub implementation — just enough to show the pattern
public interface IProductRepository { /* ... */ }
public class InMemoryProductRepository : IProductRepository { /* ... */ }