DepenMock.XUnit.V3 4.0.0

DepenMock.XUnit.V3

XUnit v3 integration for DepenMock — a C# testing library that automates mock creation for your System Under Test (SUT) dependencies.

Installation

Install this package alongside a DepenMock mock-framework package:

dotnet add package DepenMock.XUnit.V3
dotnet add package DepenMock.Moq          # or DepenMock.NSubstitute

Setting Up the Test Container

The base classes require an IMockFactory to be passed through the constructor. The recommended approach is to define a project-level base class once that wires up your chosen mock factory, so individual test classes need no constructor boilerplate.

Recommended: project-level base class

Define these once in your test project and inherit from them everywhere:

public abstract class TestByAbstraction<TType, TInterface>
    : BaseTestByAbstraction<TType, TInterface>(new MoqMockFactory())
    where TType : class, TInterface;

public abstract class TestByType<TType>
    : BaseTestByType<TType>(new MoqMockFactory())
    where TType : class;

Then each test class simply inherits with no constructor required:

public class DeskBookingRequestProcessorTests
    : TestByAbstraction<DeskBookingRequestProcessor, IDeskBookingRequestProcessor>
{
    // Your test methods here
}

Alternative: pass the factory directly

If you prefer not to define a shared base class, pass the factory explicitly per test class:

public class DeskBookingRequestProcessorTests
    : BaseTestByAbstraction<DeskBookingRequestProcessor, IDeskBookingRequestProcessor>
{
    public DeskBookingRequestProcessorTests()
        : base(new MoqMockFactory()) { }
}

public class AccountControllerTests : BaseTestByType<AccountController>
{
    public AccountControllerTests()
        : base(new MoqMockFactory()) { }
}

Swap MoqMockFactory for NSubstituteMockFactory to use NSubstitute instead.

Creating the System Under Test (SUT)

Call ResolveSut() as the final step of your arrange phase, after any mock setup.

var sut = ResolveSut();

Creating Mock Data

Create<T>()

The Create<T> method generates a single instance of the specified type.

// Creates a random string in the format of a guid i.e "fe06998d-aec1-4808-8968-d8f37024a294"
var name = Container.Create<string>();

// Creates a random integer greater than 0
var id = Container.Create<int>();

// Creates a boolean value set to true
var isEnabled = Container.Create<bool>();

// Creates a random date set in the future
var startDate = Container.Create<DateTime>();

// Creates an instance of the class MyObj
var myObjInstance = Container.Create<MyObj>();

// Creates a list of strings. NOTE: Use CreateMany for generating lists.
var randomStrings = Container.Create<List<string>>();

CreateMany<T>(int? numberOfInstances)

The CreateMany<T> method generates a list of instances of the specified type. By default it creates three items, but you can customise the count with the numberOfInstances parameter.

// Creates a list of strings
var randomStrings = Container.CreateMany<string>();

// Creates a list of random integers
var randomNumbers = Container.CreateMany<int>();

// Creates a list of boolean values. All values will be set to true.
var allTrueValues = Container.CreateMany<bool>();

// Creates a list of random dates. This example creates a list of 5 random dates.
var randomDates = Container.CreateMany<DateTime>(5);

// Creates a list of addresses set to random values
var addressList = Container.CreateMany<Address>();

Build<T>()

The Build<T> method provides a builder pattern for creating objects with specific values rather than using all auto-generated data.

var deskBookingResult = Container
    .Build<DeskBookingResult>()
    .Without(x => x.DeskBookingId) // DeskBookingId will be set to null
    .With(x => x.Code, DeskBookingResultCode.Success)
    .With(x => x.FirstName, request.FirstName)
    .With(x => x.LastName, request.LastName)
    .With(x => x.Email, request.Email)
    .With(x => x.Date, request.Date)
    .Create();

Creating Mock Dependencies

DepenMock automatically creates mocks for all unregistered dependencies using the factory you provided. Call ResolveMock<T>() to get a reference to a mock, then unwrap it with the extension method for your chosen framework (AsMoq() or AsNSubstitute()) to access stub and spy APIs.

See DepenMock.Moq or DepenMock.NSubstitute for framework-specific stub and spy examples.

Testing Logging

DepenMock provides a ListLogger and automatically injects it as a dependency for your tests.

Logger.ErrorLogs().AssertContains($"Correlation Id: {correlationId}");

// Accessing logs by level directly
Logger.Logs[LogLevel.Error]
Logger.Logs[LogLevel.Critical]
Logger.Logs[LogLevel.Warning]
Logger.Logs[LogLevel.Information]

Outputting Logs to Test Results

xUnit v3 supports automatically outputting log messages to the test runner's output window using the LogOutputAttribute. This is useful for debugging tests or understanding what happened during test execution.

Method-level LogOutput

using DepenMock.Attributes;

[Fact]
[LogOutput(LogOutputTiming.Always)]
public void TestWithLogOutput_ShouldOutputLogs()
{
    // Your test code here
    // Logs will be output to the test runner output window
}

Class-level LogOutput

using DepenMock.Attributes;

[LogOutput(LogOutputTiming.Always)]
public class MyTestClass : BaseTestByType<MyService>
{
    public MyTestClass() : base(new MoqMockFactory()) { }

    [Fact]
    public void MyTest()
    {
        // All tests in this class will output logs
    }
}

LogOutputTiming Options

• LogOutputTiming.Always - Always output logs regardless of test result
• LogOutputTiming.OnSuccess - Output logs only when the test passes
• LogOutputTiming.OnFailure - Output logs only when the test fails

Note: The LogOutputAttribute only works with xUnit v3. xUnit v2 does not support automatic log output due to framework limitations. For xUnit v2 tests, inspect logs directly in your test assertions using Logger.Logs[LogLevel.Information] etc.

Extending Fixture Customization

Override AddContainerCustomizations to register custom ISpecimenBuilder instances or otherwise control how objects are created.

public class MyTests : BaseTestByType<MyType>
{
    public MyTests() : base(new MoqMockFactory()) { }

    protected override void AddContainerCustomizations(Container container)
    {
        container.AddCustomizations(new MyCustomSpecimenBuilder());
    }
}

You can add as many custom builders as you need:

container.AddCustomizations(new MyBuilder1(), new MyBuilder2());

Sample Project

Explore the sample project, DeskBooker.Core, which includes example unit tests for NUnit, XUnit, and MSTest to help you get started with DepenMock.