TinyBDD.MSTest by Jerrett Davis

NuGet / site data
Details
Original Readme
How to use
Useful

NuGet / site data

Details

Info

info

Name: TinyBDD.MSTest

Package Description

Author: Jerrett Davis

NuGet: https://www.nuget.org/packages/TinyBDD.MSTest/

You can find more details at https://github.com/JerrettDavis/TinyBDD

Source: https://github.com/JerrettDavis/TinyBDD

Author

note

Jerrett Davis Alt text

Original Readme

note

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

Step	Purpose	Example
`Given`	Initial state / setup	`.Given("start", () => 5)`
`When`	Action / event	`.When("doubled", x => x * 2)`
`Then`	Assertion	`.Then(">= 10", v => v >= 10)`
`And`	Additional assertion after `Then` or `When`	`.And("<= 20", v => v <= 20)`
`But`	Additional assertion phrased negatively	`.But("!= 15", v => v != 15)`

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

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:

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
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.
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

About

note

Optimizing Test Code with BDD Style Testing

How to use

Example (source csproj, source files)

CSharp Project
TestClock.cs

This is the CSharp Project that references TinyBDD.MSTest

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>

    <IsPackable>false</IsPackable>
    <IsTestProject>true</IsTestProject>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.8.1" />
    <PackageReference Include="MSTest.TestAdapter" Version="4.3.2" />
    <PackageReference Include="MSTest.TestFramework" Version="4.3.2" />
    <PackageReference Include="coverlet.collector" Version="10.0.1">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
    </PackageReference>
    <PackageReference Include="TinyBDD.MSTest" Version="0.19.29" />
  </ItemGroup>

  <ItemGroup>
    <ProjectReference Include="..\Mock\MockData.csproj" />
  </ItemGroup>
	<PropertyGroup>
		<EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
		<CompilerGeneratedFilesOutputPath>$(BaseIntermediateOutputPath)\GX</CompilerGeneratedFilesOutputPath>
	</PropertyGroup>

</Project>

This is the use of TinyBDD.MSTest in TestClock.cs

using TinyBDD.MSTest;

namespace TestClock;

public class MyClock : IMyClock
{
    public DateTime GetNow()
    {
        return DateTime.Now;
    }
    public DateTime GetUtcNow()
    {
        return DateTime.UtcNow;
    }
}

[TestClass]
public partial class TestData:  TinyBddMsTestBase
{
    [TestMethod]
    public async Task TestMyClock()
    {
        
        await Given("start", () => new MyClock())
            .When("get now", x => x.GetNow())
            .Then("equals 84", x => DateTime.Now>=x)
            .AssertPassed();
    }
}

Generated Files

Those are taken from $(BaseIntermediateOutputPath)\GX

TestClock_TestData_TestMyClock_Optimized.g.cs

// <auto-generated/>
#nullable enable

namespace TestClock
{
    partial class TestData
    {
        async System.Threading.Tasks.Task TestMyClock_Optimized()
        {
            // Optimized implementation - no boxing!
            var __ctx = TinyBDD.Ambient.Current.Value;
            var __sw = System.Diagnostics.Stopwatch.StartNew();

            try
            {
                // Given: start
                __sw.Restart();
                TestClock.MyClock __step0 = new MyClock();
                __sw.Stop();
                __ctx.AddStep(new TinyBDD.StepResult
                {
                    Kind = "Given",
                    Title = "start",
                    Elapsed = __sw.Elapsed
                });

                // When: get now
                __sw.Restart();
                System.DateTime __step1 = __step0.GetNow();
                __sw.Stop();
                __ctx.AddStep(new TinyBDD.StepResult
                {
                    Kind = "When",
                    Title = "get now",
                    Elapsed = __sw.Elapsed
                });

                // Then: equals 84
                __sw.Restart();
                bool __step2 = DateTime.Now>=__step1;
                __sw.Stop();
                __ctx.AddStep(new TinyBDD.StepResult
                {
                    Kind = "Then",
                    Title = "equals 84",
                    Elapsed = __sw.Elapsed
                });
                if (!__step2)
                {
                    throw new TinyBDD.BddStepException("Assertion failed: equals 84", __ctx, null);
                }
            }
            catch (System.Exception __ex)
            {
                // TODO: Handle errors according to ScenarioOptions
                throw;
            }
        }
    }
}