Refactor test method naming to follow the .NET unit testing standard

[nanotaboada]

Problem

The current test method naming follows a GWT-ish pattern (Given{Method}_When{Condition}_Then{Outcome}) that is both more verbose than necessary for unit tests and misaligned with the Microsoft-endorsed industry standard for .NET unit test naming.

Current examples:

GivenGetAsync_WhenServiceRetrieveAsyncReturnsListOfPlayers_ThenResponseShouldBeEquivalentToListOfPlayers
GivenPostAsync_WhenValidatorReturnsErrors_ThenResponseStatusCodeShouldBe400BadRequest
GivenValidateAsync_WhenDateOfBirthIsInTheFuture_ThenValidationShouldFail

These names carry ~40% filler words (Given, When, Then, ShouldBe) that add length without adding meaning.

Research

Microsoft official standard

Unit testing best practices for .NET (Microsoft Learn) explicitly defines test names as having three parts:

Name of the method being tested · Scenario under which it is tested · Expected behavior when the scenario is invoked

Their canonical pattern (based on Roy Osherove's Naming Standards for Unit Tests):

MethodName_StateUnderTest_ExpectedBehavior

Examples from their docs:

Add_SingleNumber_ReturnsSameNumber()
Add_EmptyString_ReturnsZero()
GetDiscountedPrice_NotTuesday_ReturnsFullPrice()
ParseLogLine_StartsAndEndsWithSpace_ReturnsTrimmedResult()

Where GWT belongs

Given/When/Then originates in BDD (Cucumber, SpecFlow, Gherkin) and is appropriate for acceptance/integration tests that map directly to user stories. For unit tests — where the subject is a single method or class — it adds noise. The three-part Microsoft standard conveys the same information without the filler.

Adapting the standard to HTTP controller tests

For controller tests, the unit of work is always an HTTP request/response cycle. Encoding the HTTP verb and resource makes the three parts concrete and immediately scannable, while remaining a faithful expression of UnitOfWork_StateUnderTest_ExpectedBehavior:

{METHOD}_{Resource}_{Condition}_Returns{Outcome}

This is still the same Microsoft-standard three-part structure — just with HTTP semantics making each part explicit.

Proposed Solution

Apply a unified naming pattern derived from the Microsoft standard, specialized by test layer:

Layer	Pattern	Rationale
Controller	{METHOD}_{Resource}_{Condition}_Returns{Outcome}	HTTP semantics make the three parts explicit
Service	{MethodName}_{StateUnderTest}_{ExpectedBehavior}	Pure Microsoft standard; no HTTP concerns
Validator	{MethodName}_{StateUnderTest}_{ExpectedBehavior}	Pure Microsoft standard; no HTTP concerns

Suggested Approach

Controller tests (PlayerControllerTests.cs)

Before	After
GivenGetAsync_WhenServiceRetrieveAsyncReturnsListOfPlayers_ThenResponseShouldBeEquivalentToListOfPlayers	GET_Players_Existing_ReturnsPlayers
GivenGetAsync_WhenServiceRetrieveAsyncReturnsEmptyList_ThenResponseStatusCodeShouldBe404NotFound	GET_Players_NonExisting_Returns404NotFound
GivenGetByIdAsync_WhenServiceRetrieveByIdAsyncReturnsPlayer_ThenResponseStatusCodeShouldBe200Ok	GET_PlayerById_Existing_Returns200OK
GivenGetByIdAsync_WhenServiceRetrieveByIdAsyncReturnsNull_ThenResponseStatusCodeShouldBe404NotFound	GET_PlayerById_NonExisting_Returns404NotFound
GivenGetBySquadNumberAsync_WhenServiceRetrieveBySquadNumberAsyncReturnsPlayer_ThenResponseStatusCodeShouldBe200Ok	GET_PlayerBySquadNumber_Existing_Returns200OK
GivenGetBySquadNumberAsync_WhenServiceRetrieveBySquadNumberAsyncReturnsNull_ThenResponseStatusCodeShouldBe404NotFound	GET_PlayerBySquadNumber_NonExisting_Returns404NotFound
GivenPostAsync_WhenValidatorReturnsErrors_ThenResponseStatusCodeShouldBe400BadRequest	POST_Players_ValidationError_Returns400BadRequest
GivenPostAsync_WhenServiceRetrieveBySquadNumberAsyncReturnsPlayer_ThenResponseStatusCodeShouldBe409Conflict	POST_Players_Existing_Returns409Conflict
GivenPostAsync_WhenServiceRetrieveBySquadNumberAsyncReturnsNull_ThenResponseStatusCodeShouldBe201Created	POST_Players_NonExisting_Returns201Created
GivenPutAsync_WhenValidatorReturnsErrors_ThenResponseStatusCodeShouldBe400BadRequest	PUT_PlayerBySquadNumber_ValidationError_Returns400BadRequest
GivenPutAsync_WhenServiceRetrieveBySquadNumberAsyncReturnsNull_ThenResponseStatusCodeShouldBe404NotFound	PUT_PlayerBySquadNumber_NonExisting_Returns404NotFound
GivenPutAsync_WhenServiceRetrieveBySquadNumberAsyncReturnsPlayer_ThenResponseStatusCodeShouldBe204NoContent	PUT_PlayerBySquadNumber_Existing_Returns204NoContent
GivenDeleteAsync_WhenServiceRetrieveBySquadNumberAsyncReturnsNull_ThenResponseStatusCodeShouldBe404NotFound	DELETE_PlayerBySquadNumber_NonExisting_Returns404NotFound
GivenDeleteAsync_WhenServiceRetrieveBySquadNumberAsyncReturnsPlayer_ThenResponseStatusCodeShouldBe204NoContent	DELETE_PlayerBySquadNumber_Existing_Returns204NoContent

Service tests (PlayerServiceTests.cs)

Before	After
GivenCreateAsync_WhenRepositoryAddAsync_ThenAddsPlayerToRepositoryAndRemovesCache	CreateAsync_WhenCalled_AddsPlayerAndRemovesCache
GivenRetrieveAsync_WhenRepositoryGetAllAsyncReturnsPlayers_ThenCacheCreateEntryAndResultShouldBeListOfPlayers	RetrieveAsync_CacheMiss_QueriesRepositoryAndCachesResult
GivenRetrieveAsync_WhenExecutedForTheSecondTime_ThenSecondExecutionTimeShouldBeLessThanFirst	RetrieveAsync_CacheHit_ReturnsBeforeQueryingRepository
GivenRetrieveByIdAsync_WhenRepositoryFindByIdAsyncReturnsNull_TheResultShouldBeNull	RetrieveByIdAsync_PlayerNotFound_ReturnsNull
GivenRetrieveByIdAsync_WhenRepositoryFindByIdAsyncReturnsPlayer_TheResultShouldBePlayer	RetrieveByIdAsync_PlayerFound_ReturnsMappedResponseModel
GivenRetrieveBySquadNumberAsync_WhenRepositoryFindBySquadNumberAsyncReturnsNull_ThenResultShouldBeNull	RetrieveBySquadNumberAsync_PlayerNotFound_ReturnsNull
GivenRetrieveBySquadNumberAsync_WhenRepositoryFindBySquadNumberAsyncReturnsPlayer_ThenResultShouldBePlayer	RetrieveBySquadNumberAsync_PlayerFound_ReturnsMappedResponseModel
GivenUpdateAsync_WhenRepositoryFindBySquadNumberAsyncReturnsPlayer_ThenRepositoryUpdateAsyncAndCacheRemove	UpdateAsync_PlayerFound_UpdatesRepositoryAndRemovesCache
GivenDeleteAsync_WhenRepositoryFindBySquadNumberAsyncReturnsPlayer_ThenRepositoryDeleteAsyncAndCacheRemove	DeleteAsync_PlayerFound_RemovesFromRepositoryAndRemovesCache

Validator tests (PlayerValidatorTests.cs)

Before	After
GivenValidateAsync_WhenRequestModelIsValid_ThenValidationShouldPass	ValidateAsync_ValidRequest_ReturnsNoErrors
GivenValidateAsync_WhenFirstNameIsEmpty_ThenValidationShouldFail	ValidateAsync_FirstNameEmpty_ReturnsValidationError
GivenValidateAsync_WhenLastNameIsEmpty_ThenValidationShouldFail	ValidateAsync_LastNameEmpty_ReturnsValidationError
GivenValidateAsync_WhenSquadNumberIsNotGreaterThanZero_ThenValidationShouldFail	ValidateAsync_SquadNumberNotGreaterThanZero_ReturnsValidationError
GivenValidateAsync_WhenSquadNumberIsNotUnique_ThenValidationShouldFail	ValidateAsync_SquadNumberNotUnique_ReturnsValidationError
GivenValidateAsync_WhenAbbrPositionIsEmpty_ThenValidationShouldFail	ValidateAsync_AbbrPositionEmpty_ReturnsValidationError
GivenValidateAsync_WhenAbbrPositionIsInvalid_ThenValidationShouldFail	ValidateAsync_AbbrPositionInvalid_ReturnsValidationError
GivenValidateAsync_WhenDateOfBirthIsNull_ThenValidationShouldPass	ValidateAsync_DateOfBirthNull_ReturnsNoErrors
GivenValidateAsync_WhenDateOfBirthIsInTheFuture_ThenValidationShouldFail	ValidateAsync_DateOfBirthInFuture_ReturnsValidationError
GivenValidateAsync_WhenDateOfBirthIsBeforeYear1900_ThenValidationShouldFail	ValidateAsync_DateOfBirthBeforeYear1900_ReturnsValidationError

Acceptance Criteria

• All PlayerControllerTests.cs methods follow {METHOD}_{Resource}_{Condition}_Returns{Outcome}
• All PlayerServiceTests.cs methods follow {MethodName}_{StateUnderTest}_{ExpectedBehavior}
• All PlayerValidatorTests.cs methods follow {MethodName}_{StateUnderTest}_{ExpectedBehavior}
• All 33 tests pass after renaming

References

• Unit testing best practices for .NET — Microsoft Learn (official)
• Naming Standards for Unit Tests — Roy Osherove (cited by Microsoft; origin of UnitOfWork_StateUnderTest_ExpectedBehavior)
• test/Dotnet.Samples.AspNetCore.WebApi.Tests/Unit/PlayerControllerTests.cs
• test/Dotnet.Samples.AspNetCore.WebApi.Tests/Unit/PlayerServiceTests.cs
• test/Dotnet.Samples.AspNetCore.WebApi.Tests/Unit/PlayerValidatorTests.cs

[coderabbitai]

🔗 Related PRs

#189 - feat(data)!: implement Repository pattern [merged]
#194 - feat(service)!: migrate to AutoMapper for Model mapping [merged]
#206 - refactor(tests): more idiomatic Fake methods and result assertions [merged]
#208 - feature/identifiers [merged]
#352 - refactor: consolidate player data into single source of truth (#210) [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Summary

• Direct method rename operation with no structural changes—ticket provides explicit before/after mappings for all 33 methods
• Controller tests adopt HTTP-semantic pattern (GET_Players_Existing_ReturnsPlayers) while service and validator tests use the pure Microsoft standard (MethodName_State_Behavior)
• No CI/CD, configuration, or external file updates required—exploration confirmed no external references to test method names exist

Implementation Steps

Rename Test Methods to Microsoft Standard

This phase applies the new naming conventions to all 33 test methods across the three test files. Each file follows a layer-appropriate pattern as specified in the ticket. Since the ticket provides explicit before/after mappings for every method, implementation is a direct application of those mappings.

Task 1: Rename Controller Test Methods

Apply the HTTP-semantic naming pattern {METHOD}_{Resource}_{Condition}_Returns{Outcome} to all 14 methods in the controller test file.

• Update test/Dotnet.Samples.AspNetCore.WebApi.Tests/Unit/PlayerControllerTests.cs to rename all test methods
• Apply the mappings from the ticket's "Controller tests" table exactly (e.g., GivenGetAsync_WhenServiceRetrieveAsyncReturnsListOfPlayers_... → GET_Players_Existing_ReturnsPlayers)
• Preserve all method bodies, attributes ([Fact], [Trait]), and class structure unchanged—only method names change

Task 2: Rename Service Test Methods

Apply the standard {MethodName}_{StateUnderTest}_{ExpectedBehavior} pattern to all 9 methods in the service test file.

• Update test/Dotnet.Samples.AspNetCore.WebApi.Tests/Unit/PlayerServiceTests.cs to rename all test methods
• Apply the mappings from the ticket's "Service tests" table exactly (e.g., GivenCreateAsync_WhenRepositoryAddAsync_... → CreateAsync_WhenCalled_AddsPlayerAndRemovesCache)
• Note: Two existing methods had a typo (TheResultShouldBeNull instead of ThenResultShouldBeNull)—these get corrected automatically via the new names

Task 3: Rename Validator Test Methods

Apply the standard {MethodName}_{StateUnderTest}_{ExpectedBehavior} pattern to all 10 methods in the validator test file.

• Update test/Dotnet.Samples.AspNetCore.WebApi.Tests/Unit/PlayerValidatorTests.cs to rename all test methods
• Apply the mappings from the ticket's "Validator tests" table exactly (e.g., GivenValidateAsync_WhenRequestModelIsValid_... → ValidateAsync_ValidRequest_ReturnsNoErrors)

Task 4: Verify Test Suite Passes

Confirm all 33 tests execute successfully with the new names.

• Run dotnet test against the test project to verify all tests pass
• Ensure test count remains at 33 and no tests are skipped or broken due to rename

🤖 Prompt for AI agents

Rename all 33 test methods across three test files from BDD-style
Given/When/Then naming to the Microsoft-endorsed naming conventions. Only method
names should change—all method bodies, attributes, and class structure must
remain untouched.

**File 1:
`test/Dotnet.Samples.AspNetCore.WebApi.Tests/Unit/PlayerControllerTests.cs`**
- Apply the HTTP-semantic pattern
`{METHOD}_{Resource}_{Condition}_Returns{Outcome}` to all 14 test methods
- Use the ticket's "Controller tests" before/after mapping table exactly (e.g.,
`GivenGetAsync_WhenServiceRetrieveAsyncReturnsListOfPlayers_...` →
`GET_Players_Existing_ReturnsPlayers`)

**File 2:
`test/Dotnet.Samples.AspNetCore.WebApi.Tests/Unit/PlayerServiceTests.cs`**
- Apply the standard `{MethodName}_{StateUnderTest}_{ExpectedBehavior}` pattern
to all 9 test methods
- Use the ticket's "Service tests" before/after mapping table exactly (e.g.,
`GivenCreateAsync_WhenRepositoryAddAsync_...` →
`CreateAsync_WhenCalled_AddsPlayerAndRemovesCache`)
- Note: Two existing methods had a typo (`TheResultShouldBeNull` instead of
`ThenResultShouldBeNull`)—the new names correct this automatically

**File 3:
`test/Dotnet.Samples.AspNetCore.WebApi.Tests/Unit/PlayerValidatorTests.cs`**
- Apply the standard `{MethodName}_{StateUnderTest}_{ExpectedBehavior}` pattern
to all 10 test methods
- Use the ticket's "Validator tests" before/after mapping table exactly (e.g.,
`GivenValidateAsync_WhenRequestModelIsValid_...` →
`ValidateAsync_ValidRequest_ReturnsNoErrors`)

**Verification:**
- After renaming, run `dotnet test` against the test project
- Confirm all 33 tests pass and none are skipped or broken

Research

The test suite resides in test/Dotnet.Samples.AspNetCore.WebApi.Tests/Unit/ and contains three test classes: PlayerControllerTests.cs (14 methods), PlayerServiceTests.cs (9 methods), and PlayerValidatorTests.cs (10 methods). All tests use xUnit with [Fact] and [Trait("Category", "Unit")] attributes—no [Theory], [DisplayName], or parameterized test attributes exist. No CI/CD pipelines, .runsettings, or external configurations reference individual test method names, making this a self-contained rename operation with no ripple effects.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Rename all 33 test methods across three test files from BDD-style
Given/When/Then naming to the Microsoft-endorsed naming conventions. Only method
names should change—all method bodies, attributes, and class structure must
remain untouched.

**File 1:
`test/Dotnet.Samples.AspNetCore.WebApi.Tests/Unit/PlayerControllerTests.cs`**
- Apply the HTTP-semantic pattern
`{METHOD}_{Resource}_{Condition}_Returns{Outcome}` to all 14 test methods
- Use the ticket's "Controller tests" before/after mapping table exactly (e.g.,
`GivenGetAsync_WhenServiceRetrieveAsyncReturnsListOfPlayers_...` →
`GET_Players_Existing_ReturnsPlayers`)

**File 2:
`test/Dotnet.Samples.AspNetCore.WebApi.Tests/Unit/PlayerServiceTests.cs`**
- Apply the standard `{MethodName}_{StateUnderTest}_{ExpectedBehavior}` pattern
to all 9 test methods
- Use the ticket's "Service tests" before/after mapping table exactly (e.g.,
`GivenCreateAsync_WhenRepositoryAddAsync_...` →
`CreateAsync_WhenCalled_AddsPlayerAndRemovesCache`)
- Note: Two existing methods had a typo (`TheResultShouldBeNull` instead of
`ThenResultShouldBeNull`)—the new names correct this automatically

**File 3:
`test/Dotnet.Samples.AspNetCore.WebApi.Tests/Unit/PlayerValidatorTests.cs`**
- Apply the standard `{MethodName}_{StateUnderTest}_{ExpectedBehavior}` pattern
to all 10 test methods
- Use the ticket's "Validator tests" before/after mapping table exactly (e.g.,
`GivenValidateAsync_WhenRequestModelIsValid_...` →
`ValidateAsync_ValidRequest_ReturnsNoErrors`)

**Verification:**
- After renaming, run `dotnet test` against the test project
- Confirm all 33 tests pass and none are skipped or broken

💡 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!