gewuyou/GFramework
1
0
Fork 0
mirror of https://github.com/GeWuYou/GFramework.git synced 2026-03-26 06:16:43 +08:00
Code Issues Packages Projects Releases Wiki Activity
GFramework/.qoder/repowiki/zh/content/测试和质量保证.md
GeWuYou a79f02c987 docs(api): 添加 Core API 参考文档与事件系统接口文档 
- 新增 Core API 参考文档，涵盖架构与模块、数据模型与系统、命令与查询等核心组件
- 添加事件系统接口详细文档，包括 IEvent、IEventBus、IUnRegister 等接口说明
- 提供完整的 API 使用示例路径、最佳实践与性能建议
- 包含架构图、依赖关系图与故障排查指南
- 添加测试用例参考与扩展方法说明
- [skip ci]
2026-01-21 23:45:10 +08:00

355 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 测试和质量保证
<cite>
**本文引用的文件**
- [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)
</cite>
## 目录
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构建参数，确保一致的质量基线。
```mermaid
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](file://GFramework.Core.Tests/GFramework.Core.Tests.csproj#L1-L19)
- [GFramework.SourceGenerators.Tests.csproj](file://GFramework.SourceGenerators.Tests/GFramework.SourceGenerators.Tests.csproj#L1-L30)
章节来源
- [GFramework.Core.Tests.csproj](file://GFramework.Core.Tests/GFramework.Core.Tests.csproj#L1-L19)
- [GFramework.SourceGenerators.Tests.csproj](file://GFramework.SourceGenerators.Tests/GFramework.SourceGenerators.Tests.csproj#L1-L30)
## 核心组件
- 单元测试框架：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](file://GFramework.Core.Tests/GFramework.Core.Tests.csproj#L8-L12)
- [GFramework.SourceGenerators.Tests.csproj](file://GFramework.SourceGenerators.Tests/GFramework.SourceGenerators.Tests.csproj#L10-L19)
- [Directory.Build.props（源生成器公共）](file://GFramework.SourceGenerators.Common/Directory.Build.props#L14-L23)
- [Directory.Build.props（核心抽象）](file://GFramework.Core.Abstractions/Directory.Build.props#L14-L23)
- [Directory.Build.props（游戏抽象）](file://GFramework.Game.Abstractions/Directory.Build.props#L14-L23)
- [Directory.Build.props（Godot源生成器抽象）](file://GFramework.Godot.SourceGenerators.Abstractions/Directory.Build.props#L14-L23)
- [Directory.Build.props（源生成器抽象）](file://GFramework.SourceGenerators.Abstractions/Directory.Build.props#L14-L23)
## 架构总览
测试体系围绕“隔离性、可维护性、可扩展性”设计：
- 测试基类统一SetUp/TearDown，确保架构测试的生命周期一致性。
- 模块内测试文件按功能域组织，便于定位与扩展。
- 源代码生成器采用快照对比，确保生成代码稳定。
```mermaid
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](file://GFramework.Core.Tests/GFramework.Core.Tests.csproj#L8-L12)
- [TEST_COVERAGE_PLAN.md](file://GFramework.Core.Tests/TEST_COVERAGE_PLAN.md#L474-L491)
## 详细组件分析
### 架构测试策略
- 测试基类：ArchitectureTestsBase与TestArchitectureBase提供统一的架构生命周期与阶段历史记录能力，确保测试隔离与可重复性。
- 关键断言：通过CurrentPhase与ReadyEventFired验证初始化与阶段切换。
- 异步架构：使用[NonParallelizable]避免并发干扰，确保异步初始化顺序可控。
```mermaid
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](file://GFramework.Core.Tests/tests/ArchitectureTestsBase.cs#L11-L61)
- [TestArchitectureBase.cs](file://GFramework.Core.Tests/architecture/TestArchitectureBase.cs#L10-L58)
章节来源
- [ArchitectureTestsBase.cs](file://GFramework.Core.Tests/tests/ArchitectureTestsBase.cs#L11-L61)
- [TestArchitectureBase.cs](file://GFramework.Core.Tests/architecture/TestArchitectureBase.cs#L10-L58)
### 事件系统测试
- EventBus：验证注册、注销、发送事件的多处理器调用行为；事件类型隔离。
- 易用性：通过专用测试事件类简化断言。
```mermaid
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](file://GFramework.Core.Tests/events/EventBusTests.cs#L10-L78)
章节来源
- [EventBusTests.cs](file://GFramework.Core.Tests/events/EventBusTests.cs#L10-L78)
### 协程调度测试
- 覆盖范围：创建/销毁、暂停/恢复、等待机制、标签管理、异常处理、容量扩展、活跃协程计数、时间源集成。
- 辅助类：TestTimeSource提供可控时间推进，确保可预测的更新序列。
```mermaid
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](file://GFramework.Core.Tests/coroutine/CoroutineSchedulerTests.cs#L24-L467)
章节来源
- [CoroutineSchedulerTests.cs](file://GFramework.Core.Tests/coroutine/CoroutineSchedulerTests.cs#L24-L467)
### 依赖注入测试（IoC）
- 覆盖范围：单例注册、多样性注册、泛型/类型注册、获取实例（含必需）、排序获取、包含关系、清除、冻结保护、系统实例注册。
- 注意：通过反射初始化内部日志器字段以满足IocContainer的日志依赖。
```mermaid
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](file://GFramework.Core.Tests/ioc/IocContainerTests.cs#L13-L330)
章节来源
- [IocContainerTests.cs](file://GFramework.Core.Tests/ioc/IocContainerTests.cs#L13-L330)
### 命令系统测试（含异步）
- 同步命令：验证Send与Send（带返回值）的行为，以及null命令的异常处理。
- 异步命令：验证SendAsync与SendAsync（带返回值）的行为，以及null命令的异常处理。
- 未来补充：根据覆盖率计划，需补充AbstractAsyncCommand与CommandBus.SendAsync的异步测试。
```mermaid
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](file://GFramework.Core.Tests/command/CommandBusTests.cs#L20-L124)
章节来源
- [CommandBusTests.cs](file://GFramework.Core.Tests/command/CommandBusTests.cs#L20-L124)
- [TEST_COVERAGE_PLAN.md](file://GFramework.Core.Tests/TEST_COVERAGE_PLAN.md#L166-L300)
### 源代码生成器测试（快照）
- 快照测试：GeneratorSnapshotTest提供统一的快照生成与比对流程，首次运行生成快照，后续运行对比差异。
- 示例：ContextAwareGeneratorSnapshotTests验证带有ContextAware特性的类生成的上下文感知代码。
```mermaid
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](file://GFramework.SourceGenerators.Tests/core/GeneratorSnapshotTest.cs#L11-L72)
- [ContextAwareGeneratorSnapshotTests.cs](file://GFramework.SourceGenerators.Tests/rule/ContextAwareGeneratorSnapshotTests.cs#L12-L84)
章节来源
- [GeneratorSnapshotTest.cs](file://GFramework.SourceGenerators.Tests/core/GeneratorSnapshotTest.cs#L11-L72)
- [ContextAwareGeneratorSnapshotTests.cs](file://GFramework.SourceGenerators.Tests/rule/ContextAwareGeneratorSnapshotTests.cs#L12-L84)
### 环境系统测试
- DefaultEnvironment与EnvironmentBase：验证名称、初始化、键值注册与获取。
- 接口契约：通过IEnvironment.Register验证接口实现的一致性。
章节来源
- [EnvironmentTests.cs](file://GFramework.Core.Tests/environment/EnvironmentTests.cs#L11-L215)
## 依赖分析
- 测试项目依赖核心库与抽象层，确保测试覆盖真实实现。
- 源生成器测试依赖Microsoft.CodeAnalysis与SourceGenerators.Testing，确保生成器行为可验证。
- 静态分析工具在各模块统一启用，形成一致的质量门槛。
```mermaid
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](file://GFramework.Core.Tests/GFramework.Core.Tests.csproj#L14-L16)
- [GFramework.SourceGenerators.Tests.csproj](file://GFramework.SourceGenerators.Tests/GFramework.SourceGenerators.Tests.csproj#L21-L23)
章节来源
- [GFramework.Core.Tests.csproj](file://GFramework.Core.Tests/GFramework.Core.Tests.csproj#L14-L16)
- [GFramework.SourceGenerators.Tests.csproj](file://GFramework.SourceGenerators.Tests/GFramework.SourceGenerators.Tests.csproj#L21-L23)
## 性能考虑
- 协程性能：通过可控时间源推进，验证调度器在高并发协程下的吞吐与延迟。
- 内存使用：关注协程句柄、等待指令与调度器容量扩展对GC的影响，避免频繁分配。
- 并发测试：使用[NonParallelizable]确保架构相关测试的串行执行，避免竞态条件。
- Godot集成性能基准：参考教程中的性能对比示例，验证扩展方法与原生方法的性能差异。
章节来源
- [CoroutineSchedulerTests.cs](file://GFramework.Core.Tests/coroutine/CoroutineSchedulerTests.cs#L24-L467)
- [godot-integration.md（Godot集成教程）](file://docs/tutorials/godot-integration.md#L1277-L1318)
## 故障排查指南
- 测试隔离问题：确认每个测试类使用独立的[SetUp]/[TearDown]，必要时使用[NonParallelizable]。
- 异步测试死锁：避免使用Result/Wait，统一使用async/await与Assert.ThrowsAsync<T>。
- 覆盖率缺失：根据覆盖率计划补充异步命令/查询与工具基类的直接测试。
- 源生成器快照不匹配：首次运行会生成快照，后续运行对比差异，确保生成器行为稳定。
章节来源
- [TEST_COVERAGE_PLAN.md](file://GFramework.Core.Tests/TEST_COVERAGE_PLAN.md#L426-L493)
- [GeneratorSnapshotTest.cs](file://GFramework.SourceGenerators.Tests/core/GeneratorSnapshotTest.cs#L11-L72)
## 结论
GFramework的测试与质量保证体系以NUnit为核心，结合架构基类、模块化测试与源生成器快照测试，形成了覆盖全面、可维护性强的测试框架。通过覆盖率计划与静态分析工具，持续提升代码质量与稳定性；通过性能测试与Godot集成示例，确保在实际场景中的高效运行。
## 附录
### 测试覆盖率计划与质量标准
- 目标：Core模块文件覆盖率提升至95%+，代码行覆盖率90%+。
- 优先级：高优先级补全异步命令/查询与工具基类测试；中优先级补充常量验证测试。
- 质量标准：测试命名规范、注释规范、异步测试最佳实践、覆盖率工具配置。
章节来源
- [TEST_COVERAGE_PLAN.md](file://GFramework.Core.Tests/TEST_COVERAGE_PLAN.md#L1-L582)
### 测试环境搭建与自动化配置
- 测试框架：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](file://GFramework.Core.Tests/GFramework.Core.Tests.csproj#L8-L12)
- [GFramework.SourceGenerators.Tests.csproj](file://GFramework.SourceGenerators.Tests/GFramework.SourceGenerators.Tests.csproj#L10-L19)
- [Directory.Build.props（源生成器公共）](file://GFramework.SourceGenerators.Common/Directory.Build.props#L14-L23)
### 可维护测试代码与用例设计原则
- 命名规范：测试类{Component}Tests；测试方法{Scenario}_Should_{ExpectedOutcome}；辅助类Test{Component}V{Version}。
- 异步测试：使用async Task，避免Result/Wait；使用Assert.ThrowsAsync<T>测试异常。
- 隔离性：[SetUp]/[TearDown]确保状态清理；必要时[NonParallelizable]。
- 文档注释：类与方法使用标准C#文档注释，复杂逻辑使用行内注释说明。
章节来源
- [TEST_COVERAGE_PLAN.md](file://GFramework.Core.Tests/TEST_COVERAGE_PLAN.md#L426-L493)
Reference in New Issue View Git Blame Copy Permalink