FunctionalDev.MoqHelpers 3.0.1

FunctionalDev.MoqHelpers

Moq Helpers is a library which has been created to aid unit testing.

Please read through the rest of this document to view tools which can help reduce the brittle nature of unit tests, decrease excess code when setting up objects and enhance the clarity of what it is you're testing.

A particular focus of this library is setting up Mock objects (including non-public members) and providing access to non-public members and methods of instantiated objects.

For a complete changelog, please see the ChangeLog below

Activators

Creating instances of objects is central to most unit testing. Activator classes have been provided to reduce the overhead and brittle nature of setting up classes, when it may not be required to provide all arguments for the constructor, if those arguments are not necessary for the particular unit test in focus.

These activators can be used to future-proof the creation of objects, in that future changes to an object constructor will not break existing unit tests, providing that the additional arguments do not affect existing behaviour.

Lazy Mock Activation

A MockActivator class can be used to create Mock{T} classes.

This activator has CreateLazy and CreateNull methods which allow the creation of Mock{T} classes without needing to provide all/any constructor arguments.

Whilst these methods can be used to provide all arguments, they can also be provided with some or all constructor arguments to enable future-proofing with future constructor signature changes.

Given the following class:

public abstract class Person
{
  protected Person(ILogger<Person> logger) { }
}

The following example uses CreateLazy, without arguments, to create a new instance of Mock{Person} without supplying an instance of ILogger{Person}. Note that the Person base type will be supplied new Mock{ILogger {Person}}.Object as a value for ILogger{Person}.

public Mock<Person> CreateLazy()
  => MockActivator.CreateLazy<Person>();

The following example uses CreateNull, without arguments, to create a new instance of Mock{Person} without supplying an instance of ILogger{Person}. Note that the Person base type will be supplied null as a value for ILogger{Person}.

public Mock<Person> CreateNull()
  => MockActivator.CreateNull<Person>();

The following example uses CreateLazy, with arguments, to create a new instance of Mock{Person} supplying an instance of Mock{ILogger{Person}}. Note that the Person base type will be supplied loggerMock.Object as a value for ILogger{Person}.

public Mock<Person> CreateLazyWithMockArgument(Mock<ILogger<Person>> loggerMock)
  => MockActivator.CreateLazy<Person>(loggerMock);

The following example uses CreateLazy, with arguments, to create a new instance of Mock{Person} supplying an instance of ILogger{Person}. Note that the Person base type will be supplied loggerInstance as a value for ILogger{Person}.

public Mock<Person> CreateLazyWithMockArgument(ILogger<Person> loggerInstance)
  => MockActivator.CreateLazy<Person>(loggerInstance);

Lazy Activation

A LazyActivator class can be used to create instances of concrete classes.

This activator has CreateLazy and CreateNull methods which allow the creation of concrete classes without needing to provide all/any constructor arguments.

Whilst these methods can be used to provide all arguments, they can also be provided with some or all constructor arguments to enable future-proofing with future constructor signature changes.

An example can be seen below:

public class Person
{
  public Person(ILogger<Person> logger) { }
}

The following example uses CreateLazy, without arguments, to create a new instance of Person without supplying an instance of ILogger{Person}. Note that the Person constructor will be supplied new Mock{ILogger{Person}}.Object as a value for ILogger{Person}.

public Person CreateLazy()
  => LazyActivator.CreateLazy<Person>();

The following example uses CreateNull, without arguments, to create a new instance of Person without supplying an instance of ILogger{Person}. Note that the Person constructor will be supplied null as a value for ILogger{Person}.

public Person CreateNull()
  => LazyActivator.CreateNull<Person>();

The following example uses CreateLazy, with arguments, to create a new instance of Person supplying an instance ofMock{ILogger{Person}}. Note that the Person constructor will be supplied loggerMock.Object as a value for ILogger{Person}.

public Person CreateLazyWithMockArgument(Mock<ILogger<Person>> loggerMock)
  => LazyActivator.CreateLazy<Person>(loggerMock);

The following example uses CreateLazy, with arguments, to create a new instance of Person supplying an instance of ILogger{Person}. Note that the Person constructor will be supplied loggerInstance as a value for ILogger{Person}.

public Person CreateLazyWithMockArgument(ILogger<Person> loggerInstance)
  => LazyActivator.CreateLazy<Person>(loggerInstance);

Container Creation

Container Lazy and Mock activation has been added to provide a means of extracted auto loaded construction objects. Please note that whilst this example uses MockActivator this is also present in LazyActivator.

private readonly TestClass _testClass;
private readonly Mock<ILogger<TestClass>> _loggerMock;
private readonly Mock<IWidget> _widgetMock;
private readonly IWidget _widget;

public UnitTest()
{
    var container = MockActivator.CreateLazyContainer<TestClass>();

    _testClass = container.Instance.Object;
    _loggerMock = container.GetArgumentAsMock<ILogger<TestClass>>();
    _widgetMock = container.GetArgumentAsMock<IWidget>();
    _widget = container.GetArgument<IWidget>();
}

Object Proxy

The ObjectProxy class can be used to interact (set/get) private members of a given instance, and can be used to invoke protected/private methods.

Dot separated member access is supported to access members of members recursively. E.g. ObjectProxy.For(person)["Name"."FirstName"]

Static classes can be setup with ObjectProxy.ForStatic to interact with static classes.

Examples

Given the following class:

public class Person
{
  private string Name { set; get; }

  private Person(ILogger<Person> logger, string name)
  {
    Name = name;
  }

  private string GetName()
    => Name;

  private string ToStringFor<T>(T arg)
    => arg.ToString();
}

Creating an instance of Person can be achieved as shown below.

var person = LazyActivator.CreateLazy<Person>("Fred");
// or
var person = LazyActivator.CreateLazy<Person>();

And members can be managed as shown below.

// Get.
var name = ObjectProxy.For(person)["Name"];

// Set.
ObjectProxy.For(person)["Name"] = "Bob";

Methods can be invoked via the proxy with:

var result = person.InvokeMethod<string>("GetName");

For full examples please see end of this file.

Setup Extension Methods

Several extension methods have been provided which enable functional Moq creation (returning Mock{T} to enable chaining) and to setup private/protected members.

Please note that to resovle the extension methods, it may be required to add the following using statement:

using FunctionalDev.MoqHelpers;

Please also note that the extension methods are not the typical .Setup(...).Returns(...) format. For simple method setups the format this library provides is:

.Setup(type => type.MethodName, Expression<Func<InputArgs, ReturnArg>>);

Given an example interface:

public interface IPerson
{
    string SetName(string name);
    int GetAge();
}

The following can be used to set up an IPerson interface.

var person = new Mock<IPerson>()
    .Setup(x => x.SetName, (string name) => "")
    .Setup(x => x.GetAge, () => 25);

Please note that this does not provide any filters on the arguments for methods (such as It.Is<T>(Func<T, bool>) filtering).

Full Example

public abstract record FullExampleObjectBase(ILogger<FullExampleObjectBase> Logger)
{
    public ILogger<FullExampleObjectBase> Logger { get; } = Logger;

    private int _localIntegerValue = 1;

    protected virtual string GetName()
        => nameof(FullExampleObjectBase);

    private void SetLocalIntegerValue(int newValue)
    {
        _localIntegerValue = newValue;
    }

    private int GetLocalIntegerValue()
        => _localIntegerValue;

    private int GenericMethod<T>() => 1;

    public abstract string GetNameAbstract(string arg);
}

public record FullExampleObject(ILogger<FullExampleObjectBase> Logger)
    : FullExampleObjectBase(Logger)
{
    public override string GetNameAbstract(string arg)
        => arg;
}

public static class FullExampleStaticClass
{
    private static void SetStaticValue(string arg) { }
}

public class FullExample
{
    public FullExampleObject CreateFullExampleObject()
        => LazyActivator.CreateLazy<FullExampleObject>();

    public FullExampleObject CreateFullExampleObjectWithArgument()
        => LazyActivator.CreateLazy<FullExampleObject>(Mock.Of<ILogger<FullExampleObjectBase>>());

    public void SetPrivate()
    {
        var proxy = ObjectProxy.For(CreateFullExampleObject());
        proxy["_localIntegerValue"] = 5;
    }

    public void GetPrivate()
    {
        var proxy = ObjectProxy.For(CreateFullExampleObject());
        var value = (int)proxy["_localIntegerValue"];
    }

    private void CallPrivate()
    {
        var proxy = ObjectProxy.For(CreateFullExampleObject());
        proxy.InvokeMethod("SetLocalIntegerValue", 5);
    }

    private void CallPrivateWithReturning()
    {
        var proxy = ObjectProxy.For(CreateFullExampleObject());
        int resultAsInt = proxy.InvokeMethod<int>("GetLocalIntegerValue");
        object resultAsObject = proxy.InvokeMethod("GetLocalIntegerValue");
    }

    private void CallGenericPrivateMethod()
    {
        var proxy = ObjectProxy.For(CreateFullExampleObject());
        int resultAsInt = proxy.InvokeGenericMethod<int>("GenericMethod", new[] { typeof(RecordClass) }, Array.Empty<object>());
        object resultAsObject = proxy.InvokeGenericMethod("GenericMethod", new[] { typeof(RecordClass) }, Array.Empty<object>());
    }

    private void ObjectProxyForStaticClass()
    {
        var proxy = ObjectProxy.ForStatic(typeof(FullExampleStaticClass));
        proxy.InvokeMethod("SetStaticValue", "Hello world");
    }

    private void SetupExtensionMethods()
    {
        MockActivator.CreateLazy<FullExampleObjectBase>()
            // Setting members.
            .Setup(x => x.Logger, Mock.Of<ILogger<FullExampleObjectBase>>())
            // Setting public methods.
            .Setup(x => x.GetNameAbstract, (string arg) => arg + "test")
            // Setting private methods.
            .Setup("GetName", () => "Hello World")
            // Also works for public methods.
            .Setup("GetNameAbstract", (string arg) => arg + "test")
            ;
    }
}

Chaining Calls on ActivatedObject/ActivatedObject{T}

Further changes in containers allows for chaining setups:

var container = LazyActivator.CreateLazyContainer<MyTestClass>()
  .SetupMock<IWidget>(widget => { })
  .SetupMock<ITestObject>(testObject => testObject.Setup(x => x.Name, "Fred"))
  .SetupMock<ITestObject>(testObject => testObject.Setup(x => x.Name, "Frank"))
  .Arguments
      .AddToArgumentCollection(new Mock<ILogger<MyTestClass>>().Object)
      .Parent
  .SetupMock<ILogger<MyTestClass>>(logger =>
  {
      logger.Setup(...)
  });

ChangeLog

3.0.1 | 11/01/2023

• Introduced ChangeLog

3.0.0 | 11/01/2023

• Breaking - ActivatedObject{T} no longer inherits from ActivatedObject, instead a new base class has been introduced (ActivatedObjectBase) which they both share.
• Breaking - The two methods GetArgument and GetArgumentAsMock have been marked as obsolete (and have been moved to ActivatedObjectBase) and may be removed on the next major release.
• Breaking - ActivatedObject no longer has a property called InstanceUnTyped it has been renamed to Instance with a type of object, mirroring the property on ActivatedObject{T} named Instance of type T (class generic type).
• Added chaining calls to ActivatedObjects to enable setting up of mocks inline/chained.
• Rewrite on the argument logic allowing custom injection of objects after instantiation.
• Updated all ILogger{T} extension methods to also support ILogger.
• Logger/Logger{T}.Unwrap() now returns the exception, if provided on invocations.