# FluentAssertions — Readable Test Assertions for .NET

> FluentAssertions provides a rich set of extension methods for writing expressive, self-documenting assertions in .NET unit tests, with clear failure messages that tell you exactly what went wrong.

## Install

Save in your project root:

# FluentAssertions — Readable Test Assertions for .NET

## Quick Use
```bash
dotnet add package FluentAssertions
```
```csharp
using FluentAssertions;
string name = "FluentAssertions";
name.Should().StartWith("Fluent").And.EndWith("Assertions");
var list = new[] { 1, 2, 3 };
list.Should().HaveCount(3).And.Contain(2);
DateTime.Now.Should().BeAfter(DateTime.Today);
```

## Introduction
FluentAssertions replaces cryptic `Assert.AreEqual(expected, actual)` calls with natural-language expressions like `actual.Should().Be(expected)`. When a test fails, the error message describes the mismatch in detail, saving time spent debugging why a test broke.

## What FluentAssertions Does
- Provides fluent `.Should()` assertions for strings, numbers, collections, dates, exceptions, and more
- Generates detailed failure messages showing expected vs. actual values with context
- Supports object graph comparison for deep equality checks between complex objects
- Asserts on async operations, events, and execution time
- Works with xUnit, NUnit, MSTest, and any .NET test framework

## Architecture Overview
FluentAssertions is a pure .NET library that extends types with `.Should()` via extension methods. Each assertion returns a typed assertion object that chains further conditions with `.And`. When an assertion fails, it throws a framework-appropriate exception (xUnit's `XunitException`, NUnit's `AssertionException`, etc.) detected automatically at runtime. The library targets .NET Standard 2.0 and .NET 6+.

## Self-Hosting & Configuration
- Install via NuGet: `dotnet add package FluentAssertions`
- No additional configuration needed for most use cases
- Auto-detects the test framework (xUnit, NUnit, MSTest) at runtime
- Customize assertion behavior with `AssertionOptions.AssertEquivalencyUsing()`
- Add `FluentAssertions.Analyzers` for Roslyn-based best practice suggestions

## Key Features
- Natural-language assertion syntax that reads like specifications
- Structural equivalency assertions for deep object comparison
- Collection assertions: ContainSingle, BeInAscendingOrder, HaveElementAt, OnlyContain
- Exception assertions: `.Should().Throw<T>().WithMessage("...")` and async variants
- Execution time assertions: `.Should().CompleteWithin(TimeSpan.FromSeconds(1))`

## Comparison with Similar Tools
- **Assert (xUnit/NUnit/MSTest)** — built-in but terse; FluentAssertions adds readability and better failure messages
- **Shouldly** — similar fluent syntax; FluentAssertions has broader type coverage and deeper object comparison
- **NFluent** — fluent assertions with a different chaining style; smaller community
- **Verify (verify-tests)** — snapshot-based assertions; FluentAssertions is value-based comparison
- **Chai (JavaScript)** — JS fluent assertion library; FluentAssertions brings the same approach to .NET

## FAQ
**Q: Does FluentAssertions work with xUnit, NUnit, and MSTest?**
A: Yes. It auto-detects the test framework and throws the appropriate exception type for correct reporting.

**Q: How do I compare two complex objects?**
A: Use `actual.Should().BeEquivalentTo(expected)` for structural comparison that checks property values recursively, ignoring property order.

**Q: Can I customize which properties are compared?**
A: Yes. Pass options to `BeEquivalentTo`: `actual.Should().BeEquivalentTo(expected, o => o.Excluding(x => x.Id))`.

**Q: Is FluentAssertions free?**
A: Yes. It is released under the Apache 2.0 license and free for all use.

## Sources
- https://github.com/fluentassertions/fluentassertions
- https://fluentassertions.com

---
Source: https://tokrepo.com/en/workflows/asset-0e9271c0
Author: AI Open Source