Merge pull request #464 from nanotaboada/feat/web-application-integration-tests

test(integration): add `WebApplicationFactory` HTTP tests (#421)

Author: nanotaboada

.github/copilot-instructions.md

@@ -58,14 +58,15 @@ test/Dotnet.Samples.AspNetCore.WebApi.Tests/
 
 ### Test naming conventions
 
-Tests live under `test/.../Unit/`. Two naming patterns, strictly by layer:
+Two naming patterns, strictly by layer:
 
-| Layer                | Pattern                                                       | Example                                                          |
-|----------------------|---------------------------------------------------------------|------------------------------------------------------------------|
-| Controller           | `{HttpMethod}_{Resource}_{Condition}_Returns{Outcome}`        | `Get_Players_Existing_ReturnsPlayers`                            |
-| Service / Validator  | `{MethodName}_{StateUnderTest}_{ExpectedBehavior}`            | `RetrieveAsync_CacheMiss_QueriesRepositoryAndCachesResult`       |
+| Layer                | Location              | Pattern                                                       | Example                                                          |
+|----------------------|-----------------------|---------------------------------------------------------------|------------------------------------------------------------------|
+| Controller (unit)    | `test/.../Unit/`      | `{HttpMethod}_{Resource}_{Condition}_Returns{Outcome}`        | `Get_Players_Existing_ReturnsPlayers`                            |
+| Service / Validator  | `test/.../Unit/`      | `{MethodName}_{StateUnderTest}_{ExpectedBehavior}`            | `RetrieveAsync_CacheMiss_QueriesRepositoryAndCachesResult`       |
+| HTTP integration     | `test/.../Integration/` | `{HttpMethod}_{Resource}_{Condition}_Returns{Outcome}`      | `Get_Players_Existing_Returns200Ok`                              |
 
-Each pattern has exactly three underscore-delimited segments. Do not add a fourth segment.
+Each pattern has exactly three underscore-delimited segments where `{HttpMethod}_{Resource}` counts as the first segment. Do not add a fourth segment.
 
 ### FluentValidation rule sets
 

CHANGELOG.md

@@ -44,6 +44,8 @@ This project uses famous football stadiums (A-Z) that hosted FIFA World Cup matc
 
 ### Added
 
+- Add `adr/0013-testing-strategy.md` documenting the decision to implement the full test pyramid as a deliberate educational choice (#421)
+- Add `test/.../Integration/PlayerWebApplicationTests.cs` with 14 HTTP-layer integration tests covering all player endpoints and `/health` via `WebApplicationFactory<Program>` backed by in-memory SQLite; includes `Utilities/TestAuthHandler.cs` to bypass `[Authorize]` on `GET /players/{id:Guid}`; expose `Program` to the test project via `public partial class Program {}` in `Program.cs`; add `Microsoft.AspNetCore.Mvc.Testing` to the test project (#421)
 - Add `test/.../Integration/PlayerRepositoryTests.cs` with 9 integration tests covering `Repository<T>` (`GetAllAsync`, `FindByIdAsync`, `RemoveAsync`) and `PlayerRepository` (`FindBySquadNumberAsync`, `SquadNumberExistsAsync`); all tests use `DatabaseFakes.MigrateAsync()` on in-memory SQLite and are tagged `[Trait("Category", "Integration")]` (#461)
 - Add `ValidateAsync_SquadNumberNegative_ReturnsValidationError` test to exercise the `GreaterThan(0)` rule with a negative value, which passes `NotEmpty()` but fails the greater-than rule (#427)
 - Add `ValidateAsync_FirstNameEmptyInUpdateRuleSet_ReturnsValidationError` test to verify the `"Update"` rule set enforces structural field validation (#427)

adr/0013-testing-strategy.md

@@ -0,0 +1,49 @@
+# 0013. Testing Strategy
+
+Date: 2026-04-10
+
+## Status
+
+Accepted
+
+## Context
+
+The project is a learning reference for a REST API built with ASP.NET Core. Its primary goal is educational clarity — it must be immediately understandable to developers studying the stack, not just functional in production.
+
+For a CRUD API of this size, a single suite of HTTP-layer integration tests (using `WebApplicationFactory<Program>` backed by an in-memory SQLite database) would cover the majority of meaningful risk. Such tests exercise the full request pipeline — routing, middleware, validation, serialization, and database interaction — with minimal setup.
+
+The question was whether to stop there or to also add unit tests for each layer (controller, service, validator, repository) separately.
+
+## Decision
+
+The project implements the full test pyramid:
+
+- **Unit tests** for each layer in isolation (controller, service, validator, repository), with dependencies replaced by Moq mocks or in-memory fakes.
+- **Repository integration tests** that run EF Core queries against in-memory SQLite via the full migration chain, validating query correctness and migration health as a side effect.
+- **HTTP integration tests** (`PlayerWebApplicationTests`) that send real HTTP requests through `WebApplicationFactory<Program>`, exercising the entire pipeline end-to-end.
+
+Some overlap between layers is accepted deliberately.
+
+## Rationale
+
+The redundancy is the point. Having all test types in one place allows a reader to see exactly what each layer tests, what it isolates, and what it leaves to the layer above or below. The test suite is as much documentation as it is a safety net.
+
+The repository integration tests in particular serve two purposes beyond what the HTTP tests provide: they validate individual EF Core queries in isolation (making failures easier to diagnose) and they run `MigrateAsync()` as a side effect, which acts as a canary for migration chain health.
+
+## Consequences
+
+### Positive
+
+- Every layer of the architecture has dedicated tests, making failure diagnosis straightforward.
+- The test suite demonstrates the full range of testing patterns available in the .NET ecosystem.
+- Migration health is continuously validated as a side effect of the repository tests.
+
+### Negative
+
+- Test count is higher than strictly necessary for confidence.
+- Maintenance cost is proportionally higher — changes to shared fixtures or fakes may require updates across multiple test classes.
+
+### Neutral
+
+- The HTTP integration tests (`PlayerWebApplicationTests`) are the minimum viable test suite. All other test classes add depth, not breadth.
+- The `409 Conflict` branch on `POST /players` is unreachable via the HTTP pipeline: the `BeUniqueSquadNumber` rule in the `"Create"` validation rule set catches duplicates first and returns `400`. This path is covered by the controller unit test, where validation is mocked to pass.

adr/README.md

@@ -18,6 +18,7 @@ This directory contains Architecture Decision Records (ADRs) for this project. A
 | [0010](0010-use-serilog-for-structured-logging.md) | Use Serilog for Structured Logging | Accepted |
 | [0011](0011-use-docker-for-containerization.md) | Use Docker for Containerization | Accepted |
 | [0012](0012-use-stadium-themed-semantic-versioning.md) | Use Stadium-Themed Semantic Versioning | Accepted |
+| [0013](0013-testing-strategy.md) | Testing Strategy | Accepted |
 
 ## When to Create an ADR
 

src/Dotnet.Samples.AspNetCore.WebApi/Program.cs

@@ -122,3 +122,8 @@
 app.MapControllers();
 
 await app.RunAsync();
+
+public partial class Program
+{
+    protected Program() { }
+}

test/Dotnet.Samples.AspNetCore.WebApi.Tests/Dotnet.Samples.AspNetCore.WebApi.Tests.csproj

@@ -9,6 +9,7 @@
   </PropertyGroup>
 
   <ItemGroup Label="Test dependencies">
+  <PackageReference Include="Microsoft.AspNetCore.Mvc.Testing" Version="10.0.0" PrivateAssets="all" />
   <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.4.0" PrivateAssets="all" />
   <PackageReference Include="Moq" Version="4.20.72" PrivateAssets="all" />
   <PackageReference Include="FluentAssertions" Version="8.9.0" PrivateAssets="all" />