refactor(test): normalize data-state vocabulary in BDD test names (#303)

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: nanotaboada

CHANGELOG.md

@@ -42,6 +42,11 @@ Release names follow the **historic football clubs** naming convention (A–Z):
 
 ### Changed
 
+- Normalize data-state vocabulary in BDD-style test names: rename 12 `given*`
+  methods across `PlayersServiceTests`, `PlayersControllerTests`, and
+  `PlayersRepositoryTests` to use canonical terms (`existing`, `nonexistent`,
+  `unknown`); add class-level Javadoc to `PlayerFakes` documenting the
+  three-term convention (#303)
 - Normalize player dataset: seed Leandro Paredes (squad 5) permanently; correct
   Enzo Fernández (squad 24) to SL Benfica / Liga Portugal, Alexis Mac Allister
   (squad 20) to Brighton & Hove Albion, and Lionel Messi (squad 10) to Paris

src/test/java/ar/com/nanotaboada/java/samples/spring/boot/test/PlayerFakes.java

@@ -7,6 +7,16 @@
 
 import ar.com.nanotaboada.java.samples.spring.boot.models.Player;
 
+/**
+ * Test data factory for Player entities.
+ *
+ * <p>Data-state vocabulary used in BDD-style test names:
+ * <ul>
+ *   <li>{@code existing} — player is present in the database</li>
+ *   <li>{@code nonexistent} — player is absent, valid shape for creation (POST scenarios)</li>
+ *   <li>{@code unknown} — valid ID format, absent from database (404-by-lookup scenarios)</li>
+ * </ul>
+ */
 public final class PlayerFakes {
 
     private PlayerFakes() {

src/test/java/ar/com/nanotaboada/java/samples/spring/boot/test/controllers/PlayersControllerTests.java

@@ -227,7 +227,7 @@ void givenPlayerExists_whenGetById_thenReturnsOk()
      * Then response status is 404 Not Found
      */
     @Test
-    void givenPlayerDoesNotExist_whenGetById_thenReturnsNotFound()
+    void givenUnknownPlayer_whenGetById_thenReturnsNotFound()
             throws Exception {
         // Given
         UUID id = UUID.randomUUID();
@@ -287,7 +287,7 @@ void givenPlayerExists_whenGetBySquadNumber_thenReturnsOk()
      * Then response status is 404 Not Found
      */
     @Test
-    void givenPlayerDoesNotExist_whenGetBySquadNumber_thenReturnsNotFound()
+    void givenUnknownPlayer_whenGetBySquadNumber_thenReturnsNotFound()
             throws Exception {
         // Given
         Integer squadNumber = 99;
@@ -411,7 +411,7 @@ void givenPlayerExists_whenPut_thenReturnsNoContent()
      * Then response status is 404 Not Found
      */
     @Test
-    void givenPlayerDoesNotExist_whenPut_thenReturnsNotFound()
+    void givenUnknownPlayer_whenPut_thenReturnsNotFound()
             throws Exception {
         // Given
         PlayerDTO dto = PlayerDTOFakes.createOneValid();
@@ -549,7 +549,7 @@ void givenPlayerExists_whenDelete_thenReturnsNoContent()
      * Then response status is 404 Not Found
      */
     @Test
-    void givenPlayerDoesNotExist_whenDelete_thenReturnsNotFound()
+    void givenUnknownPlayer_whenDelete_thenReturnsNotFound()
             throws Exception {
         // Given
         Integer squadNumber = 999;

src/test/java/ar/com/nanotaboada/java/samples/spring/boot/test/repositories/PlayersRepositoryTests.java

@@ -50,7 +50,7 @@ void givenPlayerExists_whenFindById_thenReturnsPlayer() {
      * Then an empty Optional is returned
      */
     @Test
-    void givenPlayerDoesNotExist_whenFindById_thenReturnsEmpty() {
+    void givenUnknownPlayer_whenFindById_thenReturnsEmpty() {
         // Given
         UUID nonExistentId = UUID.randomUUID();
         // When
@@ -114,7 +114,7 @@ void givenPlayerExists_whenFindBySquadNumber_thenReturnsPlayer() {
      * Then an empty Optional is returned
      */
     @Test
-    void givenPlayerDoesNotExist_whenFindBySquadNumber_thenReturnsEmpty() {
+    void givenUnknownPlayer_whenFindBySquadNumber_thenReturnsEmpty() {
         // Given
         Integer nonExistentSquadNumber = 99;
         // When

src/test/java/ar/com/nanotaboada/java/samples/spring/boot/test/services/PlayersServiceTests.java

@@ -52,7 +52,7 @@ class PlayersServiceTests {
      * Then the player is saved and a PlayerDTO is returned
      */
     @Test
-    void givenNoExistingPlayer_whenCreate_thenReturnsPlayerDTO() {
+    void givenNonexistentPlayer_whenCreate_thenReturnsPlayerDTO() {
         // Given
         Player entity = PlayerFakes.createOneValid();
         PlayerDTO expected = PlayerDTOFakes.createOneValid();
@@ -84,7 +84,7 @@ void givenNoExistingPlayer_whenCreate_thenReturnsPlayerDTO() {
      * Then null is returned (conflict detected)
      */
     @Test
-    void givenPlayerAlreadyExists_whenCreate_thenReturnsNull() {
+    void givenExistingPlayer_whenCreate_thenReturnsNull() {
         // Given
         PlayerDTO dto = PlayerDTOFakes.createOneValid();
         Integer expectedSquadNumber = 10;
@@ -192,7 +192,7 @@ void givenPlayerExists_whenRetrieveById_thenReturnsPlayerDTO() {
      * Then null is returned
      */
     @Test
-    void givenPlayerDoesNotExist_whenRetrieveById_thenReturnsNull() {
+    void givenUnknownPlayer_whenRetrieveById_thenReturnsNull() {
         // Given
         UUID id = UUID.randomUUID();
         Mockito
@@ -244,7 +244,7 @@ void givenPlayerExists_whenRetrieveBySquadNumber_thenReturnsPlayerDTO() {
      * Then null is returned
      */
     @Test
-    void givenPlayerDoesNotExist_whenRetrieveBySquadNumber_thenReturnsNull() {
+    void givenUnknownPlayer_whenRetrieveBySquadNumber_thenReturnsNull() {
         // Given
         Integer squadNumber = 99;
         Mockito
@@ -355,7 +355,7 @@ void givenPlayerExists_whenUpdate_thenReturnsTrue() {
      * Then false is returned without saving
      */
     @Test
-    void givenPlayerDoesNotExist_whenUpdate_thenReturnsFalse() {
+    void givenUnknownPlayer_whenUpdate_thenReturnsFalse() {
         // Given
         PlayerDTO dto = PlayerDTOFakes.createOneValid();
         Integer squadNumber = 999;
@@ -422,7 +422,7 @@ void givenPlayerExists_whenDelete_thenReturnsTrue() {
      * Then false is returned without deleting
      */
     @Test
-    void givenPlayerDoesNotExist_whenDelete_thenReturnsFalse() {
+    void givenUnknownPlayer_whenDelete_thenReturnsFalse() {
         // Given
         Integer squadNumber = 999;
         Mockito