Added tests Docstrings - adapted for devs. Minor refinements.

Author: Intrinsical-AI

rre-dataset-generator/tests/unit/test_vespa_search_engine.py

@@ -17,7 +17,6 @@
 # -----------------------
 # Helpers / monkeypatches
 # -----------------------
-
 def _monkeypatch_schema_ok(monkeypatch, fields=("title", "description", "id")):
     """Simulate GET /schema/fields returning a payload with field names."""
     class _SchemaResp:
@@ -66,7 +65,6 @@ def _post(url, headers=None, json=None, **kwargs):
 # ---------------------
 # Field Value Normalization
 # ---------------------
-
 @pytest.mark.parametrize(
     "input_val, expected_val",
     [
@@ -90,8 +88,12 @@ def test_normalize_field_value_EXPECTS_correct_conversion(input_val, expected_va
 # --------------
 # Happy-path generation
 # --------------
-
 def test_fetch_for_query_generation_EXPECTS_builds_valid_yql_caps_hits_and_parses_response(monkeypatch):
+    """Verify YQL composition, hit capping, and response parsing in the generation flow.
+
+    Args:
+        monkeypatch: PyTest fixture for patching HTTP calls.
+    """
     _monkeypatch_schema_ok(monkeypatch)
 
     # Simulated Vespa response (one hit with title str, description list[str])
@@ -155,16 +157,21 @@ def test_fetch_for_query_generation_EXPECTS_builds_valid_yql_caps_hits_and_parse
 # -------------------
 # Happy-path evaluation/keyword
 # -------------------
-
 def test_fetch_for_evaluation_EXPECTS_properly_quotes_and_escapes_keyword(monkeypatch):
+    """Ensure keyword literals are safely escaped/quoted in evaluation YQL.
+
+    Args:
+        monkeypatch: PyTest fixture for patching HTTP calls.
+    """
     _monkeypatch_schema_ok(monkeypatch)
 
     vespa_raw = {"root": {"children": []}}
     calls = _capture_post(monkeypatch, vespa_raw, status_code=200)
 
     engine = VespaSearchEngine("https://fakehost/base", schema="doc")
     template = 'select * from doc where title contains #$query##'
-    # keyword with quotes, backslash and newline: should be **quoted and escaped**
+    # keyword with quotes, backslash and newline
+    ## > should be quoted and escaped
     kw = 'He said "hi" \\ \n new'
 
     _ = engine.fetch_for_evaluation(
@@ -187,8 +194,12 @@ def test_fetch_for_evaluation_EXPECTS_properly_quotes_and_escapes_keyword(monkey
 # -------------------------
 # Skips hits without ID
 # -------------------------
-
 def test_fetch_for_query_generation_EXPECTS_skip_hits_without_id(monkeypatch):
+    """Hits missing an ``id`` must be discarded during query generation.
+
+    Args:
+        monkeypatch: PyTest fixture for patching HTTP calls.
+    """
     _monkeypatch_schema_ok(monkeypatch)
 
     vespa_raw = {"root": {"children": [{"fields": {"title": "No ID here"}}]}}
@@ -202,8 +213,13 @@ def test_fetch_for_query_generation_EXPECTS_skip_hits_without_id(monkeypatch):
 # ----------------------
 # Schema warnings
 # ----------------------
-
 def test_fetch_for_query_generation_EXPECTS_warn_on_unknown_schema_fields(monkeypatch, caplog):
+    """Expect a warning when filters reference fields absent in the Vespa schema.
+
+    Args:
+        monkeypatch: PyTest fixture.
+        caplog: PyTest log-capture fixture.
+    """
     # Load a schema with only "title"
     _monkeypatch_schema_ok(monkeypatch, fields=("title",))
 
@@ -224,8 +240,12 @@ def test_fetch_for_query_generation_EXPECTS_warn_on_unknown_schema_fields(monkey
 # --------------------
 # API loading failure
 # --------------------
-
 def test_schema_loading_EXPECTS_continue_on_failure(monkeypatch):
+    """Engine should fall back gracefully if the schema endpoint is unreachable.
+
+    Args:
+        monkeypatch: PyTest fixture for patching HTTP calls.
+    """
     _monkeypatch_schema_fail(monkeypatch)
 
     vespa_raw = {"root": {"children": []}}
@@ -243,6 +263,11 @@ def test_schema_loading_EXPECTS_continue_on_failure(monkeypatch):
 # -----------------------
 
 def test_http_requests_EXPECTS_raise_on_negative_responses(monkeypatch):
+    """Search/evaluation requests must raise ``HTTPError`` on non-success HTTP status codes.
+
+    Args:
+        monkeypatch: PyTest fixture for patching HTTP calls.
+    """
     _monkeypatch_schema_ok(monkeypatch)
 
     for code in (400, 401, 402, 403, 500):
@@ -283,9 +308,12 @@ def test_http_requests_EXPECTS_raise_on_negative_responses(monkeypatch):
         },
     ],
 )
-def test_backwards_compatibility_EXPECTS_work_with_existing_mocks_and_config(monkeypatch, mock_doc):
-    """
-    Tests both generation and evaluation paths using MockResponseVespaSearch.
+def test_workflow_with_mocks_and_config_EXPECTS_work_with_existing(monkeypatch, mock_doc):
+    """Validate generation & evaluation flows against legacy mocks and YAML config.
+
+    Args:
+        monkeypatch: PyTest fixture.
+        mock_doc: Single mocked Vespa hit used by ``MockResponseVespaSearch``.
     """
     # POST /search with existing mock
     monkeypatch.setattr(