test: strengthen traverse assertions and add validation unit tests

- test_traverse_returns_neighbours: assert the specific leaf1 node ID is in
  result.nodes, not just that the count is non-zero
- test_traverse_inbound_direction: capture src_id alongside dst_id so that
  when the server gains inbound support (XPASS), the assertion validates the
  correct node was returned
- TestTraverseValidation: new unit test class for ValueError cases in
  AsyncCoordinodeClient.traverse() — invalid direction and max_depth < 1;
  validation fires before any RPC so no running server is required

Author: polaz

tests/integration/test_sdk.py

@@ -276,9 +276,20 @@ def test_traverse_returns_neighbours(client):
         )
         assert len(rows) >= 1, "hub node not found"
         start_id = rows[0]["node_id"]
+
+        # Fetch the leaf1 node ID so we can assert it specifically appears in the result.
+        leaf_rows = client.cypher(
+            "MATCH (b:TraverseRPC {tag: $tag, role: 'leaf1'}) RETURN b AS node_id",
+            params={"tag": tag},
+        )
+        assert len(leaf_rows) >= 1, "leaf1 node not found"
+        leaf1_id = leaf_rows[0]["node_id"]
+
         result = client.traverse(start_id, "TRAVERSE_TEST", direction="outbound", max_depth=1)
         assert isinstance(result, TraverseResult)
         assert len(result.nodes) >= 1, "traverse() returned no neighbour nodes"
+        node_ids = {n.id for n in result.nodes}
+        assert leaf1_id in node_ids, f"traverse() did not return the expected leaf1 node ({leaf1_id}); got: {node_ids}"
     finally:
         client.cypher("MATCH (n:TraverseRPC {tag: $tag}) DETACH DELETE n", params={"tag": tag})
 
@@ -298,16 +309,23 @@ def test_traverse_inbound_direction(client):
         params={"tag": tag},
     )
     try:
-        # Get dst node id — traverse INBOUND from dst should reach src.
+        # Capture both src and dst so that when the server gains inbound support
+        # (XPASS), the assertion verifies the *correct* node was returned, not just any node.
         rows = client.cypher(
-            "MATCH (src:TraverseIn {tag: $tag})-[:INBOUND_TEST]->(dst:TraverseIn {tag: $tag}) RETURN dst AS node_id",
+            "MATCH (src:TraverseIn {tag: $tag})-[:INBOUND_TEST]->(dst:TraverseIn {tag: $tag}) "
+            "RETURN src AS src_id, dst AS dst_id",
             params={"tag": tag},
         )
         assert len(rows) >= 1
-        dst_id = rows[0]["node_id"]
+        src_id = rows[0]["src_id"]
+        dst_id = rows[0]["dst_id"]
         result = client.traverse(dst_id, "INBOUND_TEST", direction="inbound", max_depth=1)
         assert isinstance(result, TraverseResult)
         assert len(result.nodes) >= 1, "inbound traverse returned no nodes"
+        node_ids = {n.id for n in result.nodes}
+        assert src_id in node_ids, (
+            f"inbound traverse did not return the expected source node ({src_id}); got: {node_ids}"
+        )
     finally:
         client.cypher("MATCH (n:TraverseIn {tag: $tag}) DETACH DELETE n", params={"tag": tag})
 

tests/unit/test_schema_crud.py

@@ -5,7 +5,12 @@
 interface that real generated messages provide.
 """
 
+import asyncio
+
+import pytest
+
 from coordinode.client import (
+    AsyncCoordinodeClient,
     EdgeResult,
     EdgeTypeInfo,
     LabelInfo,
@@ -189,3 +194,34 @@ def test_repr_shows_counts(self):
         r = repr(result)
         assert "nodes=1" in r
         assert "edges=0" in r
+
+
+# ── traverse() input validation ──────────────────────────────────────────────
+
+
+class TestTraverseValidation:
+    """Unit tests for AsyncCoordinodeClient.traverse() input validation.
+
+    Validation (direction and max_depth checks) runs before any RPC call, so no
+    running server is required — only the client object needs to be instantiated.
+    """
+
+    def test_invalid_direction_raises(self):
+        """traverse() raises ValueError for an unrecognised direction string."""
+
+        async def _inner() -> None:
+            client = AsyncCoordinodeClient("localhost:0")
+            with pytest.raises(ValueError, match="Invalid direction"):
+                await client.traverse(1, "KNOWS", direction="sideways")
+
+        asyncio.run(_inner())
+
+    def test_max_depth_below_one_raises(self):
+        """traverse() raises ValueError when max_depth is less than 1."""
+
+        async def _inner() -> None:
+            client = AsyncCoordinodeClient("localhost:0")
+            with pytest.raises(ValueError, match="max_depth must be >= 1"):
+                await client.traverse(1, "KNOWS", max_depth=0)
+
+        asyncio.run(_inner())