tests: add unit tests for client routes

Cover ClientRouteEntry/ClientRoutesConfig validation, _RouteStore
get/merge operations, _ClientRoutesHandler initialization,
ClientRoutesEndPoint resolution with and without route mappings,
and SSL check_hostname rejection with client_routes_config.

Author: sylwiaszunejko

tests/unit/test_client_routes.py

@@ -0,0 +1,211 @@
+# Copyright 2026 ScyllaDB, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import ssl
+import unittest
+import uuid
+from unittest.mock import Mock, patch
+
+from cassandra.client_routes import (
+    ClientRouteProxy,
+    ClientRoutesConfig,
+    _RouteStore,
+    _Route,
+    _ClientRoutesHandler
+)
+from cassandra.connection import ClientRoutesEndPoint
+from cassandra.cluster import Cluster
+from cassandra import DriverException
+
+
+class TestClientRouteProxy(unittest.TestCase):
+
+    def test_endpoint_none_connection_id(self):
+        with self.assertRaises(ValueError):
+            ClientRouteProxy(None)
+
+
+class TestClientRoutesConfig(unittest.TestCase):
+
+    def test_config_with_proxies(self):
+        ep1 = ClientRouteProxy(str(uuid.uuid4()), "10.0.0.1")
+        ep2 = ClientRouteProxy(str(uuid.uuid4()), "10.0.0.2")
+        config = ClientRoutesConfig([ep1, ep2])
+        self.assertEqual(len(config.proxies), 2)
+
+    def test_config_empty_proxies(self):
+        with self.assertRaises(ValueError):
+            ClientRoutesConfig([])
+
+    def test_config_invalid_proxy_type(self):
+        with self.assertRaises(TypeError):
+            ClientRoutesConfig(["not-a-proxy"])
+
+
+
+class TestRouteStore(unittest.TestCase):
+
+    def test_get_by_host_id(self):
+        routes = _RouteStore()
+        host_id = uuid.uuid4()
+        route = _Route(
+            connection_id=str(uuid.uuid4()),
+            host_id=host_id,
+            address="example.com",
+            port=9042,
+        )
+
+        routes.update([route])
+
+        retrieved = routes.get_by_host_id(host_id)
+        self.assertEqual(retrieved.host_id, host_id)
+        self.assertEqual(retrieved.address, "example.com")
+
+    def test_merge_routes(self):
+        routes = _RouteStore()
+        host_id1 = uuid.uuid4()
+        host_id2 = uuid.uuid4()
+
+        route1 = _Route(
+            connection_id=str(uuid.uuid4()), host_id=host_id1,
+            address="host1.com", port=9042,
+        )
+
+        route2 = _Route(
+            connection_id=str(uuid.uuid4()), host_id=host_id2,
+            address="host2.com", port=9042,
+        )
+
+        routes.update([route1])
+        routes.merge([route2])
+
+        self.assertIsNotNone(routes.get_by_host_id(host_id1))
+        self.assertIsNotNone(routes.get_by_host_id(host_id2))
+
+
+class TestClientRoutesHandler(unittest.TestCase):
+
+    def setUp(self):
+        self.conn_id = uuid.uuid4()
+        self.proxy = ClientRouteProxy(str(self.conn_id), "10.0.0.1")
+        self.config = ClientRoutesConfig([self.proxy])
+
+    def test_handler_initialization(self):
+        handler = _ClientRoutesHandler(self.config, ssl_enabled=False)
+        self.assertIsNotNone(handler)
+        self.assertEqual(handler.ssl_enabled, False)
+
+    @patch.object(_ClientRoutesHandler, '_query_routes')
+    def test_initialize(self, mock_query):
+        host_id = uuid.uuid4()
+        mock_query.return_value = [
+            _Route(
+                connection_id=self.conn_id,
+                host_id=host_id,
+                address="node1.example.com",
+                port=9042,
+            )
+        ]
+
+        handler = _ClientRoutesHandler(self.config)
+        mock_control_conn = Mock()
+
+        handler.initialize(mock_control_conn)
+
+        mock_query.assert_called_once()
+        route = handler._routes.get_by_host_id(host_id)
+        self.assertIsNotNone(route)
+        self.assertEqual(route.address, "node1.example.com")
+
+class TestClientRoutesEndPoint(unittest.TestCase):
+
+    def setUp(self):
+        self.conn_id = uuid.uuid4()
+        self.proxy = ClientRouteProxy(str(self.conn_id), "10.0.0.1")
+        self.config = ClientRoutesConfig([self.proxy])
+        self.handler = _ClientRoutesHandler(self.config, ssl_enabled=False)
+
+    def test_resolve_falls_back_when_no_mapping(self):
+        """resolve() should return original address/port when no route mapping exists."""
+        host_id = uuid.uuid4()
+        ep = ClientRoutesEndPoint(
+            host_id=host_id,
+            handler=self.handler,
+            original_address="10.0.0.1",
+            original_port=9042,
+        )
+        self.assertEqual(ep.resolve(), ("10.0.0.1", 9042))
+
+class TestClientRoutesSSLValidation(unittest.TestCase):
+
+    def test_check_hostname_with_ssl_context_raises(self):
+        """Cluster should reject check_hostname=True with client_routes_config."""
+        ssl_ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+        self.assertTrue(ssl_ctx.check_hostname)
+
+        config = ClientRoutesConfig(
+            proxies=[ClientRouteProxy(str(uuid.uuid4()), "10.0.0.1")]
+        )
+        with self.assertRaises(ValueError) as cm:
+            Cluster(
+                contact_points=["10.0.0.1"],
+                ssl_context=ssl_ctx,
+                client_routes_config=config,
+            )
+        self.assertIn("check_hostname", str(cm.exception))
+
+    def test_check_hostname_with_ssl_options_raises(self):
+        """Cluster should reject check_hostname=True in ssl_options with client_routes_config."""
+        config = ClientRoutesConfig(
+            proxies=[ClientRouteProxy(str(uuid.uuid4()), "10.0.0.1")]
+        )
+        with self.assertRaises(ValueError) as cm:
+            Cluster(
+                contact_points=["10.0.0.1"],
+                ssl_options={'check_hostname': True},
+                client_routes_config=config,
+            )
+        self.assertIn("check_hostname", str(cm.exception))
+
+    def test_disabled_check_hostname_with_client_routes_ok(self):
+        """Cluster should allow check_hostname=False with client_routes_config."""
+        ssl_ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+        ssl_ctx.check_hostname = False
+
+        config = ClientRoutesConfig(
+            proxies=[ClientRouteProxy(str(uuid.uuid4()), "10.0.0.1")]
+        )
+        # Should not raise
+        cluster = Cluster(
+            contact_points=["10.0.0.1"],
+            ssl_context=ssl_ctx,
+            client_routes_config=config,
+        )
+        cluster.shutdown()
+
+    def test_no_ssl_with_client_routes_ok(self):
+        """Cluster should allow client_routes_config without SSL."""
+        config = ClientRoutesConfig(
+            proxies=[ClientRouteProxy(str(uuid.uuid4()), "10.0.0.1")]
+        )
+        # Should not raise
+        cluster = Cluster(
+            contact_points=["10.0.0.1"],
+            client_routes_config=config,
+        )
+        cluster.shutdown()
+
+
+if __name__ == '__main__':
+    unittest.main()