Add FluentAssertions nuget package to test projects

[filzrev]

This PR add FluentAssertions NuGet package to test projects.

Background
Currently xUnit's assertions are used for unit tests.
I want to write unit test assertions with FluentAssertions assertion helpers. when adding new tests.

FluentAssertions is published as Apache License 2.0 and widely used in org:dotnet repositories
So I thought there is no major obstacles to adapt this assertion library.

If these changes aren't accepted. feel free to close this PR.

[yufeih]

I don't have a lot of personal experience with FluentAssertions. Are there any benefits you see of adopting it except for syntax differences, such as things xunit assertions cannot do easily, or better diagnostic messages?

I'm leaning towards keeping one way of doing things unless there is enough merit where we can say the new approach is the new default.

[filzrev]

Thanks for your reply.

such as things xunit assertions cannot do easily, or better diagnostic messages?

More readable diagnostic message.

Basically FluentAssertions output more readable diagnostic message.
Because It expose variety of APIs to write assertion.

For example.

1. FluentAssertions assertion

var results = new[] { "Dummy" };
results.Should().HaveCount(0);

Message:

Expected results to contain 0 item(s), but found 1: {"Dummy"}.

2. xUnit.NET assertion

var results = new[] { "Dummy" };
Assert.True(results.Length== 0);

Message:

Assert.True() Failure
Expected: True
Actual: False

It can be confirmed FluentAssertions output contains more assertion context information.

And FluentAssertions have Subject Identification feature.
It output what's tested* information when assertion failed.
This feature is useful when writing assertion for object tree.

For Example

Original code

docfx/test/docfx.Tests/MetadataCommandTest.cs

Line 356 in 2fc5c76

Assert.Equal("SubBar", tocViewModel[2].Items[0].Name);

FluentAssertionsassertion

> tocViewModel[2].Items[0].Uid.Should().Be("SubBar");

Message:

Expected tocViewModel[2].Items[0].Name to be "SubBarDummy" with a length of 9, but "SubBar" has a length of 6, differs near "r" (index 5).

---

FluentAssertions features that can't do easily with xunit assertions.

Below is an excerpt features that I want to use when writing unit tests.

AssertionScope

This feature is useful when writing following tests.

1. Writing multiple assertions in single unit test.
2. Writing test to multiple items with foreach enumeration.

Example of 1.

• MetadataCommandTest.cs

Example of 2.

using var scope = new AssertionScope();
foeach(var path in Directory.EnumerateFiles("TestData"))
{
    // Validate file content using fluent assertins.
}

Basically this type of test should be written using xUnit's InlineData or TheoryData.
But sometimes it's useful writing tests with foreach loop.

Object Graph Comparison

This feature is useful for POCO/DTO class (with no IEquatable) data comparison.

// Act
var actual = JsonUtility.Deserialize<BuildJsonConfig>("<path>")

// Assert
actual.Should().BeEquivalent(new BuildJsonConfig{
  // Set properties to assert.
});

Extensibility

It can write custom assertion logics for specific types (e.g. Manifest/OutputFileInfo,DirectoryInfo etc.)
It simplify test assertion codes dramatically. and it can share assertion logics across tests.

[yufeih]

Looks great! I like object graph comparison and improved diagnostics.