dotnet-testing-advanced-webapi-integration-testing

name	dotnet-testing-advanced-webapi-integration-testing
category	testing
subcategory	integration
description	Complete guide for ASP.NET Core Web API integration testing. Use when performing integration testing on Web API endpoints or validating ProblemDetails error format. Covers WebApplicationFactory, IExceptionHandler, Testcontainers multi-container orchestration, Flurl URL construction, and AwesomeAssertions HTTP validation. Keywords: webapi integration testing, WebApplicationFactory, asp.net core integration test, webapi integration test, IExceptionHandler, ProblemDetails, ValidationProblemDetails, AwesomeAssertions, Flurl, Respawn, Be201Created, Be400BadRequest, multi-container testing, Collection Fixture, global exception handling
targets	["*"]
license	MIT
metadata	{"author":"Kevin Tseng","version":"1.0.0","tags":"webapi, integration-testing, testcontainers, aspnetcore, clean-architecture","related_skills":"advanced-aspnet-integration-testing, advanced-testcontainers-database, advanced-aspire-testing"}
claudecode	{}
opencode	{}
codexcli	{"short-description":".NET skill guidance for dotnet-testing-advanced-webapi-integration-testing"}
copilot	{}
geminicli	{}
antigravity	{}

Source: kevintsengtw/dotnet-testing-agent-skills (MIT). Ported into dotnet-agent-harness.

Web API Integration Testing

Applicable Scenarios

Skill Level: Advanced
Prerequisites: xUnit basics, ASP.NET Core basics, Testcontainers basics, Clean Architecture
Estimated Learning Time: 60-90 minutes

Learning Objectives

After completing this skill, you will be able to:

1. Establish complete Web API integration testing architecture
2. Implement modern exception handling using IExceptionHandler
3. Validate standard ProblemDetails and ValidationProblemDetails format
4. Use Flurl to simplify URL construction for HTTP testing
5. Use AwesomeAssertions for precise HTTP response validation
6. Establish multi-container (PostgreSQL + Redis) testing environment

Core Concepts

IExceptionHandler - Modern Exception Handling

The IExceptionHandler interface introduced in ASP.NET Core 8+ provides a more elegant error handling approach than traditional middleware:

/// <summary>
/// Global exception handler
/// </summary>
public class GlobalExceptionHandler : IExceptionHandler
{
    private readonly ILogger<GlobalExceptionHandler> _logger;

    public GlobalExceptionHandler(ILogger<GlobalExceptionHandler> logger)
    {
        _logger = logger;
    }

    public async ValueTask<bool> TryHandleAsync(
        HttpContext httpContext,
        Exception exception,
        CancellationToken cancellationToken)
    {
        _logger.LogError(exception, "Unhandled exception occurred: {Message}", exception.Message);

         problemDetails = CreateProblemDetails(exception);

        httpContext.Response.StatusCode = problemDetails.Status ?? ;
        httpContext.Response.ContentType = ;

         httpContext.Response.WriteAsJsonAsync(problemDetails, cancellationToken);
         ;
    }

    
    {
         exception 
        {
            KeyNotFoundException =>  ProblemDetails
            {
                Type = ,
                Title = ,
                Status = ,
                Detail = exception.Message
            },
            ArgumentException =>  ProblemDetails
            {
                Type = ,
                Title = ,
                Status = ,
                Detail = exception.Message
            },
            _ =>  ProblemDetails
            {
                Type = ,
                Title = ,
                Status = ,
                Detail = 
            }
        };
    }
}
```text



RFC  defined unified error response format:

| Field | Description |
| ----- | ----------- |
| `type` | URI  problem type |
| `title` | Short error description |
| `status` | HTTP status code |
| `detail` | Detailed error explanation |
| `instance` | URI of problem occurrence |



```json
{
  : ,
  : ,
  : ,
  : ,
  : {
    : [],
    : []
  }
}
```text



FluentValidation exception handler implements the `IExceptionHandler` ,   ``       ``  .     ,    ( )      .

> 📖       [/--](/--)

##   

### 

```
   : <>, 
{
     PostgreSqlContainer? _postgresContainer;
     RedisContainer? _redisContainer;
     FakeTimeProvider? _timeProvider;

     PostgreSqlContainer PostgresContainer => _postgresContainer
        ??   InvalidOperationException();

     RedisContainer RedisContainer => _redisContainer
        ??   InvalidOperationException();

     FakeTimeProvider TimeProvider => _timeProvider
        ??   InvalidOperationException();

    
    {
        _postgresContainer =  PostgreSqlBuilder()
            .WithImage()
            .WithDatabase()
            .WithUsername()
            .WithPassword()
            .WithCleanUp()
            .Build();

        _redisContainer =  RedisBuilder()
            .WithImage()
            .WithCleanUp()
            .Build();

        _timeProvider =  FakeTimeProvider( DateTimeOffset(, , , , , , TimeSpan.Zero));

         _postgresContainer.StartAsync();
         _redisContainer.StartAsync();
    }

    
    {
        builder.ConfigureAppConfiguration(config =>
        {
            config.Sources.Clear();
            config.AddInMemoryCollection( Dictionary<, ?>
            {
                [] = PostgresContainer.GetConnectionString(),
                [] = RedisContainer.GetConnectionString(),
                [] = 
            });
        });

        builder.ConfigureServices(services =>
        {
            
            services.Remove(services.Single(d => d.ServiceType == (TimeProvider)));
            services.AddSingleton<TimeProvider>(TimeProvider);
        });

        builder.UseEnvironment();
    }

    
    {
         (_postgresContainer != )  _postgresContainer.DisposeAsync();
         (_redisContainer != )  _redisContainer.DisposeAsync();
         .DisposeAsync();
    }
}
```text



```csharp
[]
   : <>
{
       Name = ;
}
```text



```csharp
[]
    : 
{
      TestWebApplicationFactory Factory;
      HttpClient HttpClient;
      DatabaseManager DatabaseManager;
      IFlurlClient FlurlClient;

    
    {
        Factory = factory;
        HttpClient = factory.CreateClient();
        DatabaseManager =  DatabaseManager(factory.PostgresContainer.GetConnectionString());
        FlurlClient =  FlurlClient(HttpClient);
    }

    
    {
         DatabaseManager.InitializeDatabaseAsync();
    }

    
    {
         DatabaseManager.CleanDatabaseAsync();
        FlurlClient.Dispose();
    }

    
    {
        Factory.TimeProvider.SetUtcNow( DateTimeOffset(, , , , , , TimeSpan.Zero));
    }

    
    {
        Factory.TimeProvider.Advance(timeSpan);
    }
}
```text



Flurl provides fluent API  building complex URLs:

```csharp

 url = ;


 url = 
    .SetQueryParam(, )
    .SetQueryParam(, )
    .SetQueryParam(, );
```text





```csharp
[]

{
    
     request =  ProductCreateRequest { Name = , Price = m };

    
     response =  HttpClient.PostAsJsonAsync(, request);

    
    response.Should().Be201Created()
        .And.Satisfy<ProductResponse>(product =>
        {
            product.Id.Should().NotBeEmpty();
            product.Name.Should().Be();
            product.Price.Should().Be(m);
        });
}
```text



```csharp
[]

{
    
     invalidRequest =  ProductCreateRequest { Name = , Price = m };

    
     response =  HttpClient.PostAsJsonAsync(, invalidRequest);

    
    response.Should().Be400BadRequest()
        .And.Satisfy<ValidationProblemDetails>(problem =>
        {
            problem.Type.Should().Be();
            problem.Title.Should().Be();
            problem.Errors.Should().ContainKey();
            problem.Errors[].Should().Contain();
        });
}
```text



```csharp
[]

{
    
     nonExistentId = Guid.NewGuid();

    
     response =  HttpClient.GetAsync();

    
    response.Should().Be404NotFound()
        .And.Satisfy<ProblemDetails>(problem =>
        {
            problem.Type.Should().Be();
            problem.Title.Should().Be();
            problem.Status.Should().Be();
        });
}
```text



```csharp
[]

{
    
     TestHelpers.SeedProductsAsync(DatabaseManager, );

    
     url = 
        .SetQueryParam(, )
        .SetQueryParam(, );

     response =  HttpClient.GetAsync(url);

    
    response.Should().Be200Ok()
        .And.Satisfy<PagedResult<ProductResponse>>(result =>
        {
            result.Total.Should().Be();
            result.PageSize.Should().Be();
            result.Page.Should().Be();
            result.Items.Should().HaveCount();
        });
}
```text





```csharp
   
{
    
    {
          ProductCreateRequest { Name = name, Price = price };
    }

    
    {
         tasks = Enumerable.Range(, count)
            .Select(i => SeedSpecificProductAsync(dbManager, , i * m));
         Task.WhenAll(tasks);
    }
}
```text



```text
tests/Integration/
└── SqlScripts/
    └── Tables/
        └── CreateProductsTable.sql
```text





- **Single Responsibility**: Each test focuses  one specific scenario
- **A Pattern**: Clear separation of Arrange, Act, Assert
- **Clear Naming**: Method name expresses test intent



- **ValidationProblemDetails**: Validate error response format
- **ProblemDetails**: Validate business exception response
- **HTTP Status Code**: Confirm correct status code



- **Container Sharing**: Use Collection Fixture
- **Data Cleanup**: Clean data after tests, dons Testing Practice -  Day Challenge