Skip to main content
dotnet-testing-awesome-assertions-guide 使用 AwesomeAssertions 進行流暢且可讀的測試斷言技能。當需要撰寫清晰的斷言、比對物件、驗證集合、處理複雜比對時使用。涵蓋 Should()、BeEquivalentTo()、Contain()、ThrowAsync() 等完整 API。
Make sure to use this skill whenever the user mentions assertions, Should(), BeEquivalentTo, fluent assertions, AwesomeAssertions, or wants more readable test assertions, even if they don't explicitly ask for assertion guidance.
Keywords: assertions, awesome assertions, fluent assertions, 斷言, 流暢斷言, Should(), Be(), BeEquivalentTo, Contain, ThrowAsync, NotBeNull, 物件比對, 集合驗證, 例外斷言, AwesomeAssertions, FluentAssertions, fluent syntax
跳到安装 Skills Marketplace 发现并探索由社区构建的 Agent Skills
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/kevintsengtw/dotnet-testing-agent-skills --skill dotnet-testing-awesome-assertions-guide命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
下载 Zip 下载中... 同仓库更多 Skills dotnet-testing-advanced-aspire-testing .NET Aspire Testing 整合測試框架完整指南。當需要測試 .NET Aspire 分散式應用程式、設定 AppHost 測試或從 Testcontainers 遷移至 Aspire 測試時使用。涵蓋 DistributedApplicationTestingBuilder、容器生命週期管理、多服務編排、Respawn 配置與時間可測試性設計。
Make sure to use this skill whenever the user mentions .NET Aspire, AppHost testing, DistributedApplicationTestingBuilder, cloud-native testing, or migrating from Testcontainers to Aspire, even if they don't explicitly ask for Aspire testing guidance.
Keywords: aspire testing, .NET Aspire, DistributedApplicationTestingBuilder, AppHost testing, 分散式測試, AspireAppFixture, IAsyncLifetime, ContainerLifetime.Session, 雲原生測試, 多服務整合, Aspire.Hosting.Testing, Respawn
dotnet-testing-advanced-aspnet-integration-testing ASP.NET Core 整合測試的專門技能。當需要測試 Web API 端點、HTTP 請求/回應、中介軟體、依賴注入時使用。涵蓋 WebApplicationFactory、TestServer、HttpClient 測試、記憶體資料庫配置等。
Make sure to use this skill whenever the user mentions ASP.NET Core integration testing, WebApplicationFactory, TestServer, HTTP endpoint testing, or middleware testing, even if they don't explicitly ask for integration testing guidance.
Keywords: integration testing, 整合測試, web api testing, WebApplicationFactory, TestServer, HttpClient testing, controller testing, endpoint testing, 端點測試, RESTful API testing, Microsoft.AspNetCore.Mvc.Testing, CreateClient, ConfigureWebHost, AwesomeAssertions.Web, Be200Ok, Be404NotFound, middleware testing, 中介軟體測試, dependency injection testing
.NET 進階測試技能總覽與引導中心。當使用者詢問「整合測試」、「API 測試」、「容器化測試」、「微服務測試」、「測試框架遷移」、「Testcontainers」、「Aspire 測試」等進階測試需求時觸發。會根據具體需求推薦適合的子技能組合，涵蓋整合測試、Testcontainers、Aspire 測試、框架升級等 8 個進階技能。
Make sure to use this skill whenever the user mentions integration testing, API testing, Testcontainers, .NET Aspire testing, WebApplicationFactory, or xUnit/TUnit migration, even if they don't explicitly ask for advanced testing guidance.
Keywords: integration testing, 整合測試, API testing, advanced testing, 進階測試, testcontainers, aspire testing, WebApplicationFactory, TestServer, database test, 資料庫測試, EF Core test, MongoDB test, Redis test, Docker test, 容器測試, microservice test, 微服務測試, .NET Aspire, xUnit upgrade, TUnit, framework migration
kevintsengtw
kevintsengtw/dotnet-testing-agent-skills
打开 GitHub 仓库 name dotnet-testing-awesome-assertions-guide description 使用 AwesomeAssertions 進行流暢且可讀的測試斷言技能。當需要撰寫清晰的斷言、比對物件、驗證集合、處理複雜比對時使用。涵蓋 Should()、BeEquivalentTo()、Contain()、ThrowAsync() 等完整 API。
Make sure to use this skill whenever the user mentions assertions, Should(), BeEquivalentTo, fluent assertions, AwesomeAssertions, or wants more readable test assertions, even if they don't explicitly ask for assertion guidance.
Keywords: assertions, awesome assertions, fluent assertions, 斷言, 流暢斷言, Should(), Be(), BeEquivalentTo, Contain, ThrowAsync, NotBeNull, 物件比對, 集合驗證, 例外斷言, AwesomeAssertions, FluentAssertions, fluent syntax
AwesomeAssertions 流暢斷言指南
本技能提供使用 AwesomeAssertions 進行高品質測試斷言的完整指南，涵蓋基礎語法、進階技巧與最佳實踐。
關於 AwesomeAssertions
AwesomeAssertions 是 FluentAssertions 的社群分支版本，使用 Apache 2.0 授權，完全免費且無商業使用限制。
核心特色
完全免費 ：Apache 2.0 授權，適合商業專案使用流暢語法 ：支援方法鏈結的自然語言風格豐富斷言 ：涵蓋物件、集合、字串、數值、例外等各種類型優秀錯誤訊息 ：提供詳細且易理解的失敗資訊高性能 ：優化的實作確保測試執行效率可擴展 ：支援自訂 Assertions 方法
與 FluentAssertions 的關係
AwesomeAssertions 是 FluentAssertions 的社群 fork，主要差異：
項目 FluentAssertions AwesomeAssertions 授權 商業專案需付費 Apache 2.0（完全免費） 命名空間 FluentAssertionsAwesomeAssertionsAPI 相容性 原版 高度相容 社群支援 官方維護 社群維護
安裝與設定
NuGet 套件安裝
dotnet add package AwesomeAssertions
Install-Package AwesomeAssertions
csproj 設定（推薦） <ItemGroup >
<PackageReference Include ="AwesomeAssertions" Version ="9.4.0" PrivateAssets ="all" />
</ItemGroup >
命名空間引用 using AwesomeAssertions;
using Xunit;
核心 Assertions 語法 所有 Assertions 皆以 .Should() 開始，搭配流暢方法鏈結。
類別 常用方法 說明 物件 NotBeNull(), BeOfType<T>(), BeEquivalentTo()空值、類型、相等性檢查 字串 Contain(), StartWith(), MatchRegex(), BeEquivalentTo()內容、模式、忽略大小寫比對 數值 BeGreaterThan(), BeInRange(), BeApproximately()比較、範圍、浮點精度 數值集合 EqualApproximately(), NotEqualApproximately()數值集合近似比對（9.4+） 集合 HaveCount(), Contain(), BeEquivalentTo(), AllSatisfy()數量、內容、順序、條件 例外 Throw<T>(), NotThrow(), WithMessage(), WithInnerException()例外類型、訊息、巢狀例外 非同步 ThrowAsync<T>(), CompleteWithinAsync()非同步例外與完成驗證
進階技巧：複雜物件比對 使用 BeEquivalentTo() 搭配 options 進行深度物件比較：
排除屬性 ：options.Excluding(u => u.Id) — 排除自動生成欄位動態排除 ：options.Excluding(ctx => ctx.Path.EndsWith("At")) — 按模式排除循環參考 ：options.IgnoringCyclicReferences().WithMaxRecursionDepth(10)
進階技巧：自訂 Assertions 擴展 建立領域特定擴展方法，如 product.Should().BeValidProduct()，以及可重用排除擴展如 ExcludingAuditFields()。
效能最佳化策略
大量資料 ：先用 HaveCount() 快速檢查數量，再抽樣驗證（避免全量 BeEquivalentTo）選擇性比對 ：使用匿名物件 + ExcludingMissingMembers() 只驗證關鍵屬性
order.Should().BeEquivalentTo(new
{
CustomerId = 123 ,
TotalAmount = 999.99 m,
Status = "Pending"
}, options => options.ExcludingMissingMembers());
9.2-9.4 版本新功能
數值集合近似比對 — [Not]EqualApproximately（9.4+） 針對 INumber<T> 數值集合，新增近似相等斷言（需 .NET 8+）：
var actual = new [] { 1.001f , 2.002f , 3.003f };
actual.Should().EqualApproximately(new [] { 1f , 2f , 3f }, 0.01f );
actual.Should().NotEqualApproximately(new [] { 10f , 20f , 30f }, 0.01f );
與 BeApproximately() 的差異 ：BeApproximately() 用於單一數值，EqualApproximately() 用於數值集合，會逐一比對每個元素。當容差為 0 時，EqualApproximately 的行為等同於 Equal。
集合格式化最大項目數設定（9.4+） 斷言失敗時，集合預設顯示前 32 個項目。現在可透過 FormattingOptions 自訂：
using var scope = new AssertionScope();
scope.FormattingOptions.MaxItems = 100 ;
largeCollection.Should().BeEquivalentTo(expected);
class LargeCollectionFormatter : EnumerableValueFormatter
{
protected override int MaxItems => 100 ;
public override bool CanHandle (object value value is IEnumerable<MyEntity>;
}
集合出現次數約束（9.2+） var numbers = new [] { 1 , 2 , 2 , 3 , 3 , 3 };
numbers.Should().Contain(2 , AtLeast.Once());
numbers.Should().Contain(3 , Exactly.Times(3 ));
Null 安全性改善 — [return: NotNull]（9.4+） 所有 Should() 和斷言方法加入 [return: NotNull] 標註，讓編譯器的 nullable 分析正確追蹤：
var user = GetUser();
user.Should().NotBeNull();
user!.Name.Should().Be("test" );
user.Should().NotBeNull();
user.Name.Should().Be("test" );
排除成員名稱（9.3+） BeEquivalentTo 支援按名稱排除成員：
actual.Should().BeEquivalentTo(expected, options => options
.Excluding(ctx => ctx.Name == "InternalState" ));
最佳實踐與團隊標準
測試命名規範 遵循 方法_情境_預期結果 模式（如 CreateUser_有效電子郵件_應回傳啟用的使用者）。
錯誤訊息優化 在斷言中加入 because 字串，提供清晰的失敗上下文：
result.IsSuccess.Should().BeFalse("because negative payment amounts are not allowed" );
AssertionScope 使用 使用 AssertionScope 收集多個失敗訊息，一次顯示所有問題：
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" );
}
常見情境與解決方案 情境 關鍵技巧 API 回應驗證 BeEquivalentTo() + Including() 選擇性比對資料庫實體驗證 BeEquivalentTo() + Excluding() 排除自動生成欄位事件驗證 訂閱捕獲事件後逐一驗證屬性
疑難排解
問題 1：BeEquivalentTo 失敗但物件看起來相同
actual.Should().BeEquivalentTo(expected, options => options
.Excluding(x => x.Id)
.Excluding(x => x.CreatedAt)
.Excluding(x => x.UpdatedAt)
);
問題 2：集合順序不同導致失敗
actual.Should().BeEquivalentTo(expected);
actual.Should().Equal(expected);
問題 3：浮點數比較失敗
actualValue.Should().BeApproximately(expectedValue, 0.001 );
actualValues.Should().EqualApproximately(expectedValues, 0.001 );
何時使用此技能
適用情境 撰寫單元測試或整合測試時
需要驗證複雜物件結構時
比對 API 回應或資料庫實體時
需要清晰的失敗訊息時
建立領域特定測試標準時
不適用情境 效能測試（使用專用 benchmarking 工具）
負載測試（使用 K6、JMeter 等）
UI 測試（使用 Playwright、Selenium）
與其他技能的配合
與 unit-test-fundamentals 搭配 先使用 unit-test-fundamentals 建立測試結構，再使用本技能撰寫斷言：
[Fact ]
public void Calculator_Add_兩個正數_應回傳總和()
{
var calculator = new Calculator();
var result = calculator.Add(2 , 3 );
result.Should().Be(5 );
}
與 test-naming-conventions 搭配 使用 test-naming-conventions 的命名規範，搭配本技能的斷言：
[Fact ]
public void CreateUser_有效資料_應回傳啟用使用者()
{
var user = userService.CreateUser("test@example.com" );
user.Should().NotBeNull()
.And.BeOfType<User>();
user.IsActive.Should().BeTrue();
}
與 xunit-project-setup 搭配 在 xunit-project-setup 建立的專案中安裝並使用 AwesomeAssertions。
輸出格式
產生使用 AwesomeAssertions 流暢語法的測試斷言
使用 Should().Be/BeEquivalentTo/Contain 等方法鏈
包含物件比對、集合驗證、例外斷言範例
提供 .csproj 套件參考（AwesomeAssertions）
參考資源
原始文章 本技能內容提煉自「老派軟體工程師的測試修練 - 30 天挑戰」系列文章：
官方資源
相關文章
總結 AwesomeAssertions 提供了強大且可讀的斷言語法，是撰寫高品質測試的重要工具。透過：
流暢語法 ：讓測試程式碼更易讀豐富斷言 ：涵蓋各種資料類型（9.4 新增數值集合近似比對）自訂擴展 ：建立領域特定斷言效能優化 ：處理大量資料情境（9.4 新增集合顯示上限設定）完全免費 ：Apache 2.0 授權無商業限制Null 安全 ：9.4 起 [return: NotNull] 改善 nullable 分析 記住：好的斷言不僅能驗證結果，更能清楚表達預期行為，並在失敗時提供有用的診斷資訊。
