Fluent Scenario Builder API – .With(), .When(), .Then(), etc.

[cwinland]

Description:
Implement a fluent, chainable API for defining test scenarios. Goals include:

• .With(), .When(), .Then(), .Verify(), .LogScenario() syntax
• Strong typing and IntelliSense support
• Compatibility with any provider via abstraction layer
• Ergonomic design for clean, readable test definitions

[cwinland]

Context

We want to implement a fluent, chainable API for defining test scenarios in FastMoq.
The goal is to make tests more expressive, readable, and maintainable, while still leveraging the existing provider abstraction and constructor injection logic.

This API should allow developers to write tests in a natural, narrative style:

Scenario
    .With(() => new MyService(...))
    .When(svc => svc.DoSomething("input"))
    .Then(result => result.ShouldBe(expected))
    .Verify(mock => mock.SomeDependency.CallWasMade());

---

High‑Level Goals

• Fluent syntax: .With(), .When(), .Then(), .Verify(), .LogScenario()
• Strong typing and IntelliSense support
• Provider‑agnostic — works with any registered mocking provider
• Ergonomic design — minimal boilerplate, clear intent
• Composable — steps can be reused across tests
• Hybrid support — works with both public types (generic base) and internal/protected types (non‑generic base)
• Unified usage — allow Scenario.With(Component) in both base class types

---

Proposed Structure

1. Scenario Builder Entry Point

public static class Scenario
{
    // For public types (generic path)
    public static ScenarioBuilder<T> With<T>(Func<T> factory)
        => new ScenarioBuilder<T>(factory);

    // For internal/protected types (non-generic path)
    public static ScenarioBuilder<T> With<T>(Mocker mocker, Type targetType)
        => new ScenarioBuilder<T>(() => (T)MockerConstructionHelper.CreateInstance(mocker, targetType));

    // Shared helper for both generic and non-generic MockerTestBase
    public static ScenarioBuilder<T> With<T>(T component)
        => new ScenarioBuilder<T>(() => component);
}

2. Scenario Builder Class

public class ScenarioBuilder<T>
{
    private readonly T _component;
    private readonly List<Action> _verifications = new();

    public ScenarioBuilder(Func<T> factory)
    {
        _component = factory();
    }

    public ScenarioBuilder<T> When(Action<T> action)
    {
        action(_component);
        return this;
    }

    public ScenarioBuilder<T> Then(Action<T> assertion)
    {
        assertion(_component);
        return this;
    }

    public ScenarioBuilder<T> Verify(Action verification)
    {
        _verifications.Add(verification);
        return this;
    }

    public ScenarioBuilder<T> LogScenario(Action<T> logger)
    {
        logger(_component);
        return this;
    }

    public void Execute()
    {
        foreach (var verify in _verifications)
            verify();
    }
}

---

Changes to MockerTestBase and MockerTestBase_Constructors

Shared Constructor Logic

Extract the existing constructor‑finding/activating code into a shared helper:

internal static class MockerConstructionHelper
{
    internal static object CreateInstance(Mocker mocker, Type targetType)
    {
        if (mocker == null) throw new ArgumentNullException(nameof(mocker));
        if (targetType == null) throw new ArgumentNullException(nameof(targetType));

        // Existing logic from MockerTestBase_Constructors:
        var ctor = ConstructorSelector.FindBestConstructor(targetType, mocker);
        var args = ConstructorSelector.ResolveParameters(ctor, mocker);
        return Activator.CreateInstance(targetType, args);
    }
}

---

Generic Base (unchanged except for shared helper)

public abstract partial class MockerTestBase<T>
{
    protected Mocker Mocker { get; }
    protected T Component { get; }

    protected MockerTestBase()
    {
        Mocker = new Mocker();
        Component = (T)MockerConstructionHelper.CreateInstance(Mocker, typeof(T));
    }
}

---

Non‑Generic Base for Internal/Protected Types

public abstract class MockerTestBase
{
    protected Mocker Mocker { get; }
    protected object Component { get; private set; }

    protected MockerTestBase(Type targetType)
    {
        Mocker = new Mocker();
        Component = MockerConstructionHelper.CreateInstance(Mocker, targetType);
    }

    /// <summary>
    /// Strongly‑typed accessor for the component under test.
    /// </summary>
    protected TComponent ComponentAs<TComponent>() => (TComponent)Component;
}

---

Example Usage – Public Type

Scenario
    .With(Component) // from MockerTestBase<T>
    .When(svc => svc.ProcessOrder(orderId))
    .Then(svc => svc.LastProcessedOrder.ShouldBe(orderId))
    .Verify(() => Mocker.Verify<IOrderRepository>(r => r.Save(orderId)))
    .Execute();

Example Usage – Internal Type

Scenario
    .With(ComponentAs<MyInternalType>()) // from non-generic MockerTestBase
    .When(svc => svc.ProcessOrder(orderId))
    .Then(svc => svc.LastProcessedOrder.ShouldBe(orderId))
    .Verify(() => Mocker.Verify<IOrderRepository>(r => r.Save(orderId)))
    .Execute();

---

Benefits

• Readable: Test steps read like a narrative.
• Reusable: Common .With() or .When() steps can be shared.
• Extensible: Easy to add .Given() or .And() in future.
• Consistent: Works with both public and internal types without extra ceremony.
• Unified: Scenario.With(Component) works in both base class types.
• Type‑safe: Strong typing preserved in both paths.

---

Next Steps:

• Implement ScenarioBuilder<T> and overloads for .With().
• Integrate .Verify() with FastMoq’s provider abstraction.
• Add .LogScenario() hooks for structured logging.
• Provide cookbook examples in Milestone 5 documentation.
• Update MockerTestBase and MockerTestBase_Constructors as shown above to support unified Component usage.