feat(device): change xpath filter output format to use === separator

BREAKING CHANGE: The dump_hierarchy tool now returns matching XML
elements separated by "===" instead of simple concatenation when
xpath parameter is provided.

- Update dump_hierarchy and save_dump_hierarchy functions to use
  "===\n" as separator between matching XML elements
- Modify test cases to verify the new separator format
- Update docstrings and comments to reflect the new behavior
- Update changelog to reflect the changes made

Author: tanbro

.coveragerc

@@ -0,0 +1,6 @@
+[run]
+omit =
+    scripts/*
+    tests/*
+    venv/*
+    src/**/version.py

CHANGELOG.md

@@ -8,9 +8,7 @@
     - Add xpath filter parameter to `dump_hierarchy` tool for filtering XML results
 
 - ⚙️ Changed:
-    - Improve type hinting with `types-retry` dependency for better type checking
-    - Add `types-lxml` to dev dependencies for proper type checking
-    - Add type stubs to mypy pre-commit hook for comprehensive type coverage
+    - Add serval type stubs for comprehensive type coverage
 
 ## 0.2.1
 

src/u2mcp/tools/device.py

@@ -289,11 +289,11 @@ async def dump_hierarchy(
         max_depth (int): max depth of hierarchy.
         xpath (str): optional xpath expression to filter results.
             If empty, returns the full hierarchy xml.
-            If provided, returns only matching elements as xml fragments.
+            If provided, returns only matching elements, separated by "===".
 
     Returns:
         str: xml string of the hierarchy tree.
-            If xpath is provided, returns concatenated xml of all matching elements.
+            If xpath is provided, returns matching elements separated by "===".
     """
     async with get_device(serial) as device:
         xml_str = await to_thread.run_sync(
@@ -310,12 +310,12 @@ async def dump_hierarchy(
     if not nodes:
         return ""
 
-    # Return concatenated xml of matching nodes
+    # Return xml of matching nodes, separated by ===
     result_parts: list[str] = []
     for node in nodes:
         result_parts.append(etree.tostring(node, encoding="unicode"))
 
-    return "\n".join(result_parts) if len(result_parts) > 1 else result_parts[0] if result_parts else ""
+    return "\n===\n".join(result_parts)
 
 
 @mcp.tool("save_dump_hierarchy", tags={"device:capture"})
@@ -337,7 +337,7 @@ async def save_dump_hierarchy(
         max_depth (int): max depth of hierarchy.
         xpath (str): optional xpath expression to filter results.
             If empty, saves the full hierarchy xml.
-            If provided, saves only matching elements as xml fragments.
+            If provided, saves only matching elements, separated by "===".
 
     Returns:
         str: absolute path to the saved file.
@@ -356,7 +356,7 @@ async def save_dump_hierarchy(
             result_parts: list[str] = []
             for node in nodes:
                 result_parts.append(etree.tostring(node, encoding="unicode"))
-            xml_str = "\n".join(result_parts) if len(result_parts) > 1 else result_parts[0] if result_parts else ""
+            xml_str = "\n===\n".join(result_parts)
         else:
             xml_str = ""
 

tests/unit/test_device.py

@@ -230,7 +230,7 @@ async def test_dump_hierarchy_with_xpath_single_match(mock_u2_device: MagicMock)
 @pytest.mark.asyncio
 @pytest.mark.unit
 async def test_dump_hierarchy_with_xpath_multiple_matches(mock_u2_device: MagicMock) -> None:
-    """Test dump_hierarchy returns concatenated XML when xpath matches multiple nodes."""
+    """Test dump_hierarchy returns XML separated by === when xpath matches multiple nodes."""
     sample_xml = """<?xml version='1.0' encoding='UTF-8'?>
 <hierarchy>
     <node resource-id="button1" text="Button 1" clickable="true"/>
@@ -241,10 +241,12 @@ async def test_dump_hierarchy_with_xpath_multiple_matches(mock_u2_device: MagicM
 
     result = await dump_hierarchy.fn("emulator-5554", xpath="//*[@clickable='true']")
 
-    # Should return both clickable buttons
+    # Should return both clickable buttons separated by ===
     assert 'resource-id="button1"' in result
     assert 'resource-id="button2"' in result
     assert 'clickable="true"' in result
+    # Check for === separator
+    assert "\n===\n" in result
     # Should not contain the non-clickable element
     assert 'resource-id="text"' not in result