test: add given-when-then comments to template coverage

Author: lan17

models/tests/test_control_templates.py

@@ -44,10 +44,12 @@ def _nested_template_value(depth: int) -> object:
 
 
 def test_control_definition_requires_template_fields_together() -> None:
+    # Given: a rendered control that only includes template metadata without template values
     with pytest.raises(
         ValidationError,
         match="template and template_values must both be present or both absent",
     ):
+        # When: validating the control definition model
         ControlDefinition.model_validate(
             {
                 "execution": "server",
@@ -63,13 +65,16 @@ def test_control_definition_requires_template_fields_together() -> None:
                 "template": VALID_TEMPLATE,
             }
         )
+    # Then: the model rejects the partial template-backed control shape
 
 
 def test_control_definition_rejects_template_values_without_template() -> None:
+    # Given: a rendered control that only includes template values without template metadata
     with pytest.raises(
         ValidationError,
         match="template and template_values must both be present or both absent",
     ):
+        # When: validating the control definition model
         ControlDefinition.model_validate(
             {
                 "execution": "server",
@@ -85,13 +90,16 @@ def test_control_definition_rejects_template_values_without_template() -> None:
                 "template_values": {"pattern": "hello"},
             }
         )
+    # Then: the model rejects the partial template-backed control shape
 
 
 def test_template_definition_rejects_invalid_parameter_name() -> None:
+    # Given: a template definition with an invalid parameter name
     with pytest.raises(
         ValidationError,
         match=r"Parameter names must match \[a-zA-Z_\]\[a-zA-Z0-9_\]\*",
     ):
+        # When: validating the template definition model
         TemplateDefinition.model_validate(
             {
                 "parameters": {
@@ -103,35 +111,43 @@ def test_template_definition_rejects_invalid_parameter_name() -> None:
                 "definition_template": {},
             }
         )
+    # Then: the invalid parameter name is rejected
 
 
 def test_template_definition_rejects_excessive_nesting() -> None:
+    # Given: a template definition whose structure exceeds the nesting limit
     with pytest.raises(
         ValidationError,
         match="definition_template nesting depth exceeds maximum",
     ):
+        # When: validating the template definition model
         TemplateDefinition.model_validate(
             {
                 "parameters": {},
                 "definition_template": _nested_template_value(12),
             }
         )
+    # Then: the model rejects the deeply nested template
 
 
 def test_template_definition_rejects_excessive_size() -> None:
+    # Given: a template definition whose structure exceeds the size limit
     with pytest.raises(
         ValidationError,
         match="definition_template size exceeds maximum",
     ):
+        # When: validating the template definition model
         TemplateDefinition.model_validate(
             {
                 "parameters": {},
                 "definition_template": list(range(1001)),
             }
         )
+    # Then: the model rejects the oversized template
 
 
 def test_create_control_request_parses_template_payload_as_template_input() -> None:
+    # Given: a create request payload containing template-backed control input
     request = CreateControlRequest.model_validate(
         {
             "name": "template-control",
@@ -142,17 +158,21 @@ def test_create_control_request_parses_template_payload_as_template_input() -> N
         }
     )
 
+    # When: the request model parses the payload
+    # Then: the control input is discriminated as template-backed input
     assert isinstance(request.data, TemplateControlInput)
 
 
 def test_create_control_request_rejects_mixed_raw_and_template_payload() -> None:
+    # Given: a create request payload that mixes template and rendered control fields
     with pytest.raises(
         ValidationError,
         match=(
             "Template-backed control input cannot mix template fields with rendered "
             "control fields"
         ),
     ):
+        # When: the request model parses the mixed payload
         CreateControlRequest.model_validate(
             {
                 "name": "template-control",
@@ -163,9 +183,11 @@ def test_create_control_request_rejects_mixed_raw_and_template_payload() -> None
                 },
             }
         )
+    # Then: the mixed payload is rejected clearly
 
 
 def test_control_definition_can_round_trip_to_template_control_input() -> None:
+    # Given: a stored template-backed control definition
     control = ControlDefinition.model_validate(
         {
             "execution": "server",
@@ -183,15 +205,18 @@ def test_control_definition_can_round_trip_to_template_control_input() -> None:
         }
     )
 
+    # When: converting the stored control back into template input
     template_input = control.to_template_control_input()
 
+    # Then: the template metadata and values round-trip unchanged
     assert template_input.template.parameters["pattern"].label == "Pattern"
     assert template_input.template.parameters["pattern"].type == "regex_re2"
     assert template_input.template.definition_template == VALID_TEMPLATE["definition_template"]
     assert template_input.template_values == {"pattern": "hello"}
 
 
 def test_control_definition_to_template_control_input_rejects_raw_control() -> None:
+    # Given: a raw control definition without template metadata
     control = ControlDefinition.model_validate(
         {
             "execution": "server",
@@ -207,11 +232,14 @@ def test_control_definition_to_template_control_input_rejects_raw_control() -> N
         }
     )
 
+    # When: converting the raw control into template input
     with pytest.raises(ValueError, match="not template-backed"):
         control.to_template_control_input()
+    # Then: the helper rejects the non-template-backed control
 
 
 def test_control_definition_runtime_ignores_template_metadata() -> None:
+    # Given: a stored template-backed control definition with template metadata
     runtime_control = ControlDefinitionRuntime.model_validate(
         {
             "execution": "server",
@@ -229,5 +257,7 @@ def test_control_definition_runtime_ignores_template_metadata() -> None:
         }
     )
 
+    # When: validating it through the runtime-only model
+    # Then: runtime parsing succeeds while ignoring template metadata
     assert runtime_control.execution == "server"
     assert runtime_control.action.decision == "deny"

sdks/python/tests/test_controls_api.py

@@ -13,13 +13,16 @@
 
 @pytest.mark.asyncio
 async def test_list_controls_passes_template_backed_filter() -> None:
+    # Given: an SDK client stub and a template-backed list filter
     response = Mock()
     response.raise_for_status = Mock()
     response.json = Mock(return_value={"controls": [], "pagination": {}})
     client = SimpleNamespace(http_client=SimpleNamespace(get=AsyncMock(return_value=response)))
 
+    # When: listing controls through the SDK wrapper
     await agent_control.controls.list_controls(client, template_backed=True)
 
+    # Then: the filter is forwarded to the API request
     client.http_client.get.assert_awaited_once_with(
         "/api/v1/controls",
         params={"limit": 20, "template_backed": True},
@@ -28,6 +31,7 @@ async def test_list_controls_passes_template_backed_filter() -> None:
 
 @pytest.mark.asyncio
 async def test_create_control_accepts_template_control_input() -> None:
+    # Given: an SDK client stub and template-backed control input
     response = Mock()
     response.raise_for_status = Mock()
     response.json = Mock(return_value={"control_id": 123})
@@ -58,20 +62,24 @@ async def test_create_control_accepts_template_control_input() -> None:
         }
     )
 
+    # When: creating a control through the SDK wrapper
     await agent_control.controls.create_control(client, "templated", template_input)
 
+    # Then: the template values are serialized into the request body
     client.http_client.put.assert_awaited_once()
     _, kwargs = client.http_client.put.await_args
     assert kwargs["json"]["data"]["template_values"]["pattern"] == "hello"
 
 
 @pytest.mark.asyncio
 async def test_render_control_template_calls_preview_endpoint() -> None:
+    # Given: an SDK client stub and template preview input
     response = Mock()
     response.raise_for_status = Mock()
     response.json = Mock(return_value={"control": {"execution": "server"}})
     client = SimpleNamespace(http_client=SimpleNamespace(post=AsyncMock(return_value=response)))
 
+    # When: rendering a control template through the SDK wrapper
     await agent_control.controls.render_control_template(
         client,
         template={
@@ -89,6 +97,7 @@ async def test_render_control_template_calls_preview_endpoint() -> None:
         template_values={},
     )
 
+    # Then: the SDK calls the preview endpoint with the expected payload
     client.http_client.post.assert_awaited_once_with(
         "/api/v1/control-templates/render",
         json={
@@ -111,6 +120,7 @@ async def test_render_control_template_calls_preview_endpoint() -> None:
 
 @pytest.mark.asyncio
 async def test_validate_control_data_accepts_template_control_input() -> None:
+    # Given: an SDK client stub and template-backed control input
     response = Mock()
     response.raise_for_status = Mock()
     response.json = Mock(return_value={"success": True})
@@ -141,8 +151,10 @@ async def test_validate_control_data_accepts_template_control_input() -> None:
         }
     )
 
+    # When: validating template-backed control input through the SDK wrapper
     await agent_control.controls.validate_control_data(client, template_input)
 
+    # Then: the template-backed payload is posted to the validate endpoint
     client.http_client.post.assert_awaited_once()
     _, kwargs = client.http_client.post.await_args
     assert kwargs["json"]["data"]["template_values"]["pattern"] == "hello"
@@ -156,6 +168,7 @@ async def test_validate_control_data_accepts_template_control_input() -> None:
 
 @pytest.mark.asyncio
 async def test_set_control_data_accepts_template_control_input() -> None:
+    # Given: an SDK client stub and template-backed control input
     response = Mock()
     response.raise_for_status = Mock()
     response.json = Mock(return_value={"success": True})
@@ -186,14 +199,17 @@ async def test_set_control_data_accepts_template_control_input() -> None:
         }
     )
 
+    # When: updating control data through the SDK wrapper
     await agent_control.controls.set_control_data(client, 123, template_input)
 
+    # Then: the template values are serialized into the request body
     client.http_client.put.assert_awaited_once()
     _, kwargs = client.http_client.put.await_args
     assert kwargs["json"]["data"]["template_values"]["pattern"] == "hello"
 
 
 def test_to_template_control_input_reshapes_stored_control_data() -> None:
+    # Given: stored template-backed control data returned by the API
     template_input = agent_control.controls.to_template_control_input(
         {
             "execution": "server",
@@ -230,11 +246,15 @@ def test_to_template_control_input_reshapes_stored_control_data() -> None:
         }
     )
 
+    # When: reshaping the stored data into template input
+    # Then: the result is template-backed input with the original values
     assert isinstance(template_input, TemplateControlInput)
     assert template_input.template_values == {"pattern": "hello"}
 
 
 def test_to_template_control_input_rejects_raw_control_data() -> None:
+    # Given: raw control data without template metadata
+    # When: reshaping it into template-backed control input
     with pytest.raises(ValueError, match="not template-backed"):
         agent_control.controls.to_template_control_input(
             {
@@ -250,3 +270,4 @@ def test_to_template_control_input_rejects_raw_control_data() -> None:
                 "action": {"decision": "deny"},
             }
         )
+    # Then: the helper rejects the raw control data

sdks/python/tests/test_local_evaluation.py

@@ -305,19 +305,22 @@ async def test_server_only_template_backed_controls_still_call_server(
         llm_payload,
     ):
         """Template metadata must not break routing for server-executed cached controls."""
+        # Given: a cached server-executed control that includes template metadata
         controls = [
             add_template_metadata(
                 make_control_dict(1, "templated_server_ctrl", execution="server"),
             ),
         ]
 
+        # Given: a client stub that returns a safe server evaluation response
         client = MagicMock(spec=AgentControlClient)
         mock_response = MagicMock()
         mock_response.json.return_value = {"is_safe": True, "confidence": 1.0}
         mock_response.raise_for_status = MagicMock()
         client.http_client = AsyncMock()
         client.http_client.post = AsyncMock(return_value=mock_response)
 
+        # When: evaluating with local controls enabled
         result = await check_evaluation_with_local(
             client=client,
             agent_name=agent_name,
@@ -326,6 +329,7 @@ async def test_server_only_template_backed_controls_still_call_server(
             controls=controls,
         )
 
+        # Then: the SDK still routes evaluation to the server
         client.http_client.post.assert_called_once()
         assert result.is_safe is True
 
@@ -512,15 +516,18 @@ async def test_template_backed_local_control_executes_locally(
         llm_payload,
     ):
         """Template metadata should be ignored by runtime parsing in local evaluation."""
+        # Given: a cached SDK-executed control that includes template metadata
         controls = [
             add_template_metadata(
                 make_control_dict(1, "templated_local_ctrl", execution="sdk", pattern=r"test"),
             ),
         ]
+        # Given: a client stub that would allow server calls if routing were wrong
         client = MagicMock(spec=AgentControlClient)
         client.http_client = AsyncMock()
         client.http_client.post = AsyncMock()
 
+        # When: evaluating with local controls enabled
         result = await check_evaluation_with_local(
             client=client,
             agent_name=agent_name,
@@ -529,6 +536,7 @@ async def test_template_backed_local_control_executes_locally(
             controls=controls,
         )
 
+        # Then: local evaluation succeeds and no server call is made
         client.http_client.post.assert_not_called()
         assert result.is_safe is False
         assert result.matches is not None