TinyBDD.Extensions.DependencyInjection 0.19.1

TinyBDD

NuGet Packages:

Package	Version	Downloads
TinyBDD
TinyBDD.MSTest
TinyBDD.Xunit
TinyBDD.Xunit.v3
TinyBDD.NUnit
TinyBDD.Extensions.DependencyInjection
TinyBDD.Extensions.FileBased
TinyBDD.Extensions.Hosting
TinyBDD.Extensions.Reporting

TinyBDD is a minimal, fluent Behavior-Driven Development library for .NET. It supports two complementary approaches:

• Code-first: Fluent Given / When / Then syntax directly in C#
• File-based: Gherkin .feature files and YAML scenarios with convention-based drivers

Both approaches are designed to:

• Be framework-agnostic (works with MSTest, xUnit, NUnit, etc.).
• Keep scenarios clear and concise with readable syntax.
• Support async and sync operations for maximum flexibility.
• Integrate with existing test runners' output for easy step visibility.

Features

Code-First Approach

• Readable BDD syntax:

    await Given("a number", () => 5)
        .When("doubled", x => x * 2)
        .Then(">= 10", v => v >= 10)
        .And("<= 20", v => v <= 20)
        .But("!= 15", v => v != 15)
        .AssertPassed();
  

• Sync & Async Support:

  • Func<T> / Func<T, bool>
  • Func<Task<T>> / Func<T, Task<bool>>
  • Token-aware variants for advanced control.

• And / But chaining with correct step names in output:

  Given start [OK]
  When double [OK]
  Then >= 10 [OK]
  And <= 20 (async) [OK]
  But != 11 [OK]
  

File-Based Approach

• Gherkin .feature files:

  Feature: Calculator Operations
  
  Scenario: Add two numbers
    Given a calculator
    When I add 5 and 3
    Then the result should be 8
  

• Convention-based driver methods:

  [DriverMethod("I add {a} and {b}")]
  public Task Add(int a, int b)
  {
      _calculator.Add(a, b);
      return Task.CompletedTask;
  }
  

• Scenario Outlines with Examples tables for parameterized tests

• YAML format as alternative to Gherkin for tooling integration

Framework Integration

• Test framework adapters:

  • MSTest: TinyBddMsTestBase, MSTestBddReporter, MSTestTraitBridge
  • xUnit: TinyBddXunitBase, XunitTraitBridge, XunitBddReporter
  • NUnit: TinyBddNUnitBase, NUnitTraitBridge, NUnitBddReporter
  • Automatically logs steps and tags to the test output.

Installation

Add TinyBDD via NuGet:

dotnet add package TinyBDD

For MSTest:

dotnet add package TinyBDD.MSTest

For NUnit:

dotnet add package TinyBDD.NUnit

For xUnit:

dotnet add package TinyBDD.Xunit

For xUnit v3:

dotnet add package TinyBDD.Xunit.v3

For Extensions:

# File-Based DSL (Gherkin and YAML)
dotnet add package TinyBDD.Extensions.FileBased

# Dependency Injection
dotnet add package TinyBDD.Extensions.DependencyInjection

# Hosting (includes DI)
dotnet add package TinyBDD.Extensions.Hosting

# JSON Reporting
dotnet add package TinyBDD.Extensions.Reporting

⚡ Performance Optimization (Automatic!)

TinyBDD includes a Roslyn source generator that automatically optimizes ALL BDD tests at compile-time starting in v1.1. No attributes needed, no configuration, no additional packages!

📌 Important: Test classes must be declared as partial to enable source generation. This allows the generator to add optimized methods to your test class.

Default behavior - All BDD test methods are automatically optimized:

public partial class MyTests  // ← Note: 'partial' keyword required
{
    // This is automatically optimized - no attribute needed!
    public async Task FastScenario()
    {
        await Given("start", () => 42)
             .When("double", x => x * 2)
             .Then("equals 84", x => x == 84);
    }
}

Opt-out - Use [DisableOptimization] if you need the full pipeline features:

[DisableOptimization]  // Uses standard pipeline
public async Task ScenarioWithObservers()
{
    // Uses standard pipeline (observers, hooks, etc.)
    await Given("start", () => 1)
         .When("add", x => x + 1)
         .Then("equals 2", x => x == 2);
}

Performance gains:

• 16-40x faster execution (~814ns → ~20-50ns per step)
• 9x less memory (2,568 bytes → ~290 bytes per scenario)
• Zero boxing - All values are strongly typed at compile-time
• No runtime overhead - Transforms to direct procedural code
• Compile-time transformation - Happens automatically during build

When to opt-out:

• ⚠️ Using IStepObserver or IScenarioObserver (not yet supported in generated code)
• ⚠️ Using BeforeStep/AfterStep hooks
• ⚠️ Complex ScenarioOptions features
• 🐛 Debugging (to step through standard pipeline)

Common warnings:

• TBDD010: Test class is not partial → Add partial keyword to your class declaration
• TBDD011: Nested types not supported → Move tests to a top-level partial class
• TBDD012: Generic types not supported → Use non-generic partial class for tests

The generator transforms fluent chains into optimized procedural code while maintaining the same readable syntax. Generated code is placed in obj/.../generated/ for inspection.

Basic Usage

MSTest Example

using TinyBDD.MSTest;
using Microsoft.VisualStudio.TestTools.UnitTesting;

[Feature("Math")]
[TestClass]
public class MathTests : TinyBddMsTestBase
{
    [Scenario("Doubling numbers")]
    [TestMethod]
    public async Task DoublingScenario()
    {
        await Given("start with 5", () => 5)
             .When("doubled", x => x * 2)
             .Then("should be 10", v => v == 10)
             .AssertPassed();
    }
}

NUnit Example

using TinyBDD.NUnit;
using NUnit.Framework;

[Feature("Math")]
public class MathTests : TinyBddNUnitBase
{
    [Scenario("Doubling numbers")]
    [Test]
    public async Task DoublingScenario()
    {
        await Given("start with 5", () => 5)
             .When("doubled", x => x * 2)
             .Then("should be 10", v => v == 10)
             .AssertPassed();
    }
}

xUnit Example

using TinyBDD.Xunit;
using Xunit;

[Feature("Math")]
public class MathTests : TinyBddXunitBase
{
    [Scenario("Doubling numbers")]
    [Fact]
    public async Task DoublingScenario()
    {
        await Given("start with 5", () => 5) 
             .When("doubled", x => x * 2)
             .Then("should be 10", v => v == 10)
             .AssertPassed();
    }
}

File-Based Usage

Gherkin Feature File

Create Features/Calculator.feature:

Feature: Calculator Operations

@calculator @smoke
Scenario: Add two numbers
  Given a calculator
  When I add 5 and 3
  Then the result should be 8

Scenario Outline: Multiply numbers
  Given a calculator
  When I multiply <a> and <b>
  Then the result should be <expected>

Examples:
  | a | b | expected |
  | 2 | 3 | 6        |
  | 4 | 5 | 20       |

Driver Implementation

using TinyBDD.Extensions.FileBased.Core;

public class CalculatorDriver : IApplicationDriver
{
    private readonly Calculator _calculator = new();

    [DriverMethod("a calculator")]
    public Task Initialize()
    {
        _calculator.Clear();
        return Task.CompletedTask;
    }

    [DriverMethod("I add {a} and {b}")]
    public Task Add(int a, int b)
    {
        _calculator.Add(a, b);
        return Task.CompletedTask;
    }

    [DriverMethod("I multiply {a} and {b}")]
    public Task Multiply(int a, int b)
    {
        _calculator.Multiply(a, b);
        return Task.CompletedTask;
    }

    [DriverMethod("the result should be {expected}")]
    public Task<bool> VerifyResult(int expected)
    {
        return Task.FromResult(_calculator.GetResult() == expected);
    }

    public Task InitializeAsync(CancellationToken ct = default) => Task.CompletedTask;
    public Task CleanupAsync(CancellationToken ct = default) => Task.CompletedTask;
}

Test Class

using TinyBDD.Extensions.FileBased;

public class CalculatorTests : FileBasedTestBase<CalculatorDriver>
{
    [Fact]
    public async Task ExecuteCalculatorScenarios()
    {
        await ExecuteScenariosAsync(options =>
        {
            options.AddFeatureFiles("Features/**/*.feature")
                   .WithBaseDirectory(Directory.GetCurrentDirectory());
        });
    }
}

Output:

Feature: Calculator Operations
Scenario: Add two numbers
  Given a calculator [OK] 0 ms
  When I add 5 and 3 [OK] 0 ms
  Then the result should be 8 [OK] 1 ms

Scenario Outline: Multiply numbers (Example 1: a=2, b=3, expected=6)
  Given a calculator [OK] 0 ms
  When I multiply 2 and 3 [OK] 0 ms
  Then the result should be 6 [OK] 0 ms

Step Types

All step types have sync and async overloads.

Cleanup with Finally

Finally registers cleanup handlers that execute after all steps complete, even if steps throw exceptions. This is useful for resource cleanup like disposing objects:

await Given("a database connection", () => new SqlConnection(connectionString))
    .Finally("close connection", conn => conn.Dispose())
    .When("query data", conn => conn.Query<User>("SELECT * FROM Users"))
    .Then("results returned", users => users.Any())
    .AssertPassed();

// Connection is automatically disposed after all steps complete

Key Features:

• Finally handlers execute in registration order after all other steps
• They execute even when steps throw exceptions
• Multiple Finally handlers can be registered at different points in the chain
• Each Finally handler receives the state value at the point where it was registered
• The chain passes through the upstream value unchanged (tap semantics)

await Given("resource A", () => new ResourceA())
    .Finally("cleanup A", a => a.Dispose())
    .When("create resource B", a => new ResourceB(a))
    .Finally("cleanup B", b => b.Dispose())
    .Then("verify", b => b.IsValid)
    .AssertPassed();

// Execution order: Given → When → Then → Finally cleanup A → Finally cleanup B

Tags

Tags can be added for reporting and filtering:

ctx.AddTag("smoke");
ctx.AddTag("fast");

In xUnit, tags are logged to the test output:

[TinyBDD] Tag: smoke
[TinyBDD] Tag: fast

Asserting Pass/Fail

TinyBDD tracks step results internally. At the end of the scenario, call one of the following methods:

Scenario.AssertPassed();

Scenario.AssertFailed();

// or use the fluent syntax:
await Given("one", () => 1)
    .When("add one", x => x + 1)
    .Then("equals two", v => v == 2)
    .AssertPassed();

await Given("one", () => 1)
    .When("add one", x => x + 1)
    .Then("equals elevent", v => v == 11)
    .AssertFailed();

This ensures that all steps passed and throws if any failed.

Philosophy

TinyBDD was created with a few guiding principles:

1. Focus on readability, not ceremony Steps should read like plain English and map directly to Gherkin-style thinking. Choose the approach that best fits your team:

   • Code-first: Write BDD tests directly in C# with fluent API
   • File-based: Use standard Gherkin .feature files or YAML for business-readable specifications

2. Flexible specification approach Both approaches produce the same readable output:

   • Code-first: Your C# code using the fluent API serves as the executable specification
   • File-based: Separate .feature or YAML files define scenarios, implemented through driver methods

   Your test runner output is the human-readable spec in both cases.

3. Stay out of your way TinyBDD is not an opinionated test framework; it's a syntax layer that integrates with MSTest, xUnit, or NUnit and leaves assertions, test discovery, and reporting to them. Choose code-first for flexibility and complex logic, or file-based when business analysts need to author test specifications.

Gherkin-Style Output

When running a scenario, TinyBDD prints structured step output similar to Gherkin formatting.
For example:

await Given("start", () => 5)
    .When("double", x => x * 2)
    .Then(">= 10", v => v >= 10)
    .And("<= 20 (async)", v => Task.FromResult(v <= 20))
    .But("!= 11", v => v != 11)
    .AssertPassed();

Test output:

Feature: Math
Scenario: Doubling numbers
  Given start [OK] 0 ms
  When double [OK] 0 ms
  Then >= 10 [OK] 0 ms
  And <= 20 (async) [OK] 0 ms
  But != 11 [OK] 0 ms

If a step fails, you’ll see exactly which step failed, how long it took, and the exception message.

Why Use TinyBDD?

TinyBDD offers flexibility that traditional BDD tools don't:

Compared to SpecFlow / Cucumber:

• Choose your approach: Start code-first, add .feature files later when business analysts join, or vice versa
• No runtime overhead: File-based DSL uses convention-based matching without reflection or runtime parsing
• Lighter setup: Works directly with standard test frameworks (xUnit, NUnit, MSTest)
• Better IDE support: Code-first approach gets full IntelliSense, refactoring, and debugging
• Simpler integration: No separate test runners, no complex step binding configurations

Unique advantages:

• Seamlessly switch between approaches as your team's needs evolve
• Both approaches produce identical readable Gherkin-style output
• Test framework agnostic - use the test runner you already know
• Performance-optimized with automatic source generation (code-first)
• Convention-based driver methods for file-based tests (no attribute soup)

Minimal Example

For the smallest possible test:

await Given("one", () => 1)
    .When("add one", x => x + 1)
    .Then("equals two", v => v == 2)
    .AssertPassed();

Output:

Given one [OK]
When add one [OK]
Then equals two [OK]

Async Philosophy

In TinyBDD, sync and async steps are equally first-class citizens.

• If your step is synchronous, write it synchronously:

  .When("double", x => x * 2)
  .Then("is 10", v => v == 10)
  

• If your step needs async work:

  .When("fetch from DB", async x => await db.GetAsync(x))
  .Then("result exists", async v => Assert.NotNull(v))
  

You can even mix sync and async steps freely in the same scenario.

Output Style

TinyBDD always prints the BDD keyword for the step type (Given, When, Then, And, But), the step title, the result [OK] / [FAIL], and the elapsed time in milliseconds.

For failed steps, TinyBDD stops the scenario immediately and prints the exception:

Then equals two [FAIL] 1 ms
Expected: 2
Actual:   3

Recommended Usage

• One scenario per test method.
• Keep each step single-purpose—avoid hiding multiple unrelated actions in one step.
• Prefer creating functions, even local ones, to avoid unnecessary allocations, closure creation, garbage collection, and code cleanliness.
• Use Scenario.AssertPassed() or the fluent ThenChain.AssertPassed() at the end of each test to ensure every step was explicitly checked.
• Use tags to group and filter tests.

License

MIT License