test: adopt BDD Given-When-Then pattern across all tests

- Rename all test methods to givenX_whenY_thenZ() format
- Replace AssertJ assertThat() with BDDAssertions then()
- Update code comments from Arrange/Act/Assert to Given/When/Then
- Apply semantic variable naming (expected/actual for assertions, dto/entity for setup)
- Eliminate magic strings/numbers from assertions
- Update all JavaDocs to abstract business descriptions
- Ensure comprehensive object comparisons using usingRecursiveComparison()
- Reorder test methods to match controller/service method order
- Refactor searchBySquadNumber to retrieveBySquadNumber (RESTful GET pattern)

Author: nanotaboada

src/main/java/ar/com/nanotaboada/java/samples/spring/boot/controllers/PlayersController.java

@@ -39,7 +39,7 @@
  * <li><b>GET</b> {@code /players} - Retrieve all players</li>
  * <li><b>GET</b> {@code /players/{id}} - Retrieve player by ID</li>
  * <li><b>GET</b> {@code /players/search/league/{league}} - Search players by league name</li>
- * <li><b>GET</b> {@code /players/search/squadnumber/{number}} - Search player by squad number</li>
+ * <li><b>GET</b> {@code /players/squadnumber/{number}} - Retrieve player by squad number</li>
  * <li><b>POST</b> {@code /players} - Create a new player</li>
  * <li><b>PUT</b> {@code /players/{id}} - Update an existing player</li>
  * <li><b>DELETE</b> {@code /players/{id}} - Delete a player by ID</li>
@@ -113,6 +113,24 @@ public ResponseEntity<Void> post(@RequestBody @Valid PlayerDTO playerDTO) {
      * -----------------------------------------------------------------------------------------------------------------------
      */
 
+    /**
+     * Retrieves all players in the squad.
+     * <p>
+     * Returns the complete Argentina 2022 FIFA World Cup squad (26 players).
+     * </p>
+     *
+     * @return 200 OK with array of all players (empty array if none found)
+     */
+    @GetMapping("/players")
+    @Operation(summary = "Retrieves all players")
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "OK", content = @Content(mediaType = "application/json", schema = @Schema(implementation = PlayerDTO[].class)))
+    })
+    public ResponseEntity<List<PlayerDTO>> getAll() {
+        List<PlayerDTO> players = playersService.retrieveAll();
+        return ResponseEntity.status(HttpStatus.OK).body(players);
+    }
+
     /**
      * Retrieves a single player by their unique identifier.
      *
@@ -133,21 +151,26 @@ public ResponseEntity<PlayerDTO> getById(@PathVariable Long id) {
     }
 
     /**
-     * Retrieves all players in the squad.
+     * Retrieves a player by their squad number (unique identifier).
      * <p>
-     * Returns the complete Argentina 2022 FIFA World Cup squad (26 players).
+     * Squad numbers are unique jersey numbers (e.g., Messi is #10). This is a direct lookup similar to getById().
+     * Example: {@code /players/squadnumber/10} returns Lionel Messi
      * </p>
      *
-     * @return 200 OK with array of all players (empty array if none found)
+     * @param squadNumber the squad number to retrieve (jersey number, typically 1-99)
+     * @return 200 OK with player data, or 404 Not Found if no player has that number
      */
-    @GetMapping("/players")
-    @Operation(summary = "Retrieves all players")
+    @GetMapping("/players/squadnumber/{squadNumber}")
+    @Operation(summary = "Retrieves a player by squad number")
     @ApiResponses(value = {
-            @ApiResponse(responseCode = "200", description = "OK", content = @Content(mediaType = "application/json", schema = @Schema(implementation = PlayerDTO[].class)))
+            @ApiResponse(responseCode = "200", description = "OK", content = @Content(mediaType = "application/json", schema = @Schema(implementation = PlayerDTO.class))),
+            @ApiResponse(responseCode = "404", description = "Not Found", content = @Content)
     })
-    public ResponseEntity<List<PlayerDTO>> getAll() {
-        List<PlayerDTO> players = playersService.retrieveAll();
-        return ResponseEntity.status(HttpStatus.OK).body(players);
+    public ResponseEntity<PlayerDTO> getBySquadNumber(@PathVariable Integer squadNumber) {
+        PlayerDTO player = playersService.retrieveBySquadNumber(squadNumber);
+        return (player != null)
+                ? ResponseEntity.status(HttpStatus.OK).body(player)
+                : ResponseEntity.status(HttpStatus.NOT_FOUND).build();
     }
 
     /**
@@ -169,30 +192,6 @@ public ResponseEntity<List<PlayerDTO>> searchByLeague(@PathVariable String leagu
         return ResponseEntity.status(HttpStatus.OK).body(players);
     }
 
-    /**
-     * Searches for a player by their squad number.
-     * <p>
-     * Squad numbers are jersey numbers that users recognize (e.g., Messi is #10).
-     * Example: {@code /players/search/squadnumber/10} returns Lionel Messi
-     * </p>
-     *
-     * @param squadNumber the squad number to search for (jersey number, typically 1-99)
-     * @return 200 OK with player data, or 404 Not Found if no player has that
-     * number
-     */
-    @GetMapping("/players/search/squadnumber/{squadNumber}")
-    @Operation(summary = "Searches for a player by squad number")
-    @ApiResponses(value = {
-            @ApiResponse(responseCode = "200", description = "OK", content = @Content(mediaType = "application/json", schema = @Schema(implementation = PlayerDTO.class))),
-            @ApiResponse(responseCode = "404", description = "Not Found", content = @Content)
-    })
-    public ResponseEntity<PlayerDTO> searchBySquadNumber(@PathVariable Integer squadNumber) {
-        PlayerDTO player = playersService.searchBySquadNumber(squadNumber);
-        return (player != null)
-                ? ResponseEntity.status(HttpStatus.OK).body(player)
-                : ResponseEntity.status(HttpStatus.NOT_FOUND).build();
-    }
-
     /*
      * -----------------------------------------------------------------------------------------------------------------------
      * HTTP PUT

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

@@ -40,20 +40,6 @@
 @Repository
 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.
-     * For example, searching for "Premier" will match "Premier League".
-     * </p>
-     *
-     * @param league the league name to search for (partial matches allowed)
-     * @return a list of players whose league name contains the search term (empty
-     * list if none found)
-     */
-    @Query("SELECT p FROM Player p WHERE LOWER(p.league) LIKE LOWER(CONCAT('%', :league, '%'))")
-    List<Player> findByLeagueContainingIgnoreCase(@Param("league") String league);
-
     /**
      * Finds a player by their squad number (exact match).
      * <p>
@@ -67,4 +53,18 @@ public interface PlayersRepository extends JpaRepository<Player, Long> {
      * @return an Optional containing the player if found, empty Optional otherwise
      */
     Optional<Player> findBySquadNumber(Integer squadNumber);
+
+    /**
+     * Finds players by league name using case-insensitive wildcard matching.
+     * <p>
+     * This method uses a custom JPQL query with LIKE operator for partial matches.
+     * For example, searching for "Premier" will match "Premier League".
+     * </p>
+     *
+     * @param league the league name to search for (partial matches allowed)
+     * @return a list of players whose league name contains the search term (empty
+     * list if none found)
+     */
+    @Query("SELECT p FROM Player p WHERE LOWER(p.league) LIKE LOWER(CONCAT('%', :league, '%'))")
+    List<Player> findByLeagueContainingIgnoreCase(@Param("league") String league);
 }

src/main/java/ar/com/nanotaboada/java/samples/spring/boot/services/PlayersService.java

@@ -110,6 +110,24 @@ public PlayerDTO create(PlayerDTO playerDTO) {
      * -----------------------------------------------------------------------------------------------------------------------
      */
 
+    /**
+     * Retrieves all players from the database.
+     * <p>
+     * This method returns the complete Argentina 2022 FIFA World Cup squad (26 players).
+     * Results are cached to improve performance on subsequent calls.
+     * </p>
+     *
+     * @return a list of all players (empty list if none found)
+     * @see org.springframework.cache.annotation.Cacheable
+     */
+    @Cacheable(value = "players")
+    public List<PlayerDTO> retrieveAll() {
+        return playersRepository.findAll()
+                .stream()
+                .map(this::mapFrom)
+                .toList();
+    }
+
     /**
      * Retrieves a player by their unique identifier.
      * <p>
@@ -130,21 +148,21 @@ public PlayerDTO retrieveById(Long id) {
     }
 
     /**
-     * Retrieves all players from the database.
+     * Retrieves a player by their squad number (unique identifier).
      * <p>
-     * This method returns the complete Argentina 2022 FIFA World Cup squad (26 players).
-     * Results are cached to improve performance on subsequent calls.
+     * Squad numbers are unique jersey numbers (e.g., Messi is #10). This is a direct lookup by unique identifier,
+     * similar to retrieveById(). Results are cached to improve performance.
      * </p>
      *
-     * @return a list of all players (empty list if none found)
+     * @param squadNumber the squad number to retrieve (jersey number, typically 1-99)
+     * @return the player DTO if found, null otherwise
      * @see org.springframework.cache.annotation.Cacheable
      */
-    @Cacheable(value = "players")
-    public List<PlayerDTO> retrieveAll() {
-        return playersRepository.findAll()
-                .stream()
+    @Cacheable(value = "players", key = "'squad-' + #squadNumber", unless = "#result == null")
+    public PlayerDTO retrieveBySquadNumber(Integer squadNumber) {
+        return playersRepository.findBySquadNumber(squadNumber)
                 .map(this::mapFrom)
-                .toList();
+                .orElse(null);
     }
 
     /*
@@ -170,22 +188,6 @@ public List<PlayerDTO> searchByLeague(String league) {
                 .toList();
     }
 
-    /**
-     * Searches for a player by their squad number.
-     * <p>
-     * This method performs an exact match on the squad number field. Squad numbers are jersey numbers that users recognize
-     * (e.g., Messi is #10).
-     * </p>
-     *
-     * @param squadNumber the squad number to search for (jersey number, typically 1-99)
-     * @return the player DTO if found, null otherwise
-     */
-    public PlayerDTO searchBySquadNumber(Integer squadNumber) {
-        return playersRepository.findBySquadNumber(squadNumber)
-                .map(this::mapFrom)
-                .orElse(null);
-    }
-
     /*
      * -----------------------------------------------------------------------------------------------------------------------
      * Update