Add integration tests using `WebApplicationFactory`

[coderabbitai]

Problem

The existing unit tests call controller methods directly through Moq mocks and cannot detect routing failures, middleware issues, or HTTP-level serialization problems. There is no test coverage for the actual ASP.NET Core request pipeline.

Proposed Solution

Add an HTTP-layer integration test class using WebApplicationFactory<Program> that exercises the real middleware pipeline, route resolution, status codes, and RFC 7807 Problem Details response bodies — without requiring a running server.

Suggested Approach

1. Add Microsoft.AspNetCore.Mvc.Testing to the test project.
2. Expose Program to the test project by adding public partial class Program {} at the bottom of Program.cs.
3. Create test/.../Integration/PlayerWebApplicationTests.cs using WebApplicationFactory<Program> with an in-memory SQLite database substituted for the real one (via ConfigureTestServices).
4. Add Utilities/TestAuthHandler.cs to bypass [Authorize] on GET /players/{id:Guid}.
5. Use [Trait("Category", "Integration")] on all tests in this class.
6. Follow the controller naming convention: {HttpMethod}_{Resource}_{Condition}_Returns{Outcome}.

Endpoints to cover

GET /players

• Returns 200 OK with all seeded players

GET /players/{id:Guid}

• Returns 200 OK with a valid player body when the ID exists
• Returns 404 Not Found (RFC 7807) when not found

GET /players/squadNumber/{squadNumber:int}

• Returns 200 OK with a valid player body when the squad number exists
• Returns 404 Not Found (RFC 7807) when not found

POST /players

• Returns 201 Created with valid payload
• Returns 400 Bad Request (RFC 7807) when validation fails
• Note: the 409 Conflict branch in the controller is unreachable via the HTTP pipeline. The BeUniqueSquadNumber rule in the "Create" validation rule set catches duplicate squad numbers first and returns 400. The 409 path is covered by the unit test Post_Players_Existing_Returns409Conflict, where validation is mocked to pass.

PUT /players/squadNumber/{squadNumber:int}

• Returns 204 No Content on successful update
• Returns 404 Not Found (RFC 7807) when player does not exist
• Returns 400 Bad Request (RFC 7807) when validation fails
• Returns 400 Bad Request (RFC 7807) when squad number in route does not match body

DELETE /players/squadNumber/{squadNumber:int}

• Returns 204 No Content on successful deletion
• Returns 404 Not Found (RFC 7807) when player does not exist

GET /health

• Returns 200 OK

Acceptance Criteria

• Microsoft.AspNetCore.Mvc.Testing added to the test project
• public partial class Program {} added to Program.cs
• Utilities/TestAuthHandler.cs added to bypass [Authorize] in tests
• test/.../Integration/PlayerWebApplicationTests.cs exists
• All endpoints listed above have at least the happy-path and principal error cases covered
• All error response assertions validate the RFC 7807 schema (type, title, status)
• [Trait("Category", "Integration")] applied to all tests in the class
• All existing tests continue to pass
• CHANGELOG.md updated

References

• Integration tests in ASP.NET Core
• Prerequisite: Add integration tests for Repository<T> and PlayerRepository #461 (establishes the Integration/ subfolder and pattern)
• Prerequisite for: Add Testcontainers for Integration Testing with Database Containers #353 (Testcontainers — promotes these tests to real containers)

[nanotaboada]

@coderabbitai the integration test coverage suggestion should apply to all routes, not just squadNumber. Can you expand the proposal and plan accordingly?

[coderabbitai]

Coding Plan

Summary

• Extend the existing test project with integration testing capabilities using Microsoft.AspNetCore.Mvc.Testing rather than creating a separate test project
• Create a custom WebApplicationFactory fixture that replaces the production SQLite database with an in-memory instance seeded with known test data
• Follow existing naming conventions and test organization patterns, placing integration tests in a new Integration/ folder with the [Trait("Category", "Integration")] decoration
• Test actual endpoint behavior as implemented (empty 404 bodies, custom validation error arrays) rather than the RFC 7807 schema mentioned in the ticket, documenting this deviation

Design Choices

Design Choice 1: Route Template Discrepancy

Options Considered:

1. Test the routes exactly as specified in the ticket (would require route changes out of scope)
2. Test the routes as they actually exist in the codebase (/players/{squadNumber:int})

Chosen Option: 2

Rationale: Test the actual routes that exist in the codebase, as the ticket's intent is to add integration test coverage for squad-number endpoints regardless of the exact path format.

Design Choice 2: RFC 7807 Problem Details for Error Responses

Options Considered:

1. Modify the controller to return Problem Details (scope creep)
2. Test actual response behavior and structure as implemented
3. Skip error response body validation entirely

Chosen Option: 2

Rationale: Test the actual response behavior. For 404 responses, verify the status code and empty body. For 400 responses, verify the custom validation error array structure. Document in tests that these don't conform to RFC 7807. The ExceptionMiddleware does return Problem Details for unhandled exceptions, so that path could still be tested.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Test Infrastructure Setup

Configure the test project to support integration testing with WebApplicationFactory, including necessary package references and making the Program class accessible for test host instantiation.

Task 1: Add Integration Test Package Reference

Add the Microsoft.AspNetCore.Mvc.Testing NuGet package to enable WebApplicationFactory usage.

• Add Microsoft.AspNetCore.Mvc.Testing package reference to test/Dotnet.Samples.AspNetCore.WebApi.Tests/Dotnet.Samples.AspNetCore.WebApi.Tests.csproj
• Match the versioning pattern of existing packages (latest stable for .NET 10)

Task 2: Expose Program Class for WebApplicationFactory

Make the implicitly-generated Program class accessible to the test project for use with WebApplicationFactory.

• Add public partial class Program { } declaration at the bottom of src/Dotnet.Samples.AspNetCore.WebApi/Program.cs
• This follows the standard pattern for exposing top-level statement entry points to WebApplicationFactory

Task 3: Create Custom WebApplicationFactory Fixture

Create a test fixture that configures the application with an in-memory SQLite database and seeds test data.

• Create test/Dotnet.Samples.AspNetCore.WebApi.Tests/Utilities/CustomWebApplicationFactory.cs
• Inherit from WebApplicationFactory<Program> and implement IAsyncLifetime for async setup/teardown
• Override ConfigureWebHost to replace the production SQLite DbContext with an in-memory SQLite connection
• Leverage existing DatabaseFakes.CreateSqliteConnection() pattern for connection setup
• Seed the database with PlayerFakes.MakeStarting11() to provide consistent test data
• Consider disabling rate limiting for tests by overriding the rate limiter configuration

🤖 Prompt for AI agents

Set up the integration testing infrastructure for the existing test project. The
goal is to enable `WebApplicationFactory<Program>` usage by adding the required
NuGet package, exposing the `Program` class, and creating a reusable test
fixture.

- In
`test/Dotnet.Samples.AspNetCore.WebApi.Tests/Dotnet.Samples.AspNetCore.WebApi.Tests.csproj`,
add a package reference for `Microsoft.AspNetCore.Mvc.Testing` using the latest
stable version compatible with .NET 10, matching the versioning pattern of
existing packages
- In `src/Dotnet.Samples.AspNetCore.WebApi/Program.cs`, append `public partial
class Program { }` at the bottom of the file to expose the top-level statement
entry point to the test project
- Create
`test/Dotnet.Samples.AspNetCore.WebApi.Tests/Utilities/CustomWebApplicationFactory.cs`:
- Define the class inheriting from `WebApplicationFactory<Program>` and
implementing `IAsyncLifetime`
- Override `ConfigureWebHost` to replace the production SQLite DbContext
registration with an in-memory SQLite connection, leveraging the existing
`DatabaseFakes.CreateSqliteConnection()` pattern
- In the async setup (via `IAsyncLifetime`), seed the database using
`PlayerFakes.MakeStarting11()` to ensure consistent, known test data is
available
- Consider adding logic to disable rate limiting middleware for the test host to
prevent tests from being throttled

Phase 2: Integration Tests for Squad-Number Endpoints

Implement integration tests for all three squad-number-scoped endpoints, verifying HTTP-level behavior including routing, status codes, and response bodies.

Task 1: Create Integration Test Class Structure

Set up the integration test class with proper fixture usage and helper methods.

• Create test/Dotnet.Samples.AspNetCore.WebApi.Tests/Integration/PlayerEndpointsIntegrationTests.cs
• Implement IClassFixture<CustomWebApplicationFactory> to share the factory across tests
• Inject HttpClient via the factory's CreateClient() method
• Decorate tests with [Trait("Category", "Integration")] to distinguish from unit tests
• Add helper methods for JSON deserialization using the same serialization settings as the API

Task 2: Implement GET Endpoint Integration Tests

Test the GET /players/{squadNumber:int} endpoint for both success and not-found scenarios.

• Get_PlayerBySquadNumber_Existing_Returns200Ok: Request a known squad number (e.g., 10 for Messi), verify 200 status and PlayerResponseModel body with correct property values
• Get_PlayerBySquadNumber_NonExisting_Returns404NotFound: Request squad number 999 (non-existent), verify 404 status code
• Verify response content-type is application/json for successful responses
• Use FluentAssertions for all assertions following existing test patterns

Task 3: Implement PUT Endpoint Integration Tests

Test the PUT /players/{squadNumber:int} endpoint for success, validation failure, and not-found scenarios.

• Put_PlayerBySquadNumber_ValidUpdate_Returns204NoContent: Update existing player (e.g., squad #23), verify 204 status and empty body
• Put_PlayerBySquadNumber_ValidationError_Returns400BadRequest: Send invalid request body (e.g., empty FirstName), verify 400 status and error array in response
• Put_PlayerBySquadNumber_NonExisting_Returns404NotFound: Update non-existent squad number 999, verify 404 status
• Use PlayerFakes.MakeRequestModelForUpdate() to generate valid update payloads
• Serialize request bodies using JsonContent.Create() or StringContent with JSON

Task 4: Implement DELETE Endpoint Integration Tests

Test the DELETE /players/{squadNumber:int} endpoint for success and not-found scenarios.

• Delete_PlayerBySquadNumber_Existing_Returns204NoContent: Delete existing player (e.g., squad #26), verify 204 status and empty body
• Delete_PlayerBySquadNumber_NonExisting_Returns404NotFound: Delete non-existent squad number 999, verify 404 status
• Consider test isolation: if DELETE test runs before other tests on same squad number, use a dedicated squad number or reset data between tests

Task 5: Add Database Reset Between Tests (Optional Enhancement)

Ensure test isolation by resetting database state between tests that modify data.

• Evaluate whether tests need explicit data reset (PUT and DELETE modify state)
• Option A: Use IAsyncLifetime on the test class to reseed before each test
• Option B: Use unique squad numbers for each destructive test to avoid conflicts
• Option C: Accept that tests may depend on execution order (simpler but less robust)
• Choose option that balances test isolation with complexity—likely Option B given the fixture already seeds 11 distinct players

🤖 Prompt for AI agents

Implement the HTTP-level integration tests for the squad-number-scoped player
endpoints (GET, PUT, DELETE) against the real ASP.NET Core middleware pipeline.
The goal is full coverage of routing, status codes, and response bodies using
the infrastructure set up in Phase 1.

- Create
`test/Dotnet.Samples.AspNetCore.WebApi.Tests/Integration/PlayerEndpointsIntegrationTests.cs`:
- Implement `IClassFixture<CustomWebApplicationFactory>` to share the factory
instance across all tests in the class
- Obtain an `HttpClient` by calling `factory.CreateClient()` in the constructor
  - Decorate all test methods with `[Trait("Category", "Integration")]`
- Add private helper methods for JSON deserialization that use the same
serialization settings as the API

- **GET tests** (route: `/players/{squadNumber:int}`):
- `Get_PlayerBySquadNumber_Existing_Returns200Ok`: GET a known squad number
(e.g., 10 for Messi); assert 200 status, `application/json` content-type, and
correct `PlayerResponseModel` property values using FluentAssertions
- `Get_PlayerBySquadNumber_NonExisting_Returns404NotFound`: GET squad number
999; assert 404 status

- **PUT tests** (route: `/players/{squadNumber:int}`):
- `Put_PlayerBySquadNumber_ValidUpdate_Returns204NoContent`: PUT a valid payload
(from `PlayerFakes.MakeRequestModelForUpdate()`) for an existing player (e.g.,
squad `#23`); assert 204 status and empty body
- `Put_PlayerBySquadNumber_ValidationError_Returns400BadRequest`: PUT an invalid
payload (e.g., empty `FirstName`) for an existing squad number; assert 400
status and the custom validation error array structure in the response body (not
RFC 7807)
- `Put_PlayerBySquadNumber_NonExisting_Returns404NotFound`: PUT a valid payload
for squad number 999; assert 404 status
- Serialize request bodies using `JsonContent.Create()` or `StringContent` with
`application/json` media type

- **DELETE tests** (route: `/players/{squadNumber:int}`):
- `Delete_PlayerBySquadNumber_Existing_Returns204NoContent`: DELETE an existing
player (e.g., squad `#26`); assert 204 status and empty body
- `Delete_PlayerBySquadNumber_NonExisting_Returns404NotFound`: DELETE squad
number 999; assert 404 status

- **Test isolation**: Use unique squad numbers per destructive test (Option B)
to avoid cross-test state conflicts, given the fixture seeds 11 distinct players
from `PlayerFakes.MakeStarting11()`
- Follow the existing naming convention
`{HttpMethod}_{Resource}_{Condition}_Returns{Outcome}` throughout

Research

The project follows a layered architecture (Controller → Service → Repository → DbContext) targeting .NET 10. The test project uses xUnit, Moq, and FluentAssertions, with test utilities organized in a Utilities/ folder containing PlayerFakes.cs for test data, PlayerMocks.cs for mock factories, and DatabaseFakes.cs for in-memory SQLite setup. Unit tests follow the naming convention {HttpMethod}_{Resource}_{Condition}_Returns{Outcome} and are decorated with [Trait("Category", "Unit")]. The main project uses top-level statements in Program.cs without an explicit public partial class Program {} declaration. Current squad-number endpoints use route templates /players/{squadNumber:int} (not /players/squadNumber/{squadNumber:int} as mentioned in the ticket).

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Set up the integration testing infrastructure for the existing test project. The
goal is to enable `WebApplicationFactory<Program>` usage by adding the required
NuGet package, exposing the `Program` class, and creating a reusable test
fixture.

- In
`test/Dotnet.Samples.AspNetCore.WebApi.Tests/Dotnet.Samples.AspNetCore.WebApi.Tests.csproj`,
add a package reference for `Microsoft.AspNetCore.Mvc.Testing` using the latest
stable version compatible with .NET 10, matching the versioning pattern of
existing packages
- In `src/Dotnet.Samples.AspNetCore.WebApi/Program.cs`, append `public partial
class Program { }` at the bottom of the file to expose the top-level statement
entry point to the test project
- Create
`test/Dotnet.Samples.AspNetCore.WebApi.Tests/Utilities/CustomWebApplicationFactory.cs`:
- Define the class inheriting from `WebApplicationFactory<Program>` and
implementing `IAsyncLifetime`
- Override `ConfigureWebHost` to replace the production SQLite DbContext
registration with an in-memory SQLite connection, leveraging the existing
`DatabaseFakes.CreateSqliteConnection()` pattern
- In the async setup (via `IAsyncLifetime`), seed the database using
`PlayerFakes.MakeStarting11()` to ensure consistent, known test data is
available
- Consider adding logic to disable rate limiting middleware for the test host to
prevent tests from being throttled
===============================================================================

Task: 2

Implement the HTTP-level integration tests for the squad-number-scoped player
endpoints (GET, PUT, DELETE) against the real ASP.NET Core middleware pipeline.
The goal is full coverage of routing, status codes, and response bodies using
the infrastructure set up in Phase 1.

- Create
`test/Dotnet.Samples.AspNetCore.WebApi.Tests/Integration/PlayerEndpointsIntegrationTests.cs`:
- Implement `IClassFixture<CustomWebApplicationFactory>` to share the factory
instance across all tests in the class
- Obtain an `HttpClient` by calling `factory.CreateClient()` in the constructor
  - Decorate all test methods with `[Trait("Category", "Integration")]`
- Add private helper methods for JSON deserialization that use the same
serialization settings as the API

- **GET tests** (route: `/players/{squadNumber:int}`):
- `Get_PlayerBySquadNumber_Existing_Returns200Ok`: GET a known squad number
(e.g., 10 for Messi); assert 200 status, `application/json` content-type, and
correct `PlayerResponseModel` property values using FluentAssertions
- `Get_PlayerBySquadNumber_NonExisting_Returns404NotFound`: GET squad number
999; assert 404 status

- **PUT tests** (route: `/players/{squadNumber:int}`):
- `Put_PlayerBySquadNumber_ValidUpdate_Returns204NoContent`: PUT a valid payload
(from `PlayerFakes.MakeRequestModelForUpdate()`) for an existing player (e.g.,
squad `#23`); assert 204 status and empty body
- `Put_PlayerBySquadNumber_ValidationError_Returns400BadRequest`: PUT an invalid
payload (e.g., empty `FirstName`) for an existing squad number; assert 400
status and the custom validation error array structure in the response body (not
RFC 7807)
- `Put_PlayerBySquadNumber_NonExisting_Returns404NotFound`: PUT a valid payload
for squad number 999; assert 404 status
- Serialize request bodies using `JsonContent.Create()` or `StringContent` with
`application/json` media type

- **DELETE tests** (route: `/players/{squadNumber:int}`):
- `Delete_PlayerBySquadNumber_Existing_Returns204NoContent`: DELETE an existing
player (e.g., squad `#26`); assert 204 status and empty body
- `Delete_PlayerBySquadNumber_NonExisting_Returns404NotFound`: DELETE squad
number 999; assert 404 status

- **Test isolation**: Use unique squad numbers per destructive test (Option B)
to avoid cross-test state conflicts, given the fixture seeds 11 distinct players
from `PlayerFakes.MakeStarting11()`
- Follow the existing naming convention
`{HttpMethod}_{Resource}_{Condition}_Returns{Outcome}` throughout

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!