GFramework/.qoder/repowiki/zh/content/测试和质量保证.md

测试和质量保证

**本文引用的文件** - [GFramework.Core.Tests.csproj](file://GFramework.Core.Tests/GFramework.Core.Tests.csproj) - [GFramework.SourceGenerators.Tests.csproj](file://GFramework.SourceGenerators.Tests/GFramework.SourceGenerators.Tests.csproj) - [TEST_COVERAGE_PLAN.md](file://GFramework.Core.Tests/TEST_COVERAGE_PLAN.md) - [ArchitectureTestsBase.cs](file://GFramework.Core.Tests/tests/ArchitectureTestsBase.cs) - [TestArchitectureBase.cs](file://GFramework.Core.Tests/architecture/TestArchitectureBase.cs) - [ArchitectureConfigurationTests.cs](file://GFramework.Core.Tests/architecture/ArchitectureConfigurationTests.cs) - [CoroutineSchedulerTests.cs](file://GFramework.Core.Tests/coroutine/CoroutineSchedulerTests.cs) - [EventBusTests.cs](file://GFramework.Core.Tests/events/EventBusTests.cs) - [IocContainerTests.cs](file://GFramework.Core.Tests/ioc/IocContainerTests.cs) - [CommandBusTests.cs](file://GFramework.Core.Tests/command/CommandBusTests.cs) - [GeneratorSnapshotTest.cs](file://GFramework.SourceGenerators.Tests/core/GeneratorSnapshotTest.cs) - [ContextAwareGeneratorSnapshotTests.cs](file://GFramework.SourceGenerators.Tests/rule/ContextAwareGeneratorSnapshotTests.cs) - [EnvironmentTests.cs](file://GFramework.Core.Tests/environment/EnvironmentTests.cs) - [Directory.Build.props（源生成器公共）](file://GFramework.SourceGenerators.Common/Directory.Build.props) - [AnalyzerReleases.Unshipped.md（源生成器公共）](file://GFramework.SourceGenerators.Common/AnalyzerReleases.Unshipped.md) - [Directory.Build.props（核心抽象）](file://GFramework.Core.Abstractions/Directory.Build.props) - [Directory.Build.props（游戏抽象）](file://GFramework.Game.Abstractions/Directory.Build.props) - [Directory.Build.props（Godot源生成器抽象）](file://GFramework.Godot.SourceGenerators.Abstractions/Directory.Build.props) - [Directory.Build.props（源生成器抽象）](file://GFramework.SourceGenerators.Abstractions/Directory.Build.props) - [godot-integration.md（Godot集成教程）](file://docs/tutorials/godot-integration.md)

目录

1. 简介
2. 项目结构
3. 核心组件
4. 架构总览
5. 详细组件分析
6. 依赖分析
7. 性能考虑
8. 故障排查指南
9. 结论
10. 附录

简介

本文件面向GFramework项目的测试与质量保证，系统化阐述单元测试框架配置与使用、核心模块测试策略（架构、事件系统、协程调度、依赖注入）、源代码生成器测试方法与验证策略、测试覆盖率计划与质量标准、性能测试实施方案（协程性能、内存使用、并发）、代码质量保障措施（代码审查、静态分析、持续集成）、测试数据与模拟对象最佳实践、测试环境搭建与自动化配置，以及可维护测试代码与测试用例设计原则。

项目结构

GFramework采用多项目分层结构，测试项目与核心库分离，便于独立构建与测试：

• GFramework.Core.Tests：核心模块单元测试，覆盖架构、事件、协程、IoC、命令/查询、日志、扩展、环境等。
• GFramework.SourceGenerators.Tests：源代码生成器的快照测试，基于Microsoft.CodeAnalysis.Testing。
• 各模块的Directory.Build.props统一启用静态分析工具与CI构建参数，确保一致的质量基线。

graph TB
subgraph "测试项目"
TCore["GFramework.Core.Tests"]
TGen["GFramework.SourceGenerators.Tests"]
end
subgraph "核心库"
Core["GFramework.Core"]
Abstractions["GFramework.Core.Abstractions"]
Game["GFramework.Game"]
GameAbstractions["GFramework.Game.Abstractions"]
Godot["GFramework.Godot"]
SG["GFramework.SourceGenerators"]
SGAbstractions["GFramework.SourceGenerators.Abstractions"]
SGCommon["GFramework.SourceGenerators.Common"]
end
TCore --> Core
TCore --> Abstractions
TGen --> SG
TGen --> SGAbstractions
TGen --> SGCommon

图表来源

• GFramework.Core.Tests.csproj
• GFramework.SourceGenerators.Tests.csproj

章节来源

• GFramework.Core.Tests.csproj
• GFramework.SourceGenerators.Tests.csproj

核心组件

• 单元测试框架：NUnit 4.x，配合NUnit3TestAdapter与Microsoft.NET.Test.Sdk。
• 源代码生成器测试：Microsoft.CodeAnalysis + Microsoft.CodeAnalysis.CSharp.SourceGenerators.Testing。
• 覆盖率工具：建议使用coverlet.collector进行覆盖率收集。
• 静态分析：Meziantou.Analyzer + Meziantou.Polyfill，统一在各模块的Directory.Build.props中配置。

章节来源

• GFramework.Core.Tests.csproj
• GFramework.SourceGenerators.Tests.csproj
• Directory.Build.props（源生成器公共）
• Directory.Build.props（核心抽象）
• Directory.Build.props（游戏抽象）
• Directory.Build.props（Godot源生成器抽象）
• Directory.Build.props（源生成器抽象）

架构总览

测试体系围绕“隔离性、可维护性、可扩展性”设计：

• 测试基类统一SetUp/TearDown，确保架构测试的生命周期一致性。
• 模块内测试文件按功能域组织，便于定位与扩展。
• 源代码生成器采用快照对比，确保生成代码稳定。

sequenceDiagram
participant Dev as "开发者"
participant Dotnet as "dotnet CLI"
participant NUnit as "NUnit引擎"
participant Tests as "测试程序集"
participant Coverage as "Coverlet收集器"
Dev->>Dotnet : 运行 dotnet test
Dotnet->>NUnit : 加载测试适配器与测试程序集
NUnit->>Tests : 执行测试方法
Tests-->>NUnit : 测试结果
Dotnet->>Coverage : 收集覆盖率可选
Coverage-->>Dotnet : 覆盖率报告
Dotnet-->>Dev : 输出测试结果与覆盖率

图表来源

• GFramework.Core.Tests.csproj
• TEST_COVERAGE_PLAN.md

详细组件分析

架构测试策略

• 测试基类：ArchitectureTestsBase与TestArchitectureBase提供统一的架构生命周期与阶段历史记录能力，确保测试隔离与可重复性。
• 关键断言：通过CurrentPhase与ReadyEventFired验证初始化与阶段切换。
• 异步架构：使用[NonParallelizable]避免并发干扰，确保异步初始化顺序可控。

classDiagram
class ArchitectureTestsBase~TArchitecture~ {
-TArchitecture Architecture
+SetUp()
+TearDown()
+AssertInitializationFailed()
<<abstract>>
}
class TestArchitectureBase {
+bool ReadyEventFired
+bool InitCalled
+ArchitecturePhase[] PhaseHistory
+AddPostRegistrationHook(hook)
+Init()
+EnterPhase(next)
}
ArchitectureTestsBase <|-- TestArchitectureBase

图表来源

• ArchitectureTestsBase.cs
• TestArchitectureBase.cs

章节来源

• ArchitectureTestsBase.cs
• TestArchitectureBase.cs

事件系统测试

• EventBus：验证注册、注销、发送事件的多处理器调用行为；事件类型隔离。
• 易用性：通过专用测试事件类简化断言。

sequenceDiagram
participant Test as "EventBusTests"
participant Bus as "EventBus"
participant Handler as "事件处理器"
Test->>Bus : Register(EventBusTestsEvent)
Test->>Bus : Send<EventBusTestsEvent>()
Bus->>Handler : 回调执行
Handler-->>Test : 断言被调用
Test->>Bus : UnRegister(handler)
Test->>Bus : Send<EventBusTestsEvent>()
Bus-->>Test : 不再回调

图表来源

• EventBusTests.cs

章节来源

• EventBusTests.cs

协程调度测试

• 覆盖范围：创建/销毁、暂停/恢复、等待机制、标签管理、异常处理、容量扩展、活跃协程计数、时间源集成。
• 辅助类：TestTimeSource提供可控时间推进，确保可预测的更新序列。

flowchart TD
Start(["开始测试"]) --> Create["创建协程与调度器"]
Create --> Run["运行协程"]
Run --> Update["更新调度器"]
Update --> CheckActive["断言活跃协程计数"]
CheckActive --> Pause["暂停协程"]
Pause --> Resume["恢复协程"]
Resume --> Kill["终止协程"]
Kill --> Tags["按标签终止"]
Tags --> Exceptions["异常处理"]
Exceptions --> Capacity["容量扩展"]
Capacity --> Done(["结束"])

图表来源

• CoroutineSchedulerTests.cs

章节来源

• CoroutineSchedulerTests.cs

依赖注入测试（IoC）

• 覆盖范围：单例注册、多样性注册、泛型/类型注册、获取实例（含必需）、排序获取、包含关系、清除、冻结保护、系统实例注册。
• 注意：通过反射初始化内部日志器字段以满足IocContainer的日志依赖。

sequenceDiagram
participant Test as "IocContainerTests"
participant Container as "IocContainer"
Test->>Container : RegisterSingleton(instance)
Test->>Container : RegisterPlurality(instance)
Test->>Container : Register(instance)/Register(typeof, instance)
Test->>Container : Get<T>()/GetRequired<T>()/GetAll<T>()
Container-->>Test : 断言返回值
Test->>Container : Freeze()/Clear()
Container-->>Test : 断言异常或状态

图表来源

• IocContainerTests.cs

章节来源

• IocContainerTests.cs

命令系统测试（含异步）

• 同步命令：验证Send与Send（带返回值）的行为，以及null命令的异常处理。
• 异步命令：验证SendAsync与SendAsync（带返回值）的行为，以及null命令的异常处理。
• 未来补充：根据覆盖率计划，需补充AbstractAsyncCommand与CommandBus.SendAsync的异步测试。

sequenceDiagram
participant Test as "CommandBusTests"
participant Bus as "CommandBus"
participant Cmd as "命令实例"
Test->>Bus : Send(cmd)
Bus->>Cmd : OnExecute(input)
Cmd-->>Test : 断言执行状态
Test->>Bus : SendAsync(asyncCmd)
Bus->>Cmd : OnExecuteAsync(input)
Cmd-->>Test : 断言异步执行状态

图表来源

• CommandBusTests.cs

章节来源

• CommandBusTests.cs
• TEST_COVERAGE_PLAN.md

源代码生成器测试（快照）

• 快照测试：GeneratorSnapshotTest提供统一的快照生成与比对流程，首次运行生成快照，后续运行对比差异。
• 示例：ContextAwareGeneratorSnapshotTests验证带有ContextAware特性的类生成的上下文感知代码。

sequenceDiagram
participant Test as "ContextAwareGeneratorSnapshotTests"
participant Runner as "GeneratorSnapshotTest"
participant Gen as "ContextAwareGenerator"
Test->>Runner : RunAsync(source, snapshotFolder)
Runner->>Gen : 生成代码
Gen-->>Runner : 生成结果
Runner->>Runner : 对比快照
Runner-->>Test : 断言匹配/失败提示

图表来源

• GeneratorSnapshotTest.cs
• ContextAwareGeneratorSnapshotTests.cs

章节来源

• GeneratorSnapshotTest.cs
• ContextAwareGeneratorSnapshotTests.cs

环境系统测试

• DefaultEnvironment与EnvironmentBase：验证名称、初始化、键值注册与获取。
• 接口契约：通过IEnvironment.Register验证接口实现的一致性。

章节来源

• EnvironmentTests.cs

依赖分析

• 测试项目依赖核心库与抽象层，确保测试覆盖真实实现。
• 源生成器测试依赖Microsoft.CodeAnalysis与SourceGenerators.Testing，确保生成器行为可验证。
• 静态分析工具在各模块统一启用，形成一致的质量门槛。

graph LR
TCore["Core.Tests"] --> Core["Core"]
TCore --> Abstractions["Core.Abstractions"]
TGen["SourceGenerators.Tests"] --> SG["SourceGenerators"]
TGen --> SGAbstractions["SG.Abstractions"]
TGen --> SGCommon["SG.Common"]

图表来源

• GFramework.Core.Tests.csproj
• GFramework.SourceGenerators.Tests.csproj

章节来源

• GFramework.Core.Tests.csproj
• GFramework.SourceGenerators.Tests.csproj

性能考虑

• 协程性能：通过可控时间源推进，验证调度器在高并发协程下的吞吐与延迟。
• 内存使用：关注协程句柄、等待指令与调度器容量扩展对GC的影响，避免频繁分配。
• 并发测试：使用[NonParallelizable]确保架构相关测试的串行执行，避免竞态条件。
• Godot集成性能基准：参考教程中的性能对比示例，验证扩展方法与原生方法的性能差异。

章节来源

• CoroutineSchedulerTests.cs
• godot-integration.md（Godot集成教程）

故障排查指南

• 测试隔离问题：确认每个测试类使用独立的[SetUp]/[TearDown]，必要时使用[NonParallelizable]。
• 异步测试死锁：避免使用Result/Wait，统一使用async/await与Assert.ThrowsAsync。
• 覆盖率缺失：根据覆盖率计划补充异步命令/查询与工具基类的直接测试。
• 源生成器快照不匹配：首次运行会生成快照，后续运行对比差异，确保生成器行为稳定。

章节来源

• TEST_COVERAGE_PLAN.md
• GeneratorSnapshotTest.cs

结论

GFramework的测试与质量保证体系以NUnit为核心，结合架构基类、模块化测试与源生成器快照测试，形成了覆盖全面、可维护性强的测试框架。通过覆盖率计划与静态分析工具，持续提升代码质量与稳定性；通过性能测试与Godot集成示例，确保在实际场景中的高效运行。

附录

测试覆盖率计划与质量标准

• 目标：Core模块文件覆盖率提升至95%+，代码行覆盖率90%+。
• 优先级：高优先级补全异步命令/查询与工具基类测试；中优先级补充常量验证测试。
• 质量标准：测试命名规范、注释规范、异步测试最佳实践、覆盖率工具配置。

章节来源

• TEST_COVERAGE_PLAN.md

测试环境搭建与自动化配置

• 测试框架：NUnit 4.x + NUnit3TestAdapter + Microsoft.NET.Test.Sdk。
• 覆盖率：建议添加coverlet.collector并使用dotnet test --collect:"XPlat Code Coverage"。
• 静态分析：各模块启用Meziantou.Analyzer与Meziantou.Polyfill，统一LangVersion与CI构建参数。

章节来源

• GFramework.Core.Tests.csproj
• GFramework.SourceGenerators.Tests.csproj
• Directory.Build.props（源生成器公共）

可维护测试代码与用例设计原则

• 命名规范：测试类{Component}Tests；测试方法{Scenario}Should{ExpectedOutcome}；辅助类Test{Component}V{Version}。
• 异步测试：使用async Task，避免Result/Wait；使用Assert.ThrowsAsync测试异常。
• 隔离性：[SetUp]/[TearDown]确保状态清理；必要时[NonParallelizable]。
• 文档注释：类与方法使用标准C#文档注释，复杂逻辑使用行内注释说明。

章节来源

• TEST_COVERAGE_PLAN.md