adrianiftode / FluentAssertions.Web

FluentAssertions.Web

This is a FluentAssertions extension over the HttpResponseMessage object.

It provides assertions specific to HTTP responses and outputs rich erros messages when the tests fail, so less time with debugging is spent.

[Fact]
public async Task Post_ReturnsOk()
{
    // Arrange
    var client = _factory.CreateClient();

    // Act
    var response = await client.PostAsync("/api/comments", new StringContent(@"{
              ""author"": ""John"",
              ""content"": ""Hey, you...""
            }", Encoding.UTF8, "application/json"));

    // Assert
    response.Should().Be200Ok();
}

Why?

Writing tests for ASP.NET Core APIs and or any APIs by using the HttpClient classes leads to some repetitive code and also often to an incomplete one. When the test fails, the developer needs to debug the test in order to assess the failure reason, as the test itself did not usually consider what happens in this case.

Thus this library solves two problems:

Focus on the Assert part and not on the HttpClient related APIs, neither on the response deserialization

Once the response is ready you'll want to assert it. With first level properties like StatusCode is somehow easy, especially with FluentAssertions, but often we need more, like to deserialize the content into an object of a certain type and then to Assert it. Or to simply assert something about the response content itself. Soon duplication code occurs and the urge to reduce it is just the next logical step.

Debugging failed tests interrupts the programmer's flow state

When a test is failing, the following actions are taken most of the time:

• attach the debugger to the line containing var response = await client..
• debug the failing test
• add an Watch for response.Content.ReadAsStringAsync().Result and see the actual response content

And this can be avoided, if the Test Detail Summary contains the request and the response information, providing a similar experience as with an HTTP interceptor like Fiddler.

FluentAssertions.Web Examples

• Asserting that the response content of a HTTP POST request is equivalent to a certain object

[Fact]
public async Task Post_ReturnsOkAndWithContent()
{
    // Arrange
    var client = _factory.CreateClient();

    // Act
    var response = await client.PostAsync("/api/comments", new StringContent(@"{
                ""author"": ""John"",
                ""content"": ""Hey, you...""
            }", Encoding.UTF8, "application/json"));

    // Assert
    response.Should().BeAs(new
    {
        Author = "John",
        Content = "Hey, you..."
    });
}

• Asserting that the response is 200 OK and the content is like an array of specific objects:

[Fact]
public async Task Get_Returns_Ok_With_CommentsList()
{
    // Arrange
    var client = _factory.CreateClient();

    // Act
    var response = await client.GetAsync("/api/comments");

    // Assert
    response.Should().Be200Ok().And.BeAs(new[]
    {
        new { Author = "Adrian", Content = "Hey" }
    });
}

• Asserting that the response is a HTTP 400 BadRequest and contains a single error message

[Fact]
public async Task Post_WithNoAuthorButWithContent_ReturnsBadRequestWithAnErrorMessageRelatedToAuthorOnly()
{
    // Arrange
    var client = _factory.CreateClient();

    // Act
    var response = await client.PostAsync("/api/comments", new StringContent(@"{
                                    ""content"": ""Hey, you...""
                                }", Encoding.UTF8, "application/json"));

    // Assert
    response.Should().Be400BadRequest()
        .And.OnlyHaveError("Author", "The Author field is required.");
}

• Asserting the response content once deserialized into a strongly typed object it satisfies a certain assertion

[Fact]
public async Task Get_Returns_Ok_With_CommentsList_With_TwoUniqueComments()
{
    // Arrange
    var client = _factory.CreateClient();

    // Act
    var response = await client.GetAsync("/api/comments");

    // Assert
    response.Should().Satisfy<IEnumerable<Comment>>(model => 
            model.Should().HaveCount(2).And.OnlyHaveUniqueItems(c => c.CommentId));
}

• Asserting the response content once deserialized into a anonymous object it satisfies a certain assertion

[Fact]
public async Task Get_WithCommentId_Returns_A_NonSpam_Comment()
{
    // Arrange
    var client = _factory.CreateClient();

    // Act
    var response = await client.GetAsync("/api/comments/1");

    // Assert
    response.Should().Satisfy(givenModelStructure: new
    {
        Author = default(string),
        Content = default(string)
    }, assertion: model =>
        {
            model.Author.Should().NotBe("I DO SPAM!");
            model.Content.Should().NotContain("BUY MORE");
        });
}

• Asserting the response has a header like X-Correlation-ID header of application/json; charset=utf-8

[Fact]
public async Task Get_Should_Contain_a_Header_With_Correlation_Id()
{
    // Arrange
    var client = _factory.CreateClient();

    // Act
    var response = await client.GetAsync("/api/values");

    // Assert
    response.Should().HaveHeader("X-Correlation-ID").And.Match("*-*", "we want to test the correlation id is a Guid like one");
}

Many more examples can be found in the Samples projects and in the Specs files from the FluentAssertions.Web.Tests project

Optional Global Configuration

Deserialization

System.Text.Json

By default System.Text.Json is used to deserialize the response content. The related System.Text.Json.JsonSerializerOptions used to configure the serializer is accessible via the SystemTextJsonSerializerConfig.Options static field from FluentAssertions.Web. So if you want to make the serializer case sensitive, then the related setting is changed like this:

SystemTextJsonSerializerConfig.Options.PropertyNameCaseInsensitive = false; 

The change must be done before the test is run and this depends on the testing framework. Check the NewtonsoftSerializerTests from this repo to see how it can be done with xUnit.

Newtonsoft.Json

The serializer itself is replaceable, so you can implement your own, by implementing the ISerialize interface. The serializer is shipped via the FluentAssertions.Web.Serializers.NewtonsoftJson package.

To set the default serializer to Newtonsoft.Json one, use the following configuration:

FluentAssertionsWebConfig.Serializer = new NewtonsoftJsonSerializer();

The related Newtonsoft.Json.JsonSerializerSetttings used to configure the Newtonsoft.Json serializer is accesible via the NewtonsoftJsonSerializerConfig.Options static field. So if you want to add a custom converter, then the related setting is changed like this:

NewtonsoftJsonSerializerConfig.Options.Converters.Add(new YesNoBooleanJsonConverter());

Full API

The HttpResponsesMessage assertions from FluentAssertions vs. FluentAssertions.Web

In the 6.4.0 release the main library introduced a set of related assertions: BeSuccessful, BeRedirection, HaveClientError, HaveServerError, HaveError, HaveStatusCode, NotHaveStatusCode.

This library can still be used with FluentAssertions and it did not become obsoleted, not only because of the rich set of assertions, but also for the comprehensive output messages that are displayed when the test fails, feature that is not present in the main library, but in FluentAssertions.Web one.

FluentAssertions.Web vs FluentAssertions.Mvc vs FluentAssertions.Http

FluentAssertions.Web does not extend the ASP.NET Core Controllers assertions, if you are looking for that, then consider FluentAssertions.Mvc.

When FluentAssertions.Web was created, FluentAssertions.Http also existed at the time, solving the same problem when considering the asserting language. Besides the extra assertions added by FluentAssertions.Web, an important effort is put by this library on what happens when a test fails.