dotnet-testing-awesome-assertions-guide

Original：🇨🇳 Chinese

Translated

Skill for writing fluent and readable test assertions with AwesomeAssertions. Use it when you need to write clear assertions, compare objects, validate collections, or handle complex comparisons. Covers complete APIs such as Should(), BeEquivalentTo(), Contain(), ThrowAsync(), etc. Keywords: assertions, awesome assertions, fluent assertions, Should(), Be(), BeEquivalentTo, Contain, ThrowAsync, NotBeNull, object comparison, collection validation, exception assertion, AwesomeAssertions, FluentAssertions, fluent syntax

1installs

Sourcekevintsengtw/dotnet-testing-agent-skills

Added on2026-02-07

NPX Install

npx skill4agent add kevintsengtw/dotnet-testing-agent-skills dotnet-testing-awesome-assertions-guide

SKILL.md Content (Chinese)

View Translation Comparison →

AwesomeAssertions Fluent Assertions Guide

This skill provides a complete guide to writing high-quality test assertions with AwesomeAssertions, covering basic syntax, advanced techniques, and best practices.

Use Cases

Use this skill when you need to perform the following tasks:

Write clear, highly readable test assertions
Compare complex objects or collection contents
Verify exception throwing and messages
Perform test validation using fluent syntax (Should/Be/Contain)
Replace native Assert with AwesomeAssertions

About AwesomeAssertions

AwesomeAssertions is a community fork of FluentAssertions, licensed under Apache 2.0, completely free with no commercial usage restrictions.

Core Features

✅ Completely Free: Apache 2.0 license, suitable for commercial projects
🔗 Fluent Syntax: Supports method chaining in natural language style
📦 Rich Assertions: Covers various types including objects, collections, strings, numbers, exceptions, etc.
💬 Excellent Error Messages: Provides detailed and easy-to-understand failure information
⚡ High Performance: Optimized implementation ensures test execution efficiency
🔧 Extensible: Supports custom Assertions methods

Relationship with FluentAssertions

AwesomeAssertions is a community fork of FluentAssertions. The main differences are:

Item	FluentAssertions	AwesomeAssertions
License	Paid for commercial projects	Apache 2.0 (completely free)
Namespace	`FluentAssertions`	`AwesomeAssertions`
API Compatibility	Original version	Highly compatible
Community Support	Officially maintained	Community maintained

Installation and Configuration

NuGet Package Installation

bash

# .NET CLI
dotnet add package AwesomeAssertions

# Package Manager Console
Install-Package AwesomeAssertions

csproj Configuration (Recommended)

xml

<ItemGroup>
  <PackageReference Include="AwesomeAssertions" Version="9.1.0" PrivateAssets="all" />
</ItemGroup>

Namespace Reference

csharp

using AwesomeAssertions;
using Xunit;

Core Assertions Syntax

All Assertions start with

.Should()

, paired with fluent method chaining.

Category	Common Methods	Description
Object	`NotBeNull()` , `BeOfType<T>()` , `BeEquivalentTo()`	Null value, type, and equality checks
String	`Contain()` , `StartWith()` , `MatchRegex()` , `BeEquivalentTo()`	Content, pattern, and case-insensitive comparison
Number	`BeGreaterThan()` , `BeInRange()` , `BeApproximately()`	Comparison, range, and floating-point precision
Collection	`HaveCount()` , `Contain()` , `BeEquivalentTo()` , `AllSatisfy()`	Quantity, content, order, and condition checks
Exception	`Throw<T>()` , `NotThrow()` , `WithMessage()` , `WithInnerException()`	Exception type, message, and nested exception checks
Async	`ThrowAsync<T>()` , `CompleteWithinAsync()`	Async exception and completion validation

📖 For complete syntax examples and code, refer to references/core-assertions-syntax.md

Advanced Technique: Complex Object Comparison

Use

BeEquivalentTo()

with

options

for deep object comparison:

Exclude Properties:
```
options.Excluding(u => u.Id)
```
— Exclude auto-generated fields

Dynamic Exclusion:

options.Excluding(ctx => ctx.Path.EndsWith("At"))

— Exclude by pattern

Cyclic References:

options.IgnoringCyclicReferences().WithMaxRecursionDepth(10)

Advanced Technique: Custom Assertions Extension

Create domain-specific extension methods such as

product.Should().BeValidProduct()

, and reusable exclusion extensions like

ExcludingAuditFields()

.

Refer to templates/custom-assertions-template.cs for complete implementation.

📖 For complete examples, refer to references/complex-object-assertions.md

Performance Optimization Strategies

Large Datasets: First use
```
HaveCount()
```
to quickly check quantity, then validate by sampling (avoid full
```
BeEquivalentTo
```
)
Selective Comparison: Use anonymous objects +
```
ExcludingMissingMembers()
```
to only validate key properties

csharp

// Selective property comparison — only validate key fields
order.Should().BeEquivalentTo(new
{
    CustomerId = 123,
    TotalAmount = 999.99m,
    Status = "Pending"
}, options => options.ExcludingMissingMembers());

Best Practices and Team Standards

Test Naming Conventions

Follow the

Method_Scenario_ExpectedResult

pattern (e.g.,

CreateUser_ValidEmail_ShouldReturnEnabledUser

).

Error Message Optimization

Add a

because

string in assertions to provide clear failure context:

csharp

result.IsSuccess.Should().BeFalse("because negative payment amounts are not allowed");

Using AssertionScope

Use

AssertionScope

to collect multiple failure messages and display all issues at once:

csharp

using (new AssertionScope())
{
    user.Should().NotBeNull("User creation should not fail");
    user.Id.Should().BeGreaterThan(0, "User should have valid ID");
    user.Email.Should().NotBeNullOrEmpty("Email is required");
}

Common Scenarios and Solutions

Scenario	Key Techniques
API Response Validation	`BeEquivalentTo()` + `Including()` for selective comparison
Database Entity Validation	`BeEquivalentTo()` + `Excluding()` to exclude auto-generated fields
Event Validation	Capture events via subscription and validate properties one by one

📖 For complete code examples, refer to references/common-scenarios.md

Troubleshooting

Issue 1: BeEquivalentTo fails but objects look identical

Cause: May contain auto-generated fields or timestamps

Solution:

csharp

// Exclude dynamic fields
actual.Should().BeEquivalentTo(expected, options => options
    .Excluding(x => x.Id)
    .Excluding(x => x.CreatedAt)
    .Excluding(x => x.UpdatedAt)
);

Issue 2: Failure due to different collection order

Cause: Different collection order

Solution:

csharp

// Use BeEquivalentTo to ignore order
actual.Should().BeEquivalentTo(expected); // Does not check order

// Or explicitly specify that order needs to be checked
actual.Should().Equal(expected); // Checks order

Issue 3: Floating-point comparison failure

Cause: Floating-point precision issues

Solution:

csharp

// Use precision tolerance
actualValue.Should().BeApproximately(expectedValue, 0.001);

When to Use This Skill

Suitable Scenarios

✅ When writing unit tests or integration tests ✅ When you need to validate complex object structures ✅ When comparing API responses or database entities ✅ When you need clear failure messages ✅ When establishing domain-specific testing standards

Unsuitable Scenarios

❌ Performance testing (use dedicated benchmarking tools) ❌ Load testing (use K6, JMeter, etc.) ❌ UI testing (use Playwright, Selenium)

Collaboration with Other Skills

With unit-test-fundamentals

First use

unit-test-fundamentals

to build the test structure, then use this skill to write assertions:

csharp

[Fact]
public void Calculator_Add_TwoPositiveNumbers_ShouldReturnSum()
{
    // Arrange - Follow 3A Pattern
    var calculator = new Calculator();
    
    // Act
    var result = calculator.Add(2, 3);
    
    // Assert - Use AwesomeAssertions
    result.Should().Be(5);
}

With test-naming-conventions

Use the naming conventions from

test-naming-conventions

paired with assertions from this skill:

csharp

[Fact]
public void CreateUser_ValidData_ShouldReturnEnabledUser()
{
    var user = userService.CreateUser("test@example.com");
    
    user.Should().NotBeNull()
        .And.BeOfType<User>();
    user.IsActive.Should().BeTrue();
}

With xunit-project-setup

Install and use AwesomeAssertions in projects set up with

xunit-project-setup

.

Reference Resources

Original Articles

This skill is extracted from the "Old-School Software Engineer's Test Training - 30-Day Challenge" series:

Day 04 - AwesomeAssertions Basic Application and Practical Skills
- Ironman Article: https://ithelp.ithome.com.tw/articles/10374188
- Sample Code: https://github.com/kevintsengtw/30Days_in_Testing_Samples/tree/main/day04
Day 05 - AwesomeAssertions Advanced Techniques and Complex Scenario Applications
- Ironman Article: https://ithelp.ithome.com.tw/articles/10374425
- Sample Code: https://github.com/kevintsengtw/30Days_in_Testing_Samples/tree/main/day05

Official Resources

AwesomeAssertions GitHub: https://github.com/AwesomeAssertions/AwesomeAssertions
AwesomeAssertions Official Documentation: https://awesomeassertions.org/

Summary

AwesomeAssertions provides a powerful and readable assertion syntax, which is an important tool for writing high-quality tests. Through:

Fluent Syntax: Makes test code more readable
Rich Assertions: Covers various data types
Custom Extensions: Build domain-specific assertions
Performance Optimization: Handle large dataset scenarios
Completely Free: Apache 2.0 license with no commercial restrictions

Remember: Good assertions not only validate results but also clearly express expected behavior and provide useful diagnostic information when failures occur.

Refer to templates/assertion-examples.cs for more practical examples.

dotnet-testing-awesome-assertions-guide

NPX Install

Tags

SKILL.md Content (Chinese)

AwesomeAssertions Fluent Assertions Guide

Use Cases

About AwesomeAssertions

Core Features

Relationship with FluentAssertions

Installation and Configuration

NuGet Package Installation

csproj Configuration (Recommended)

Namespace Reference

Core Assertions Syntax

Advanced Technique: Complex Object Comparison

Advanced Technique: Custom Assertions Extension

Performance Optimization Strategies

Best Practices and Team Standards

Test Naming Conventions

Error Message Optimization

Using AssertionScope

Common Scenarios and Solutions

Troubleshooting

Issue 1: BeEquivalentTo fails but objects look identical

Issue 2: Failure due to different collection order

Issue 3: Floating-point comparison failure

When to Use This Skill

Suitable Scenarios

Unsuitable Scenarios

Collaboration with Other Skills

With unit-test-fundamentals

With test-naming-conventions

With xunit-project-setup

Reference Resources

Original Articles

Official Resources

Related Articles

Summary