test(e2e): add A2 negative-input tests for optional-id list-or-detail tools (#1058)

* test(e2e): add A2 negative-input tests for optional-id list-or-detail tools

Closes the A2 (optional ID → list or detail) negative-input test gaps from
#914. Two existing soft tests are hardened with explicit error-code and
message-substring assertions; three new tests are added for tools that had
no negative-input coverage on the single-ID lookup branch.

- Hardened test_get_blueprint_not_found in blueprints/test_blueprints.py —
  added error.code == 'RESOURCE_NOT_FOUND' assertion alongside the existing
  suggestions check.
- Hardened test_get_nonexistent_label in config/test_label_crud.py —
  added error.code == 'ENTITY_NOT_FOUND' assertion plus message-substring
  check on top of the existing success check.
- New TestGetIntegrationNegativeInputs in integrations/test_list_integrations.py
  with test_get_integration_nonexistent_entry_id. The existing tests in
  this file exercise list/query/domain-filter modes (A4-style empty results),
  not the entry_id single-entry lookup branch, which raises RESOURCE_NOT_FOUND
  via _get_single_entry's 404 catch.
- New TestDeviceGetNegativeInputs in registry/test_device_registry.py with
  test_get_device_nonexistent_device_id. Single-device lookup raises
  ENTITY_NOT_FOUND when the device_id is absent from the registry list.
- New TestUpdatesGetNegativeInputs in updates/test_updates.py with
  test_get_updates_nonexistent_entity_id. _get_update_details fetches the
  entity state via REST; a 404 response (HomeAssistantAPIError) is mapped to
  ENTITY_NOT_FOUND in the except-Exception branch. Live-probed against a
  real HA instance: GET /api/states/update.<nonexistent> returns HTTP 404
  with body {"message": "Entity not found."}.

ha_get_zone is intentionally not included — its A2 negative path is
already hard-asserted in zones/test_lifecycle.py. ha_config_get_category,
ha_get_todo, ha_get_entity_exposure and ha_config_get_dashboard were
deliberately scoped out (already-hard delete-side coverage in different
file, validation-pathway distinct from A2-classic, legitimate
default-exposure return shape, and a separate maintainer-mandated PR for
dashboard_id dual-accept respectively).

References #914.

* test(e2e): address Gemini review on A2 tests — structured error access

Addresses 5 medium-priority Gemini Code Assist findings on PR #1058:

- blueprints: drop redundant 'not found' substring assertion (already
  validated by call_tool_failure(expected_error=...)); switch to direct
  result['error'] access instead of .get() since the helper guarantees
  the key.
- label_crud, list_integrations, device_registry, updates: replace
  str(data.get('error','')).lower() with data['error']['message'].lower()
  for structured field access. Repo precedent: automation/test_lifecycle.py
  uses the same pattern.

No behavioral change — same assertions, more robust access path.

* test(e2e): address Gemini follow-up — assert structured suggestion presence

Addresses 4 medium-priority Gemini Code Assist findings on PR #1058
re-review:

- label_crud, list_integrations, device_registry: add 'suggestion' or
  'suggestions' presence assertion to verify the styleguide.md progressive
  disclosure principle (error responses guide next steps).
- updates: switch from safe_call_tool to MCPAssertions.call_tool_failure
  for consistency with the file's existing test style; add the same
  suggestion presence assertion.

Note on the assertion shape: create_error_response (errors.py:243-248)
sets the singular 'suggestion' key for any non-empty suggestions list and
the plural 'suggestions' key only when len > 1. The four targeted tools
each provide exactly one suggestion in their not-found path, so a strict
'suggestions' (plural) assertion would fail; the disjunction matches both
forms and is robust against future single->multi migrations.

* test(e2e): align blueprint suggestion assertion with disjunction pattern

Addresses Gemini follow-up finding on test_blueprints.py:188.

The plural-only 'suggestions' check is fragile — create_error_response
(errors.py:243-248) only sets the plural key when len > 1. ha_get_blueprint
currently provides two suggestions in its not-found path (blueprints.py:147)
so the plural assertion passes today, but the test would silently break if
a future change reduces the count to one.

Switch to the same 'suggestion' or 'suggestions' disjunction pattern used
in the other four negative-input tests for consistency and robustness.

* test(e2e): align docstring with current assertion shape

Drift fix: docstring previously claimed 'message-substring assertions'
which was removed earlier in this PR (redundant to call_tool_failure's
expected_error parameter). Update wording to reflect the actual
hardening — error-code assertion plus structured suggestion-presence
disjunction (suggestion or suggestions).

* test(e2e): simplify suggestion assertions to singular key

Addresses 4 medium-priority Gemini findings — the 'suggestion' or
'suggestions' disjunction is redundant. create_error_response
(errors.py:243-248) sets the singular 'suggestion' key unconditionally
when any suggestions are provided; the plural 'suggestions' key is
only set additionally when len > 1. Checking the singular key is both
sufficient and aligned with the helper's contract.

Applied uniformly across all 5 tests for consistency.

Author: Patch76

tests/src/e2e/workflows/blueprints/test_blueprints.py

@@ -160,22 +160,32 @@ async def test_get_blueprint_details(self, mcp_client):
 
     async def test_get_blueprint_not_found(self, mcp_client):
         """
-        Test: Get blueprint that doesn't exist
+        Test: ha_get_blueprint with a nonexistent path returns a structured
+        error with code RESOURCE_NOT_FOUND, not success=True.
 
-        Validates proper error handling when blueprint path doesn't exist.
+        Source path: tools_blueprints.py — when the requested path is absent
+        from the blueprints registry, raise_tool_error is invoked with
+        ErrorCode.RESOURCE_NOT_FOUND and the message "Blueprint not found: ...".
+
+        Hardened from a single suggestions-presence check to explicit
+        error-code and structured suggestion-presence assertions.
         """
         logger.info("Testing ha_get_blueprint with non-existent path...")
 
         async with MCPAssertions(mcp_client) as mcp:
             # Try to get a non-existent blueprint
             result = await mcp.call_tool_failure(
                 "ha_get_blueprint",
-                {"path": "nonexistent/blueprint_xyz.yaml", "domain": "automation"},
+                {"path": "nonexistent/blueprint_a2_e2e_xyz_404.yaml", "domain": "automation"},
                 expected_error="not found",
             )
 
-            # Verify error response includes suggestions (nested under "error")
-            assert "suggestions" in result.get("error", {}), "Error response should include suggestions"
+            assert result["error"]["code"] == "RESOURCE_NOT_FOUND", (
+                f"Expected error code RESOURCE_NOT_FOUND, got: {result['error']}"
+            )
+            assert "suggestion" in result["error"], (
+                "Error response should include a suggestion"
+            )
             logger.info("ha_get_blueprint properly handles non-existent blueprint")
 
     async def test_get_blueprint_invalid_domain(self, mcp_client):

tests/src/e2e/workflows/config/test_label_crud.py

@@ -202,18 +202,39 @@ async def test_create_label_with_icon(self, mcp_client, cleanup_tracker):
         )
 
     async def test_get_nonexistent_label(self, mcp_client):
-        """Test getting a non-existent label."""
+        """
+        Test: ha_config_get_label with a nonexistent label_id returns a
+        structured error with code ENTITY_NOT_FOUND, not success=True.
+
+        Source path: tools_labels.py — after listing labels via WebSocket,
+        the requested label_id is looked up in the result. When absent,
+        raise_tool_error is invoked with ErrorCode.ENTITY_NOT_FOUND and the
+        message "Label not found: ...".
+
+        Hardened from success-only check to explicit error-code and
+        message-substring assertions.
+        """
         logger.info("Testing get non-existent label")
 
         data = await safe_call_tool(
             mcp_client,
             "ha_config_get_label",
-            {"label_id": "nonexistent_label_xyz_12345"},
+            {"label_id": "nonexistent_label_a2_e2e_xyz_404"},
         )
 
         assert data.get("success") is False, (
             f"Should fail for non-existent label: {data}"
         )
+        assert data["error"]["code"] == "ENTITY_NOT_FOUND", (
+            f"Expected error code ENTITY_NOT_FOUND, got: {data['error']}"
+        )
+        assert "suggestion" in data["error"], (
+            "Error response should include a suggestion"
+        )
+        error_msg = data["error"]["message"].lower()
+        assert "not found" in error_msg, (
+            f"Expected 'not found' in error message, got: {data['error']}"
+        )
         logger.info("Non-existent label properly returned error")
 
     async def test_delete_nonexistent_label(self, mcp_client):

tests/src/e2e/workflows/integrations/test_list_integrations.py

@@ -12,7 +12,7 @@
 
 import pytest
 
-from ...utilities.assertions import assert_mcp_success
+from ...utilities.assertions import assert_mcp_success, safe_call_tool
 
 logger = logging.getLogger(__name__)
 
@@ -421,3 +421,49 @@ async def test_integration_discovery(mcp_client):
     logger.info(
         f"Integration discovery test passed: found {data['total_count']} integrations"
     )
+
+
+@pytest.mark.integrations
+class TestGetIntegrationNegativeInputs:
+    """
+    A2 negative-input tests for ha_get_integration's single-entry lookup mode.
+
+    Covers the nonexistent-entry_id failure path (entry_id provided, no match
+    in the config-entry registry). The existing tests in this file exercise
+    the list/query/domain-filter modes, which return empty results rather
+    than errors — that is A4-style behavior. The entry_id branch goes through
+    a distinct error path and was previously untested.
+
+    Methodology: source-verified against tools_integrations.py. When
+    _get_single_entry encounters a 404 from the underlying REST/WebSocket
+    call, raise_tool_error is invoked with ErrorCode.RESOURCE_NOT_FOUND and
+    the message "Config entry not found: ...".
+    """
+
+    async def test_get_integration_nonexistent_entry_id(self, mcp_client):
+        """
+        Test: ha_get_integration(entry_id="<nonexistent>") returns a
+        structured error with code RESOURCE_NOT_FOUND, not success=True.
+
+        Source path: tools_integrations.py — _get_single_entry catches a
+        404/not-found exception and raises RESOURCE_NOT_FOUND.
+        """
+        data = await safe_call_tool(
+            mcp_client,
+            "ha_get_integration",
+            {"entry_id": "nonexistent_entry_a2_e2e_xyz_404"},
+        )
+
+        assert not data.get("success"), (
+            f"Expected failure for nonexistent entry_id, got success=True: {data}"
+        )
+        assert data["error"]["code"] == "RESOURCE_NOT_FOUND", (
+            f"Expected error code RESOURCE_NOT_FOUND, got: {data['error']}"
+        )
+        assert "suggestion" in data["error"], (
+            "Error response should include a suggestion"
+        )
+        error_msg = data["error"]["message"].lower()
+        assert "not found" in error_msg, (
+            f"Expected 'not found' in error message, got: {data['error']}"
+        )

tests/src/e2e/workflows/registry/test_device_registry.py

@@ -625,3 +625,49 @@ async def test_device_entity_independence(mcp_client):
     assert restore_data.get("success"), f"Failed to restore device name: {restore_data}"
 
     logger.info("Device/entity naming independence test completed")
+
+
+@pytest.mark.registry
+class TestDeviceGetNegativeInputs:
+    """
+    A2 negative-input tests for ha_get_device's single-device lookup mode.
+
+    Covers the nonexistent-device_id failure path. Existing tests in this
+    file exercise the list mode, area/manufacturer filters, and the
+    update/remove flows, but never call ha_get_device with a device_id
+    that is absent from the device registry.
+
+    Methodology: source-verified against tools_registry.py. When the
+    requested device_id is not present in the device registry list,
+    raise_tool_error is invoked with ErrorCode.ENTITY_NOT_FOUND and the
+    message "Device not found: ...".
+    """
+
+    async def test_get_device_nonexistent_device_id(self, mcp_client):
+        """
+        Test: ha_get_device(device_id="<nonexistent>") returns a structured
+        error with code ENTITY_NOT_FOUND, not success=True.
+
+        Source path: tools_registry.py — single-device lookup branch returns
+        ENTITY_NOT_FOUND when the device_id is absent from
+        config/device_registry/list.
+        """
+        data = await safe_call_tool(
+            mcp_client,
+            "ha_get_device",
+            {"device_id": "nonexistent_device_a2_e2e_xyz_404"},
+        )
+
+        assert not data.get("success"), (
+            f"Expected failure for nonexistent device_id, got success=True: {data}"
+        )
+        assert data["error"]["code"] == "ENTITY_NOT_FOUND", (
+            f"Expected error code ENTITY_NOT_FOUND, got: {data['error']}"
+        )
+        assert "suggestion" in data["error"], (
+            "Error response should include a suggestion"
+        )
+        error_msg = data["error"]["message"].lower()
+        assert "not found" in error_msg, (
+            f"Expected 'not found' in error message, got: {data['error']}"
+        )

tests/src/e2e/workflows/updates/test_updates.py

@@ -534,3 +534,45 @@ async def test_update_tools_discovery(mcp_client):
     )
 
     logger.info("Update tools discovery test passed")
+
+
+@pytest.mark.updates
+class TestUpdatesGetNegativeInputs:
+    """
+    A2 negative-input tests for ha_get_updates' single-entity detail mode.
+
+    Covers the nonexistent-entity_id failure path. Existing tests in this
+    file exercise listing, release-notes inclusion, and edge cases on real
+    update entities, but do not call ha_get_updates with an entity_id that
+    has no matching update.
+
+    Methodology: source-verified against tools_updates.py. _get_update_details
+    fetches the entity state via REST; a 404 from /api/states/<entity_id>
+    raises HomeAssistantAPIError("API error: 404 - Entity not found.").
+    The except-Exception branch in ha_get_updates matches "404" / "not found"
+    in the error message and raises ErrorCode.ENTITY_NOT_FOUND. Live-probed
+    against a real HA instance: GET /api/states/update.<nonexistent> returns
+    HTTP 404 with body {"message": "Entity not found."}.
+    """
+
+    async def test_get_updates_nonexistent_entity_id(self, mcp_client):
+        """
+        Test: ha_get_updates(entity_id="update.<nonexistent>") returns a
+        structured error with code ENTITY_NOT_FOUND, not success=True.
+
+        Source path: REST 404 → HomeAssistantAPIError → except-Exception
+        in ha_get_updates → ENTITY_NOT_FOUND.
+        """
+        async with MCPAssertions(mcp_client) as mcp:
+            data = await mcp.call_tool_failure(
+                "ha_get_updates",
+                {"entity_id": "update.nonexistent_a2_e2e_xyz_404"},
+                expected_error="not found",
+            )
+
+            assert data["error"]["code"] == "ENTITY_NOT_FOUND", (
+                f"Expected error code ENTITY_NOT_FOUND, got: {data['error']}"
+            )
+            assert "suggestion" in data["error"], (
+                "Error response should include a suggestion"
+            )