KnockOff 0.36.0

KnockOff

Why I wrote KnockOff

I found many times I wanted to reuse my mocks. Especially in my integration test library where I may even register my mocks. So, I found myself either copying my mock definitions or creating shared methods like this:

public static IMyRepo NSubstituteMock(List<User> users)
{
    var myRepoMock = Substitute.For<IMyRepo>();

    // Setup: configure GetUser to look up from the list based on id
    myRepoMock.GetUser(Arg.Any<int>())
        .Returns(callInfo => users.SingleOrDefault(u => u.Id == callInfo.Arg<int>()));

    // Setup: configure Update to assert user exists in list
    myRepoMock.When(x => x.Update(Arg.Any<User>()))
        .Do(callInfo => Assert.Contains(callInfo.Arg<User>(), users));

    return myRepoMock;
}

But I found these methods quite unreadable and inflexible.

What I really wanted a shared stub:

public class MyRepoManualStub(List<User> Users) : IMyRepo
{
    public User? GetUser(int id)
    {
        return Users.Single(u => u.Id == id);
    }

    public void Update(User user)
    {
        Assert.Contains(user, Users);
    }
}

But that meant:

• Forced to implement all of the methods of the interface
• I didn't have any nice to haves like .Verify()

So I created KnockOff

For stand alone stubs KnockOff:

• Automatically implements all of the interface members
• Provides features like Verification, Returns and When
• Allows per-test configuration

With KnockOff the stub looks like:

[KnockOff]
public partial class MyRepoStub(List<User> Users) : IMyRepo
{
    protected override User? GetUser_(int id)
    {
        return Users.Single(u => u.Id == id);
    }

    protected override void Update_(User user)
    {
        Assert.Contains(user, Users);
    }
}

And your test looks like

var myRepoKO = new MyRepoStub([new User { Id = 1 }, new User { Id = 2 }]);
var userDomainModel = new UserDomainModel(myRepoKO);

Assert.True(userDomainModel.Fetch(1));

// I have Verify on my Stub!
myRepoKO.GetUser.Verify(Times.Once);

And you don't actually loose the ability to configure per-test!

var user = new User { Id = 1 };
var myRepoKO = new MyRepoStub([user]);
var userDomainModel = new UserDomainModel(myRepoKO);

// OnCall overrides the stub methods
myRepoKO.GetUser.OnCall(id => user).Verifiable();
myRepoKO.Update.OnCall(u => Assert.Same(u, user)).Verifiable();

userDomainModel.Fetch(1);
userDomainModel.Update();

myRepoKO.Verify();

It also uses source generation so:

• No more Arg.Any<>(). No more It.IsAny<>(). Just write C#
• If the method signature changes you get a compile error
• There's a small performance gain but honestly it's negligible

Now I have my stubs and mocks in one!

Plus this is just the start. With source generation I think many more ideas are possible. I've added a number of patterns. And new features like Source delegation.

What other ideas do you have?

AI

With my ideas and guidance Claude Code has written the entirety of this library. What started as a curiosity has shown me the value of AI. These are ideas I've had for years. I would not have been able to actually execute without AI. Even more so in about a month!

The Difference

NSubstitute:

var repo = Substitute.For<IUserRepo>();
repo.GetUser(Arg.Is<int>(id => id > 0)).Returns(x => new User { Id = x.Arg<int>() });

KnockOff:

var stub = new CompareUserRepoStub();
stub.GetUser.OnCall((id) => id > 0 ? new User { Id = id } : null);

No Arg.Is<>(). No x.Arg<int>(). The parameter is just id.

Method Overload Resolution

The Problem: When an interface has overloaded methods with the same parameter count but different types:

public interface IFormatter
{
    string Format(string input, bool uppercase);
    string Format(string input, int maxLength);
}

Any-Value Matching

NSubstitute:

// Arg.Any<T>() required - compiler needs the types to resolve overload
formatter.Format(Arg.Any<string>(), Arg.Any<bool>()).Returns("bool overload");
formatter.Format(Arg.Any<string>(), Arg.Any<int>()).Returns("int overload");

KnockOff:

// Explicit parameter types resolve the overload - standard C# syntax
stub.Format.OnCall((string input, bool uppercase) => "bool overload");
stub.Format.OnCall((string input, int maxLength) => "int overload");

Specific-Value Matching

NSubstitute:

// Specific value matching - literals work when all args are specific
formatter.Format("test", true).Returns("UPPERCASE");
formatter.Format("test", 10).Returns("truncated");

KnockOff:

// Specific value matching - parameter types resolve the overload
stub.Format.When("test", true).Returns("UPPERCASE");
stub.Format.When("test", 10).Returns("truncated");

Argument Access

NSubstitute:

// To use argument values, extract from CallInfo:
formatter.Format(Arg.Any<string>(), Arg.Any<bool>())
    .Returns(x => x.ArgAt<bool>(1) ? x.ArgAt<string>(0).ToUpper() : x.ArgAt<string>(0));

KnockOff:

// Arguments are directly available with names and types:
stub.Format.OnCall((string input, bool uppercase) => uppercase ? input.ToUpper() : input);

The Difference:

• NSubstitute: Arg.Any<bool>() + x.ArgAt<bool>(1) to match any value and access arguments
• KnockOff: (string input, bool uppercase) - standard C# lambda with named, typed parameters

Unique Feature: Source Delegation

Delegate to a real implementation, override only what you need:

stub.Source(realRepo);  // ALL methods delegate to real implementation

// Override just the method you're testing
stub.GetUser.OnCall((id) => new User { Id = id, Name = "Test User" });

IUserRepo repo = stub;
repo.Save(new User { Id = 1 });  // Calls real SimpleUserRepo.Save()
var user = repo.GetUser(1);       // Returns test data

No other mocking framework has this. Perfect for integration tests, decorator patterns, and partial mocking without complexity.

Side-by-Side Comparisons

Methods

Argument Matching

NSubstitute:

// NSubstitute - Arg.Is<T> per parameter (permanent matchers)
calc.Add(Arg.Is<int>(a => a > 0), Arg.Any<int>()).Returns(100);

KnockOff:

// KnockOff - OnCall with conditional (permanent, matches all calls)
stub.Add.OnCall((a, b) => a > 0 ? 100 : 0);

// KnockOff - When() for sequential matching (first match returns 100, then falls through)
stub.Add.When((a, b) => a > 0).Returns(100).ThenCall((a, b) => a + b);

Multiple specific values:

// Multiple specific values
calc.Add(1, 2).Returns(100);
calc.Add(3, 4).Returns(200);

stub.Add.When(1, 2).Returns(100);
stub.Add.When(3, 4).Returns(200);

Note: NSubstitute's matchers are permanent—they match all qualifying calls. KnockOff's When() is sequential—matchers are consumed in order. Use OnCall() with conditionals for permanent matching behavior.

Argument Capture

NSubstitute:

// NSubstitute - requires Arg.Do in setup
int capturedA = 0, capturedB = 0;
calc.Add(Arg.Do<int>(x => capturedA = x), Arg.Do<int>(x => capturedB = x));
calc.Add(1, 2);

KnockOff:

// KnockOff - built-in, no pre-setup
var tracking = stub.Add.OnCall((a, b) => a + b);
ICalculator calc = stub;
calc.Add(1, 2);
var (a, b) = tracking.LastArgs;  // Named tuple: a = 1, b = 2

Properties

Events

Delegates

Indexers

Feature Parity

KnockOff covers the features NSubstitute users expect:

What KnockOff Does Better

Quick Start

Install

dotnet add package KnockOff

Create a Stub

public interface IQuickStartRepo
{
    User? GetUser(int id);
}

[KnockOff]
public partial class QuickStartRepoStub : IQuickStartRepo { }

public class QuickStartCreateStubTests
{
    [Fact]
    public void CreateStub_IsReady()
    {
        var stub = new QuickStartRepoStub();

        IQuickStartRepo repository = stub;
        Assert.NotNull(repository);
    }
}

Configure and Verify

[Fact]
public void ConfigureStub_WithOnCall()
{
    var stub = new QuickStartRepoStub();

    stub.GetUser.OnCall((id) => new User { Id = id, Name = "Test User" });

    IQuickStartRepo repository = stub;
    var user = repository.GetUser(42);

    Assert.NotNull(user);
    Assert.Equal(42, user.Id);
    Assert.Equal("Test User", user.Name);
}

[Fact]
public void VerifyCalls_WithVerifiable()
{
    var stub = new QuickStartRepoStub();
    stub.GetUser.OnCall((id) => new User { Id = id, Name = "Test" }).Verifiable();

    IQuickStartRepo repository = stub;

    var user = repository.GetUser(42);

    // Verify() checks all members marked with .Verifiable()
    stub.Verify();
}

Three Stub Patterns

Standalone - Reusable across your project:

[KnockOff]
public partial class ReadmeStandaloneStub : IUserRepo { }

Inline Interface - Test-local stubs:

[Fact]
public void InlineInterface_Pattern()
{
    var stub = new Stubs.IUserRepo();
    stub.GetUser.OnCall((id) => new User { Id = id });

    IUserRepo repo = stub;
    Assert.NotNull(repo.GetUser(1));
}

Inline Class - Stub virtual members:

[Fact]
public void InlineClass_Pattern()
{
    var stub = new Stubs.MyService();
    stub.GetUser.OnCall((id) => new User { Id = id });

    MyService service = stub.Object;
    Assert.NotNull(service.GetUser(1));
}

Documentation

• Getting Started - Installation and first stub
• Stub Patterns - Standalone, inline interface, inline class
• Interceptor API - Complete OnCall, OnGet, OnSet reference
• Source Delegation - Delegate to real implementations
• Migration from Moq - Step-by-step migration guide
• Migration from NSubstitute - Comparison and migration guide

License

MIT License. See LICENSE for details.

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

• Issues: GitHub Issues
• Pull Requests: Bug fixes, features, documentation
• Discussions: GitHub Discussions