stub0 1.0.16

stub0

stub0 is a deterministic .NET mocking library for unit and integration tests. It starts with ordinary interface mocks and extends to runtime patching when you need to override concrete classes, one real object, static members, or constructors.

The goal is to keep those cases in one small workflow instead of making you switch between a mocking library for the easy path and a separate patching tool for the hard path.

Why stub0

• Start with simple interface mocks and keep the same API when tests get harder.
• Patch one existing object or one type inside a using scope with explicit ownership and cleanup.
• Verify calls, order, and no-other-calls without leaving the same tool.
• Fail fast with actionable diagnostics when runtime patching is required but the test host is not configured for it.

Pick the lightest API

• Stub0.CreatePatched<IMyInterface>(): isolated interface mock with no runtime patching.
• Stub0.CreatePatched<MyClass>(): isolated patched object for a class or abstract class.
• Stub0.CreatePatchingScope(instance): temporary override for one existing object you already have.
• Stub0.CreatePatchingScope<MyType>(): temporary override for static members and constructor hooks.
• Arg, Times, CallContext, and ConstructorContext: argument matching, verification, and advanced behavior.

Install

dotnet add package stub0

<ItemGroup>
  <PackageReference Include="stub0" Version="x.y.z" />
</ItemGroup>

For supported .NET test frameworks (xUnit 2, xUnit 3, NUnit, MSTest, TUnit), the normal path is:

install stub0 -> run tests -> ready to go

stub0 ships build-transitive props, targets, and runsettings. RunSettingsFilePath is applied automatically only when the project is a test project and no custom runsettings path is already set.

First example

Start with CreatePatched<T>() when you want an isolated dependency, then configure behavior with On(...) and verify calls with Times.

using stub0;
using Xunit;

public interface IClock
{
    int Hour();
}

public sealed class GreetingService(IClock clock)
{
    public string GetGreeting() => clock.Hour() < 12 ? "Good morning" : "Good afternoon";
}

public class GreetingServiceTests
{
    [Fact]
    public void CreatePatched_builds_an_isolated_dependency()
    {
        using var clock = Stub0.CreatePatched<IClock>()
            .On(x => x.Hour()).Do(9);

        var sut = new GreetingService(clock.Result);

        Assert.Equal("Good morning", sut.GetGreeting());
        clock.Verify(x => x.Hour(), Times.Once);
    }
}

From there, the same mental model scales up:

• Use CreatePatchingScope(instance) when the system already owns the real object.
• Use CreatePatchingScope<MyType>() when the code you need to control is static or constructor-driven.
• Use Sequence(...), OnSetter(...), OnIndexer(...), OnEventAdd(...), and OnEventRemove(...) for more specialized member shapes.

When runtime patching matters

Interface-only mocking via Stub0.CreatePatched<IMyInterface>() does not require runtime patching.

Runtime patching is required for:

• Stub0.CreatePatched<T>() when T is a class or abstract class
• Stub0.CreatePatchingScope(instance) for non-interface instances
• Stub0.CreatePatchingScope<T>() for static members and constructor hooks

When runtime patching is needed, the test process must run with:

• JIT inlining disabled
• tiered compilation disabled
• ReadyToRun disabled
• dynamic code enabled

stub0 validates those prerequisites and throws with detailed guidance when they are not met.

Docs

• Full tutorial: https://github.com/ionoy/stub0/blob/master/docs/tutorial.md
• Cheatsheet: https://github.com/ionoy/stub0/blob/master/docs/cheatsheet.md