# WebApi 集成测试 ## 学习目标完成本技能学习后，您将能够： 1. 建立完整的WebApi整合测试架构 2.使用`IExceptionHandler`实作现代化异常处理 3. 验证 `ProblemDetails` 和 `ValidationProblemDetails` 标准格式 4. 使用 Flurl 简化 URL 的 HTTP 测试眼下 5. 使用 AwesomeAssertions 进行精确的 HTTP 响应验证 6.建立多容器（PostgreSQL + Redis）测试环境 ## 核心概念 ### IExceptionHandler - 现代化异常处理 ASP.NET Core 8+ 引入的`IExceptionHandler`介面提供了比传统中间件更优雅的错误处理方式： /// <摘要> /// 全域异常处理器 /// 公共类 GlobalExceptionHandler : IExceptionHandler { 私有只读 ILogger _logger; 公共 GlobalExceptionHandler(ILogger 记录器) { _logger=记录器； } 公共异步 ValueTask TryHandleAsync( HttpContext httpContext, 异常异常， CancellationToken（取消令牌） { _logger.LogError(exception, "发生未处理的异常: {Message}", exception.Message); var ProblemDetails = CreateProblemDetails(异常); httpContext.Response.StatusCode = ProblemDetails.Status ?? 500； httpContext.Response.ContentType = "应用程序/问题+json"; 等待 httpContext.Response.WriteAsJsonAsync(problemDetails,cancelToken); 返回真； } 私有静态ProblemDetails CreateProblemDetails（异常异常） { 返回异常开关 { KeyNotFoundException => 新问题详细信息 { 类型=“https://httpstatuses.com/404”， Title = "资源不存在", 状态 = 404，详细信息 = 异常.消息 }, ArgumentException => 新问题详细信息 { 类型=“https://httpstatuses.com/400”， Title = "参数错误", 状态 = 400，详细信息 = 异常.消息 }, _ => 新问题详细信息 { 类型=“https://httpstatuses.com/500”， Title = "内部服务器错误", 状态 = 500，详细信息=“发生未预期的错误” } }; } } ### ProblemDetails 标准格式 RFC 7807定义的统一错误响应格式：栏位 | 说明 ---|--- `类型` | 问题类型的 URI `标题` | 错误描述概要 `状态` | HTTP状态码 `细节` | 详细的错误说明 `实例` | 发生问题的实例 URI ### ValidationProblemDetails - 验证错误专用 { “类型”：“https://tools.ietf.org/html/rfc9110#section-15.5.1”， "title": "发生一个或多个验证错误。", “状态”：400， "detail": "输入的数据包含验证错误", “错误”：{ "Name": ["产品名称不能为空"], "价格": ["产品价格必须大于0"] } } ### FluentValidation 异常处理器 FluentValidation异常处理器实作`IExceptionHandler`面，专门处理`ValidationException`，将验证转换错误介为标准的`ValidationProblemDetails`格式响应。处理器之间按照注册顺序特定执行，处理器（如FluentValidation）必须在全域处理器注册之前。 > 完整的实作程序代码请参阅 [references/exception-handler-details.md]() ## 集成测试基础设施 ### TestWebApplicationFactory 公共类 TestWebApplicationFactory ：WebApplicationFactory ，IAsyncLifetime { 私人 PostgreSqlContainer？ _postgres容器；私有Redis容器？ _redis容器；私人 FakeTimeProvider？ _时间提供者；公共 PostgreSqlContainer PostgresContainer => _postgresContainer ?? throw new InvalidOperationException("PostgreSQL 容器尚未初始化"); 公共 RedisContainer RedisContainer => _redisContainer ?? throw new InvalidOperationException("Redis 容器尚未初始化"); 公共 FakeTimeProvider TimeProvider => _timeProvider ?? throw new InvalidOperationException("TimeProvider 尚未初始化"); 公共异步任务InitializeAsync() { _postgresContainer = new PostgreSqlBuilder() .WithImage("postgres:16-alpine") .WithDatabase("test_db") .WithUsername("测试用户") .WithPassword("测试密码") .WithCleanUp(true) .Build(); _redisContainer = 新的RedisBuilder() .WithImage("redis:7-alpine") .WithCleanUp(true) .Build(); _timeProvider = new FakeTimeProvider(new DateTimeOffset(2024, 1, 1, 0, 0, 0, TimeSpan.Zero)); 等待 _postgresContainer.StartAsync(); 等待 _redisContainer.StartAsync(); } 受保护的覆盖无效ConfigureWebHost（IWebHostBuilder构建器） { 构建器.ConfigureAppConfiguration（配置=> { config.Sources.Clear(); config.AddInMemoryCollection(new Dictionary<字符串, 字符串?> { ["ConnectionStrings:DefaultConnection"] = PostgresContainer.GetConnectionString(), ["ConnectionStrings:Redis"] = RedisContainer.GetConnectionString(), [“日志记录：日志级别：默认”] =“警告” }); }); 构建器.ConfigureServices（服务=> { // 替换 TimeProvider services.Remove(services.Single(d => d.ServiceType == typeof(TimeProvider))); services.AddSingleton(TimeProvider); }); builder.UseEnvironment(“测试”); } 公共新异步任务 DisposeAsync() { if (_postgresContainer != null) 等待 _postgresContainer.DisposeAsync(); if (_redisContainer != null) wait _redisContainer.DisposeAsync(); 等待base.DisposeAsync(); } } ### 收藏夹具模式 [集合定义（“集成测试”）] 公共类 IntegrationTestCollection ： ICollectionFixture { public const string Name = "集成测试"; } ### 测试类别 [集合（“集成测试”）] 公共抽象类 IntegrationTestBase ：IAsyncLifetime { 受保护的只读 TestWebApplicationFactory 工厂；受保护的只读 HttpClient HttpClient；受保护的只读数据库管理器数据库管理器；受保护的只读 IFlurlClient FlurlClient；受保护的 IntegrationTestBase（TestWebApplicationFactory 工厂） { 工厂=工厂； HttpClient = 工厂.CreateClient(); DatabaseManager = new DatabaseManager(factory.PostgresContainer.GetConnectionString()); FlurlClient = 新 FlurlClient(HttpClient); } 公共虚拟异步任务InitializeAsync() { 等待 DatabaseManager.InitializeDatabaseAsync(); } 公共虚拟异步任务 DisposeAsync() { 等待 DatabaseManager.CleanDatabaseAsync(); FlulClient.Dispose(); } 受保护无效 ResetTime() { Factory.TimeProvider.SetUtcNow(new DateTimeOffset(2024, 1, 1, 0, 0, 0, TimeSpan.Zero)); } protected void AdvanceTime(TimeSpan timeSpan) { Factory.TimeProvider.Advance(timeSpan); } } ## Flul 简化 URL 浏览 Flurl 提供流畅的 API 来看看复杂的 URL： // 传统方式 var url = $"/products?pageSize={pageSize}&page={page}&keyword={keyword}"; // 使用颤动 var url =“/产品” .SetQueryParam("页面大小", 5) .SetQueryParam("页面", 2) .SetQueryParam("关键字", "特殊"); ## 模板测试 ### 成功建立产品测试 [事实] 公共异步任务CreateProduct_使用有效数据_应成功建立产品() { // 排列 var request = new ProductCreateRequest { Name = "新产品", Price = 299.99m }; // 行动 var response = wait HttpClient.PostAsJsonAsync("/products", request); // 断言响应.Should().Be201Created() .And.Satisfy(产品 => { 产品.Id.Should().NotBeEmpty(); 产品.Name.Should().Be("新产品"); 产品.价格.Should().Be(299.99m); }); } ### 验证错误测试 [事实] 公共异步任务CreateProduct_当产品名称为空_应回传400BadRequest() { // 排列 var invalidRequest = new ProductCreateRequest { 名称 = "", 价格 = 100.00m }; // 行动 var response = wait HttpClient.PostAsJsonAsync("/products", invalidRequest); // 断言响应.Should().Be400BadRequest() .And.Satisfy(问题 => { Problem.Type.Should().Be("https://tools.ietf.org/html/rfc9110#section-15.5.1"); Problem.Title.Should().Be("发生一个或多个验证错误。"); Problem.Errors.Should().ContainKey("Name"); Problem.Errors["Name"].Should().Contain("产品名称不能为空"); }); } ### 资源不存在测试 [事实] public async Task GetById_当产品不存在_应回传404且包含ProblemDetails() { // 排列 var nonExistentId = Guid.NewGuid(); // 行动 var response = wait HttpClient.GetAsync($"/Products/{nonExistentId}"); // 断言响应.Should().Be404NotFound() .And.Satisfy<问题详细信息>(问题 => { Problem.Type.Should().Be("https://httpstatuses.com/404"); Problem.Title.Should().Be("产品不存在"); 问题.Status.Should().Be(404); }); } ### 分页查询测试 [事实] 公共异步任务 GetProducts_使用分页参数_应回传正确的分页结果() { // 排列等待 TestHelpers.SeedProductsAsync(DatabaseManager, 15); // Act - 使用 Flurl 当下 QueryString var url =“/产品” .SetQueryParam("页面大小", 5) .SetQueryParam("页面", 2); var 响应 = 等待 HttpClient.GetAsync(url); // 断言响应.Should().Be200Ok() .And.Satisfy>(结果 => { 结果.Total.Should().Be(15); 结果.PageSize.Should().Be(5); 结果.Page.Should().Be(2); result.Items.Should().HaveCount(5); }); } ## 数据管理策略 ### TestHelpers 设计公共静态类 TestHelpers { 公共静态ProductCreateRequest CreateProductRequest（ string name = "测试产品", 小数价格 = 100.00m) { return new ProductCreateRequest { 名称 = 名称，价格 = 价格 }; } 公共静态异步任务 SeedProductsAsync（DatabaseManager dbManager，int count） { var 任务 = Enumerable.Range(1, 计数) .Select(i => SeedSpecificProductAsync(dbManager, $"产品 {i:D2}", i * 10.0m)); 等待任务.WhenAll(任务); } } ### SQL指令码外部化测试/集成/ └── SqlScripts/ └── 桌子/ └── 创建产品表.sql ## 最佳实务 ### 1\. 测试结构设计 * **单一职责**：每个测试专注于一个特定场景 * **3A模式** ：清晰区分 Arrange、Act、Assert * **语音命名** ：方法名称表达测试含义 ### 2\. 错误处理验证 * **ValidationProblemDetails** ：验证错误响应格式 * **ProblemDetails** ：验证业务异常已回复 * **HTTP 状态码** ：确认正确的状态码 ### 3\. 实际考量 * **容器共享** ：使用Collection Fixture * **数据清理** ：测试后清理数据，不重建集装箱 * ** 工具执行** ：确保测试独立性 ## 相依套件 ## 专案结构源代码/ ├── Api/ # WebApi 层 ├── Application/ #应用服务层 ├── Domain/ # 领域模型 └── Infrastructure/ # 基础设施层测试/ └── 整合/ ├── 赛程/ │ ├── TestWebApplicationFactory.cs │ ├── IntegrationTestCollection.cs │ └── IntegrationTestBase.cs ├── 处理者/ │ ├── GlobalExceptionHandler.cs │ └── FluentValidationExceptionHandler.cs ├── 帮手/ │ ├── 数据库管理器.cs │ └── TestHelpers.cs ├── SqlScripts/ │ └── 表格/ └── 控制器/ └── ProductsControllerTests.cs ## 输出格式 * 产生 `TestWebApplicationFactory.cs`，配置多容器（PostgreSQL + Redis）与 DI 替换 * 产生 `IntegrationTestCollection.cs` 与 `IntegrationTestBase.cs` 测试基础设施 * 产生`DatabaseManager.cs`，整合Respawn进行测试数据清理 * 产生控制器测试类别，验证CRUD、ProblemDetails 和 ValidationProblemDetails * 产生 `GlobalExceptionHandler.cs` 与 `FluentValidationExceptionHandler.cs` 异常处理器 ## 参考资源 ### 原始文章本技能内容提炼自「老派软体工程师的测试修练 - 30天挑战」系列文章： * **第 23 天 - 集成测试实战：WebApi 服务的集成测试** * 铁人赛文章： * 示例程序代码： ### 官方文件 * [ASP.NET Core 集成测试]() * [IExceptionHandler 文件]() * [问题详细信息 RFC 7807]() * [.NET 测试容器]() * [AwesomeAssertions]() * [Flurl HTTP 客户端]() * [重生]() ### 相关技能 * `dotnet-testing-advanced-aspnet-integration-testing` \- ASP.NET Core 基础集成测试 * `dotnet-testing-advanced-testcontainers-database` \- 资料库容器测试 * `dotnet-testing-advanced-testcontainers-nosql` \- NoSQL 容器测试 * `dotnet-testing-fluentvalidation-testing` \- FluentValidation 测试

Dotnet 测试高级 Webapi 集成测试

包含技能