Repository navigation
API Reference
This reference describes the supported user-facing API in the BbQ.MockLite namespace. MockLite has two surfaces:
- Source-generated
MockXxxtypes provide member-specific setup and verification methods. - Runtime mocks, created with
Mock.Create<T>(), provide the expression-basedMock<T>fluent API.
MockLite 2.x makes expression intent explicit and consistent across setup, callback, and verification:
-
Verify(expression, times)matches the method and the arguments in the expression. Exact values use equality,It.IsAny<T>()is a wildcard, andIt.Matches<T>()evaluates its predicate. -
VerifyAnyArguments(expression, times)performs an intentional method-wide count when argument values should be ignored. - A callback chained from
Setup(expression)inherits the same argument matcher as that setup. UseOnCallfor an independently registered method hook. - When multiple runtime or generated setups can match an invocation, the most recently registered matching setup wins.
- Runtime and generated invocation collections are exposed as snapshots for verification/inspection; generated mocks provide
Reset()to clear their concurrent invocation queue.
These are deliberate 2.x behavior changes from 1.x, where ordinary Verify ignored expression arguments and fluent setup callbacks were method-wide.
dotnet add package BbQ.MockLite
dotnet add package BbQ.MockLite.GeneratorsThe generator package is required only for source-generated mocks. Runtime mocks need BbQ.MockLite only.
| API | Result | Use when |
|---|---|---|
Mock.Of<T>() |
T |
Resolve a generated implementation when one is registered; otherwise create an unconfigured DispatchProxy fallback |
Mock.Create<T>() |
Mock<T> |
Configure and verify a runtime mock with expressions |
new Mock<T>() |
Mock<T> |
Equivalent runtime builder construction |
T must be a reference type. In normal use it is an interface.
Mock.Of<T>() is statically typed as T, so generated setup and verification members are not visible through its return value. Construct the generated class directly when configuring it, or cast a value returned by Mock.Of<T>() to the known generated type:
var clock = new MockClock().GetUtcNowReturns(DateTime.UnixEpoch);
// Equivalent resolution with an explicit cast:
var resolvedClock = (MockClock)Mock.Of<IClock>();Annotate an interface you own with the non-generic attribute and its interface type:
[GenerateMock]
public interface IClock
{
DateTime UtcNow { get; }
}For an interface you cannot annotate, apply the generic attribute to a class. It allows multiple uses:
[GenerateMock<IExternalClock>]
[GenerateMock<IExternalStore>]
public partial class TestMocks { }The generated class is named by removing a conventional leading I and adding Mock: IClock becomes MockClock, while Clock becomes MockClock.
GeneratedMockAttribute is a public marker added to generated classes. Applications normally do not apply it themselves. MockTypeRegistry.Register<TInterface, TMock>() is public generator infrastructure and normally does not need to be called by application code.
Start with a builder and use its Object in the system under test:
var mock = Mock.Create<IUserStore>();
mock.Setup(x => x.Find(It.IsAny<string>()))
.Returns((string id) => new User(id));
IUserStore store = mock.Object;Setup expressions select both a method and an argument pattern. Literal arguments match by equality; It.IsAny<T>() and It.Matches<T>(predicate) provide wildcard and predicate matching. The newest matching setup wins.
| API family | Purpose |
|---|---|
Setup(expression) |
Return a SetupPhrase<TResult>
|
Setup(expression, Func<TResult>) |
Configure a parameterless value factory |
Setup(expression, Func<T1, TResult>) |
Configure a factory using the first argument |
Setup(expression, Func<T1, T2, TResult>) |
Configure a factory using the first two arguments |
Setup(expression, Func<T1, T2, T3, TResult>) |
Configure a factory using the first three arguments |
SetupSequence(expression, params values) |
Return each value in order, then repeat the last value |
Throws(expression, exception) |
Throw for a return-value or void method |
The partial factories must match the method parameter types in order. They may omit trailing parameters, but they cannot skip a parameter in the middle.
Mock<T>.Setup(expression) returns a phrase with these members:
| Member | Result |
|---|---|
Returns(value) |
Use a constant TResult
|
Returns(Func<TResult>) |
Compute the result without arguments |
Returns<T1>(Func<T1, TResult>) |
Compute from the first argument |
Returns<T1, T2>(Func<T1, T2, TResult>) |
Compute from the first two arguments |
Returns<T1, T2, T3>(Func<T1, T2, T3, TResult>) |
Compute from the first three arguments |
ReturnsAsync<TInner>(value) |
Wrap a value for a Task<T> method, including covariant values |
ReturnsAsync<T1, TInner>(Func<T1, TInner>) |
Compute the inner task value from the first argument |
ReturnsAsync<T1, T2, TInner>(Func<T1, T2, TInner>) |
Compute the inner task value from the first two arguments |
ReturnsAsync<T1, T2, T3, TInner>(Func<T1, T2, T3, TInner>) |
Compute the inner task value from the first three arguments |
Throws(exception) |
Throw the exception when the setup matches |
Callback(Action) |
Add a parameterless callback and keep the phrase chainable |
Callback(Action<object?[]>) |
Add a raw-argument callback and keep the phrase chainable |
Callback<T1>(Action<T1>) |
Add a callback using the first argument |
Callback<T1, T2>(Action<T1, T2>) |
Add a callback using the first two arguments |
Callback<T1, T2, T3>(Action<T1, T2, T3>) |
Add a callback using the first three arguments |
Returns, ReturnsAsync, and Throws are terminal operations that return Mock<T> so configuration can continue. ReturnsAsync supports Task<T> methods. For ValueTask, ValueTask<T>, non-generic Task, or an already-created task, use Returns or a Setup overload with the method's actual return type.
Phrase callbacks inherit the setup's argument matcher. Use OnCall(expression, argumentMatcher, callback) for an independently matched callback.
mock.Setup(x => x.FindAsync(It.IsAny<string>(), It.IsAny<bool>()))
.Callback<string>(id => Console.WriteLine(id))
.ReturnsAsync((string id, bool includeDeleted) =>
includeDeleted ? FindAny(id) : FindActive(id));| API | Purpose |
|---|---|
SetupGet(property, getter) |
Configure a property getter factory |
ReturnsGet(property, value) |
Configure a constant getter value |
SetupGet(property) |
Return GetSetupPhrase<TProp> with Returns, Throws, and chainable Callback(Action)
|
SetupSet(property, setter) |
Configure a typed setter action |
SetupSet(property) |
Return SetSetupPhrase<TProp> with Throws, Callback(Action), and Callback(Action<TProp>)
|
VerifyGet(property, times, message?) |
Verify the getter count |
VerifySet(property, times, message?) |
Verify the setter count |
VerifySet(property, matcher, times, message?) |
Verify assignments accepted by a typed matcher |
OnCall is available for return-value and void expressions. Each form accepts a parameterless handler, a raw object?[] handler, or a typed handler for the first one to three arguments. The expression selects the method; its argument values do not filter the callback. Raw handlers also have an overload with Func<object?[], bool> for conditional execution.
Property callback APIs are:
-
OnPropertyAccess(property, callback)for both get and set. -
OnGetCallback(property, callback)for getters. -
OnSetCallback(property, callback)for setters. -
OnSetCallback(property, matcher, callback)for matching assigned values.
| API | What it counts |
|---|---|
Verify(returnExpression, times, message?) |
Calls matching the selected method and expression arguments |
Verify(voidExpression, times, message?) |
Calls matching the selected method and expression arguments |
Verify(returnExpression, argumentMatcher, times, message?) |
Calls to the selected return-value method whose object?[] arguments match |
Verify(expression, times) matches expression arguments and It matchers. VerifyAnyArguments(expression, times) intentionally ignores argument values. Use the explicit argument-matcher overload for custom filtering:
mock.Verify(
x => x.Find(It.IsAny<string>()),
args => args[0] is string id && id.StartsWith("user_"),
Times.Once,
"Expected one user lookup");A failed verification throws VerificationException. The optional message is appended to the generated failure detail.
| Member | Purpose |
|---|---|
Object |
The proxy implementing T
|
Invocations |
Read-only view of recorded Invocation objects |
Reset() |
Clear invocations while preserving setups and callbacks |
SetReturnsDefault<TDefault>(value) |
Override the fallback for unconfigured methods returning exactly TDefault
|
Built-in defaults include completed Task/Task<T> values, default ValueTask/ValueTask<T> values, value-type defaults, and empty arrays for IEnumerable<T>, IReadOnlyCollection<T>, IReadOnlyList<T>, ICollection<T>, and IList<T>.
For each non-generic interface method named Method, a generated mock exposes these stable member patterns where applicable:
| Pattern | Purpose |
|---|---|
SetupMethod(behavior) |
Configure a typed behavior using all parameters |
SetupMethod(parameterMatcher..., behavior) |
Configure behavior guarded by one typed predicate per parameter |
MethodReturns(value) |
Configure a constant sync, Task<T>, or ValueTask<T> result |
MethodReturns() |
Configure completed non-generic Task or default ValueTask
|
SetupMethod() |
Return a generated method setup phrase |
SetupMethod(parameterMatcher...) |
Return the same typed phrase, filtered by one typed Predicate<T> per parameter |
SetupMethodMatching(parameterMatcher) |
Collision-safe matcher phrase for a single-parameter method returning bool
|
VerifyMethod(times, message?) |
Verify the method call count |
VerifyMethod(parameterMatcher..., times, message?) |
Verify calls accepted by all typed parameter predicates |
Generated method phrases preserve the selected method's complete signature. Their factory Returns overload takes the method's full typed parameter list, and methods with parameters expose both Callback(Action) and an exact typed Callback(Action<T1, ...>). Matcher-selecting SetupMethod(parameterMatcher...) overloads use Predicate<T> parameters and return the same phrase, so the matcher is inherited by both callbacks and terminal behaviors. A single-parameter method returning bool is the one C# overload-resolution edge case: an untyped lambda is convertible to both its Func<T, bool> behavior and a Predicate<T> matcher. MockLite therefore generates SetupMethodMatching(...) only for that shape; other methods retain SetupMethod(...). Constant returns, factory returns, throws, direct SetupMethod(behavior), and shorthand MethodReturns(...) all participate in the same ordered setup registration; the most recently registered matching setup wins. Generic interface methods are implemented and can be verified, but do not receive generated setup/returns helpers.
For example:
mock.SetupFormat(
text => text.StartsWith("item"),
count => count > 0)
.Callback((text, count) => log.Add($"{text}:{count}"))
.Returns((text, count) => $"{text.ToUpperInvariant()}:{count}");Here IntelliSense contextually types text as string and count as int in both delegates; incompatible lambda parameter counts or types are rejected by the C# compiler.
For a property named Name, applicable generated members are:
-
SetupGetName(behavior),GetNameReturns(value),SetupGetName(), andVerifyGetName(times, message?). -
SetupSetName(behavior),SetupSetName(matcher, behavior),SetupSetName(),VerifySetName(times, message?), andVerifySetName(matcher, times, message?).
Every generated mock exposes IReadOnlyList<Invocation> Invocations as a snapshot and Reset() to clear recorded invocations.
-
It.IsAny<T>()matches every value in runtimeSetupexpressions. -
It.Matches<T>(Predicate<T>)matches values accepted by a predicate in runtimeSetupexpressions.
Generated setup and verification APIs use typed predicate parameters directly rather than It markers.
All helpers return Func<int, bool> and work with runtime and generated verification:
| Helper | Accepted count |
|---|---|
Times.Once |
1 |
Times.Never |
0 |
Times.Exactly(n) |
n |
Times.AtLeast(n) |
>= n |
Times.AtMost(n) |
<= n |
Times.Between(min, max) |
Inclusive range |
Times.Between throws ArgumentOutOfRangeException when min > max.
Create an invocation record with new Invocation(MethodInfo method, object[] arguments). Each record contains:
MethodInfo Methodobject[] Arguments-
DateTime Timestamp, captured in UTC
Invocation.ToString() formats the method, arguments, and ISO 8601 timestamp.
-
VerificationException(string message)is the sealed exception thrown by failed runtime and generated verification. -
GenerateMockAttribute()is valid on interfaces; the generator infers the target from the annotated declaration. -
GenerateMockAttribute(Type interfaceType)remains available for compatibility, but the explicit type is not required when annotating an interface. Its nullableTypeproperty exposes the supplied type. -
GenerateMockAttribute<T>is valid on classes and allows multiple instances. -
GeneratedMockAttributemarks generated classes and is intended for generator and analyzer infrastructure. -
MockTypeRegistry.Register<TInterface, TMock>()registers a generated factory.TInterfacemust be a reference type andTMockmust implement it and have a public parameterless constructor. Generated module initializers call this automatically.