refactor(tests): improve test clarity and fix stale documentation

Author: nanotaboada

src/main/java/ar/com/nanotaboada/java/samples/spring/boot/repositories/PlayersRepository.java

@@ -24,8 +24,8 @@
  *
  * <h3>Query Strategies:</h3>
  * <ul>
- * <li><b>@Query:</b> Explicit JPQL for complex searches (findByLeagueContainingIgnoreCase)</li>
- * <li><b>Method Names:</b> Spring Data derives queries from method names (Query Creation)</li>
+ * <li><b>Derived Queries:</b> Spring Data derives queries from method names (findBySquadNumber,
+ * findByLeagueContainingIgnoreCase)</li>
  * </ul>
  *
  * @see Player
@@ -55,7 +55,7 @@ public interface PlayersRepository extends JpaRepository<Player, Long> {
     /**
      * Finds players by league name using case-insensitive wildcard matching.
      * <p>
-     * This method uses a custom JPQL query with LIKE operator for partial matches.
+     * This method uses Spring Data's derived query mechanism to perform partial matching.
      * For example, searching for "Premier" will match "Premier League".
      * </p>
      *

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

@@ -184,7 +184,6 @@ void givenPlayersExist_whenGetAll_thenReturnsOkWithAllPlayers()
         then(response.getContentType()).contains("application/json");
         verify(playersServiceMock, times(1)).retrieveAll();
         then(response.getStatus()).isEqualTo(HttpStatus.OK.value());
-        then(actual).hasSize(26);
         then(actual).usingRecursiveComparison().isEqualTo(expected);
     }
 
@@ -331,7 +330,6 @@ void givenPlayersExist_whenSearchByLeague_thenReturnsOk()
         then(response.getContentType()).contains("application/json");
         verify(playersServiceMock, times(1)).searchByLeague(any());
         then(response.getStatus()).isEqualTo(HttpStatus.OK.value());
-        then(actual).hasSize(7);
         then(actual).usingRecursiveComparison().isEqualTo(expected);
     }
 

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

@@ -50,9 +50,9 @@ void givenPlayerExists_whenFindById_thenReturnsPlayer() {
     @Test
     void givenPlayerDoesNotExist_whenFindById_thenReturnsEmpty() {
         // Given
-        Long expected = 999L;
+        Long nonExistentId = 999L;
         // When
-        Optional<Player> actual = repository.findById(expected);
+        Optional<Player> actual = repository.findById(nonExistentId);
         // Then
         then(actual).isEmpty();
     }
@@ -65,12 +65,12 @@ void givenPlayerDoesNotExist_whenFindById_thenReturnsEmpty() {
     @Test
     void givenPlayersExist_whenFindByLeague_thenReturnsList() {
         // Given
-        String expected = "Premier";
+        String leagueName = "Premier";
         // When
-        List<Player> actual = repository.findByLeagueContainingIgnoreCase(expected);
+        List<Player> actual = repository.findByLeagueContainingIgnoreCase(leagueName);
         // Then
         then(actual).isNotEmpty()
-                .allMatch(player -> player.getLeague().toLowerCase().contains(expected.toLowerCase()));
+                .allMatch(player -> player.getLeague().toLowerCase().contains(leagueName.toLowerCase()));
     }
 
     /**
@@ -81,9 +81,9 @@ void givenPlayersExist_whenFindByLeague_thenReturnsList() {
     @Test
     void givenNoPlayersExist_whenFindByLeague_thenReturnsEmptyList() {
         // Given
-        String expected = "Expected League";
+        String nonExistentLeague = "Nonexistent League";
         // When
-        List<Player> actual = repository.findByLeagueContainingIgnoreCase(expected);
+        List<Player> actual = repository.findByLeagueContainingIgnoreCase(nonExistentLeague);
         // Then
         then(actual).isEmpty();
     }
@@ -96,13 +96,14 @@ void givenNoPlayersExist_whenFindByLeague_thenReturnsEmptyList() {
     @Test
     void givenPlayerExists_whenFindBySquadNumber_thenReturnsPlayer() {
         // Given
-        Integer expectedSquadNumber = 10; // Messi's squad number from pre-seeded data
+        Integer messiSquadNumber = 10; // Pre-seeded from dml.sql
+        String expectedLastName = "Messi";
         // When
-        Optional<Player> actual = repository.findBySquadNumber(expectedSquadNumber);
+        Optional<Player> actual = repository.findBySquadNumber(messiSquadNumber);
         // Then
         then(actual).isPresent();
-        then(actual.get().getSquadNumber()).isEqualTo(expectedSquadNumber);
-        then(actual.get().getLastName()).isEqualTo("Messi");
+        then(actual.get().getSquadNumber()).isEqualTo(messiSquadNumber);
+        then(actual.get().getLastName()).isEqualTo(expectedLastName);
     }
 
     /**
@@ -113,9 +114,9 @@ void givenPlayerExists_whenFindBySquadNumber_thenReturnsPlayer() {
     @Test
     void givenPlayerDoesNotExist_whenFindBySquadNumber_thenReturnsEmpty() {
         // Given
-        Integer expected = 99;
+        Integer nonExistentSquadNumber = 99;
         // When
-        Optional<Player> actual = repository.findBySquadNumber(expected);
+        Optional<Player> actual = repository.findBySquadNumber(nonExistentSquadNumber);
         // Then
         then(actual).isEmpty();
     }

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

@@ -159,7 +159,6 @@ void givenAllPlayersExist_whenRetrieveAll_thenReturns26Players() {
         List<PlayerDTO> actual = playersService.retrieveAll();
         // Then
         verify(playersRepositoryMock, times(1)).findAll();
-        then(actual).hasSize(26);
         then(actual).usingRecursiveComparison().isEqualTo(dtos);
     }