dotnet-testing-awesome-assertions-guide_skill

Overview

This skill teaches fluent, readable test assertions using AwesomeAssertions for .NET. It covers core APIs like Should(), BeEquivalentTo(), Contain(), ThrowAsync(), and patterns for object and collection comparison. You’ll get practical guidance for exception checks, asynchronous assertions, and replacing native Assert calls with a fluent style.

How this skill works

The skill inspects common testing scenarios and shows the appropriate AwesomeAssertions API to express intent clearly. It demonstrates deep object comparisons with BeEquivalentTo(options), collection assertions, string and numeric checks, and async exception verification with ThrowAsync. It also outlines performance strategies and how to create custom assertion extensions for domain-specific checks.

When to use it

• Writing unit or integration tests where clarity and intent matter
• Comparing complex objects or API responses with nested properties
• Validating collections for content, count, or order without verbose loops
• Asserting thrown exceptions and verifying exception messages or inner exceptions
• Replacing verbose native Assert calls with fluent, descriptive assertions
• Creating reusable, domain-specific assertions for team conventions

Best practices

• Favor BeEquivalentTo with Excluding/ExcludingMissingMembers to compare only relevant fields
• Use AssertionScope to aggregate multiple failures and reveal all problems at once
• Add because clauses to assertions to give clear failure context
• Check collection counts first with HaveCount() before deep comparisons on large datasets
• Create custom extension methods like product.Should().BeValidProduct() to encapsulate repeated checks

Example use cases

• API response validation: use BeEquivalentTo(expected) and Including()/Excluding() to focus on relevant fields
• Database entity checks: exclude autogenerated fields (Id, CreatedAt) and compare domain properties
• Async error handling: await action.Should().ThrowAsync<InvalidOperationException>().WithMessage("...")
• Complex object comparison: options.Excluding(ctx => ctx.Path.EndsWith("At")) to ignore timestamps
• Team standards: adopt Naming and Because patterns to make assertion failures actionable