test(api): add tests for cash_out API function

Author: S1M0N38

tests/test_api_functions.py

@@ -410,3 +410,58 @@ def test_try_to_discard_when_no_discards_left(
         assert isinstance(response, dict)
         assert "error" in response
         assert "No discards left" in response["error"]
+
+
+class TestCashOut:
+    """Tests for the cash_out API endpoint."""
+
+    @pytest.fixture(autouse=True)
+    def setup_and_teardown(
+        self, udp_client: socket.socket
+    ) -> Generator[None, None, None]:
+        """Set up and tear down each test method."""
+        # Start a run
+        start_run_args = {
+            "deck": "Red Deck",
+            "stake": 1,
+            "challenge": None,
+            "seed": "OOOO155",  # four of a kind in first hand
+        }
+        send_and_receive_api_message(udp_client, "start_run", start_run_args)
+
+        # Select blind
+        send_and_receive_api_message(
+            udp_client, "skip_or_select_blind", {"action": "select"}
+        )
+
+        # Play a winning hand (four of a kind) to reach shop
+        game_state = send_and_receive_api_message(
+            udp_client,
+            "play_hand_or_discard",
+            {"action": "play_hand", "cards": [0, 1, 2, 3]},
+        )
+        assert game_state["state"] == State.ROUND_EVAL.value
+        yield
+        send_and_receive_api_message(udp_client, "go_to_menu", {})
+
+    def test_cash_out_success(self, udp_client: socket.socket) -> None:
+        """Test successful cash out returns to shop state."""
+        # Cash out should transition to shop state
+        game_state = send_and_receive_api_message(udp_client, "cash_out", {})
+
+        # Verify we're in shop state after cash out
+        assert game_state["state"] == State.SHOP.value
+
+    def test_cash_out_invalid_state_error(self, udp_client: socket.socket) -> None:
+        """Test cash out returns error when not in shop state."""
+        # Go to menu first to ensure we're not in shop state
+        send_and_receive_api_message(udp_client, "go_to_menu", {})
+
+        # Try to cash out when not in shop - should return error
+        response = send_and_receive_api_message(udp_client, "cash_out", {})
+
+        # Verify error response
+        assert isinstance(response, dict)
+        assert "error" in response
+        assert "Cannot cash out when not in shop" in response["error"]
+        assert "state" in response