PosInformatique.Logging.Assertions 1.0.1

The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org. Prefix Reserved
There is a newer version of this package available.
See the version list below for details.
dotnet add package PosInformatique.Logging.Assertions --version 1.0.1
NuGet\Install-Package PosInformatique.Logging.Assertions -Version 1.0.1
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="PosInformatique.Logging.Assertions" Version="1.0.1" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add PosInformatique.Logging.Assertions --version 1.0.1
#r "nuget: PosInformatique.Logging.Assertions, 1.0.1"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install PosInformatique.Logging.Assertions as a Cake Addin
#addin nuget:?package=PosInformatique.Logging.Assertions&version=1.0.1

// Install PosInformatique.Logging.Assertions as a Cake Tool
#tool nuget:?package=PosInformatique.Logging.Assertions&version=1.0.1

PosInformatique.Logging.Assertions

PosInformatique.Logging.Assertions is a library to mock and assert easily the logs generated by the ILogger interface.

Installing from NuGet

The PosInformatique.Logging.Assertions library is available directly on the Nuget official website.

To download and install the library to your Visual Studio unit test projects use the following NuGet command line

Install-Package PosInformatique.Logging.Assertions

How it is work?

Imagine that you have the following class which contains various log:

public class CustomerManager
{
    private readonly IEmailProvider emailProvider;

    private readonly ILogger<CustomerManager> logger;

    public CustomerManager(IEmailProvider emailProvider, ILogger<CustomerManager> logger)
    {
        this.emailProvider = emailProvider;
        this.logger = logger;
    }

    public async Task SendEmailAsync(int id, string name)
    {
        this.logger.LogInformation($"Starting to send an email to the customer '{name}'");

        using (this.logger.BeginScope(new { Id = id }))
        {
            try
            {
                this.logger.LogDebug($"Call the SendAsync() method");

                await this.emailProvider.SendAsync(name);

                this.logger.LogDebug($"SendAsync() method has been called.");

                this.logger.LogInformation($"Email provider has been called.");
            }
            catch (Exception exception)
            {
                this.logger.LogError(exception, "Unable to send the email !");
            }
        }
    }
}

public interface IEmailProvider
{
    Task SendAsync(string name);
}

As a good developer (like me), who always do unit tests with 100% of code coverage, you have to write the unit tests to test the SendEmailAsync() method and mock the IEmailProvider and ILogger<T> interfaces with your favorite mocking library. (Moq for me...).

Some developers consider that log information should not be test with unit tests... 😆 😆 ILogger interface and his methods calls should be test as any normal code and specially the scope to be sure we inject the right data. Most often, developpers discover that their own logs don't log things correctly in production environments... 😆 😆

So the unit test to write for the previous example should look like something like that:

[Fact]
public async Task SendEmailAsync()
{
    // Arrange
    var emailProvider = new Mock<IEmailProvider>(MockBehavior.Strict);
    emailProvider.Setup(ep => ep.SendAsync("Gilles TOURREAU"))
        .Returns(Task.CompletedTask);

    var logger = new Mock<ILogger<CustomerManager>>(MockBehavior.Strict);
    logger.Setup(l => l.Log(LogLevel.Information, "Starting to send an email to the customer 'Gilles TOURREAU'", ..., ..., ... )) // WTF???
        ...
    logger.Setup(l => l.BeginScope<...>(...))   // WTF???

    var manager = new CustomerManager(emailProvider.Object, logger.Object);

    // Act
    await manager.SendEmailAsync(1234, "Gilles TOURREAU");

    // Assert
    emailProvider.VerifyAll();
    logger.VerifyAll();
}

As your can see, it is very hard to mock the Log() method of the ILogger interface which have the following signature:

void Log<TState>(LogLevel logLevel, EventId eventId, TState state, Exception? exception, Func<TState, Exception?, string> formatter)

And also to check the scope usage with the ILogger interface it can be hard !

The PosInformatique.Logging.Assertions library allows the developpers to mock the ILogger easily and setup the sequence of the expected logs using a fluent style code. For the previous example, this is how the unit test look like for the previous example.

[Fact]
public async Task SendEmailAsync()
{
    // Arrange
    var emailProvider = new Mock<IEmailProvider>(MockBehavior.Strict);
    emailProvider.Setup(ep => ep.SendAsync("Gilles TOURREAU"))
        .Returns(Task.CompletedTask);

    var logger = new LoggerMock<CustomerManager>();
    logger.SetupSequence()
        .LogInformation("Starting to send an email to the customer 'Gilles TOURREAU'")
        .BeginScope(new { Id = 1234 })
            .LogDebug("Call the SendAsync() method")
            .LogDebug("SendAsync() method has been called.")
            .LogInformation("Email provider has been called.")
        .EndScope();

    var manager = new CustomerManager(emailProvider.Object, logger.Object);

    // Act
    await manager.SendEmailAsync(1234, "Gilles TOURREAU");

    // Assert
    emailProvider.VerifyAll();
    logger.VerifyLogs();
}

😍 😍 Sexy isn't it??? The unit test is more easy to read and write!

Do not forget to call the VerifyLogs() at the end of your unit test like a VerifyAll() call with the Moq library. The VerifyLogs() will check that all methods setup (Arrange) are called by the code under test (Act).

Do not hesitate to use the indentation to make the fluent code more readable specially when using nested scopes.

For example to check nested log scopes write the following code with the following indented code:

var logger = new LoggerMock<CustomerManager>();
logger.SetupSequence()
    .LogInformation("Starting to send an email to the customer 'Gilles TOURREAU'")
    .BeginScope(new { Id = 1234 })
        .BeginScope(new { Name = "Gilles" })
            .LogError("Error in the scope 1234 + Gilles")
        .EndScope()
        .LogInformation("Log between the 2 nested scopes.")
        .BeginScope(new { Name = "Aiza" })
            .LogError("Error in the scope 1234 + Aiza")
        .EndScope()
    .EndScope();

Test the error logs with an exception.

To test an Exception with specified in the LogError() method of the ILogger interface use the WithException() method an set the instance expected:

[Fact]
public async Task SendEmailAsync_WithException()
{
    // Arrange
    var theException = new FormatException("An exception");

    var emailProvider = new Mock<IEmailProvider>(MockBehavior.Strict);
    emailProvider.Setup(ep => ep.SendAsync("Gilles TOURREAU"))
        .ThrowsAsync(theException);

    var logger = new LoggerMock<CustomerManager>();
    logger.SetupSequence()
        .LogInformation("Starting to send an email to the customer 'Gilles TOURREAU'")
        .BeginScope(new { Id = 1234 })
            .LogDebug("Call the SendAsync() method")
            .LogError("Unable to send the email !")
                .WithException(theException)
        .EndScope();

    var manager = new CustomerManager(emailProvider.Object, logger.Object);

    // Act
    await manager.Invoking(m => m.SendEmailAsync(1234, "Gilles TOURREAU"))
        .Should().ThrowExactlyAsync<FormatException>();

    // Assert
    emailProvider.VerifyAll();
    logger.VerifyLogs();
}

In the case the exception is throw by the code (It is mean the exception is not produced by the unit test during the Arrange phase), use the version with a delegate to check the content of the Exception:

var logger = new LoggerMock<CustomerManager>();
logger.SetupSequence()
    .LogInformation("Starting to send an email to the customer 'Gilles TOURREAU'")
    .BeginScope(new { Id = 1234 })
        .LogDebug("Call the SendAsync() method")
        .LogError("Unable to send the email !")
            .WithException(e =>
            {
                e.Message.Should().Be("An exception");
                e.InnerException.Should().BeNull();
            })
    .EndScope();

Assertion fail messages

The PosInformatique.Logging.Assertions library try to make the assert fail messages the most easy to understand for the developers:

Assertion Failed Too Many Calls Assertion Missing Logs

Library dependencies

The PosInformatique.Logging.Assertions library is depend of the FluentAssertions library for internal assertions which is more pretty to read in the exceptions message.

Also, the PosInformatique.Logging.Assertions library use the internal FluentAssertions unit test provider engine detection to throw an exception (when an assertion is false) depending of the engine used to execute the unit test. For example, XunitException if the unit test engine used is Xunit.

Product Compatible and additional computed target framework versions.
.NET net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.5.1 121 3/15/2024
1.5.1-rc.1 50 3/15/2024
1.5.0 197 2/26/2024
1.5.0-rc.2 65 2/22/2024
1.5.0-rc.1 67 2/19/2024
1.4.0 617 11/30/2023
1.3.0 179 10/24/2023
1.2.0 161 10/19/2023
1.1.0 124 10/16/2023
1.0.3 108 10/16/2023
1.0.2 151 10/13/2023
1.0.1 130 10/11/2023
1.0.0 124 10/11/2023

1.0.1
     - Various fixes for the NuGet package description.

     1.0.0
     - Initial version