TUnit断言扩展开发指南：异步支持与最佳实践

引言

TUnit作为一款现代化的.NET测试框架，近期对其断言系统进行了重要升级，引入了对异步操作的支持。这一变化使得开发者能够编写更灵活、更强大的自定义断言条件，但同时也带来了一些文档和API设计上的挑战。

断言系统的异步化演进

在最新版本的TUnit中，BaseAssertion.GetResult(...)方法的返回值类型从同步的AssertionResult变更为Task<AssertionResult>。这一变更使得断言条件能够支持异步操作，为测试场景提供了更大的灵活性。

文档与实际实现的不一致问题

当前官方文档中的示例代码尚未完全更新以反映这一变化，仍在使用同步版本的实现方式。更值得注意的是，文档示例中引用了两个关键但被标记为internal的辅助类：

1. TUnit.Assertions.Helpers.Formatter类中的Format方法
2. TUnit.Assertions.Extensions.StringExtensions类中的TruncateWithEllipsis扩展方法

由于这些类的internal访问修饰符限制，开发者无法在自己的项目中直接使用这些辅助功能，导致文档示例实际上无法直接复制使用。

改进后的断言扩展实现

基于当前API设计，以下是经过调整的可实际使用的自定义断言条件实现：

public class StringEqualsExpectedValueAssertCondition(string expected, StringComparison stringComparison)
    : ExpectedValueAssertCondition<string, string>(expected)
{
    protected override string GetExpectation()
        => $"to be equal to \"{expected}\"";

    protected override async Task<AssertionResult> GetResult(string? actualValue, string? expectedValue)
    {
        if (actualValue is null)
        {
            return AssertionResult
                .FailIf(
                    expectedValue is not null,
                    "it was null");
        }

        return AssertionResult
            .FailIf(
                !string.Equals(actualValue, expectedValue, stringComparison),
                $"found \"{actualValue}\"");
    }
}

这个实现方案具有以下特点：

1. 完全适配异步API
2. 不依赖任何internal类型
3. 保持了清晰的错误信息格式
4. 简化了字符串格式化逻辑

关于API设计的思考

虽然当前文档示例引用了internal辅助类，但这实际上反映了一个更深层次的API设计考量。框架开发者需要在以下方面做出权衡：

1. 封装性：保持内部实现细节的隐藏，确保框架核心逻辑的稳定性
2. 扩展性：为第三方开发者提供足够的扩展能力
3. 一致性：确保自定义断言与内置断言在行为和外观上保持一致

对于希望实现更复杂自定义断言的开发者，可以考虑以下替代方案：

1. 自行实现字符串格式化逻辑
2. 通过继承或组合方式复用TUnit的内部逻辑（如果框架未来提供相应扩展点）
3. 提交功能请求，建议框架开放必要的辅助工具

最佳实践建议

1. 优先使用简单实现：在大多数情况下，简单的字符串插值足以满足需求
2. 考虑异步场景：即使当前不需要异步操作，也应遵循框架规范使用Task返回值
3. 保持错误信息清晰：错误信息应当简明扼要地指出问题所在
4. 关注框架更新：及时跟进框架变更，调整自定义断言实现

结语

TUnit的断言系统通过支持异步操作变得更加灵活强大，虽然目前文档和API设计存在一些需要完善的地方，但开发者仍然可以基于现有API构建有效的自定义断言条件。理解框架设计理念并遵循最佳实践，将帮助开发者充分利用TUnit的扩展能力，构建更健壮的测试套件。