feat: Bronze quality scale — runtime_data, has_entity_name, data_description, removal docs, config flow tests

cloudbr34k84 · claude · cloudbr34k84 · commit 08752f1f77b5 · 2026-03-15T19:47:17.000+10:00
Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/README.md b/README.md
@@ -99,6 +99,17 @@ custom_components/
 
 No changes to `configuration.yaml` are required.
 
+## Removal
+
+To remove the PocketSmith integration:
+
+1. Go to **Settings → Integrations** in Home Assistant.
+2. Find **PocketSmith** and click on it.
+3. Click the three-dot menu (⋮) and select **Delete**.
+4. Confirm the removal.
+
+All sensors and entities created by the integration will be removed automatically.
+
 ## Automation Examples
 
 ### Notify on Low Balance:
diff --git a/custom_components/ha_pocketsmith/__init__.py b/custom_components/ha_pocketsmith/__init__.py
@@ -16,8 +16,10 @@
 
 CONFIG_SCHEMA = cv.config_entry_only_config_schema(DOMAIN)
 
+type PocketSmithConfigEntry = ConfigEntry[PocketSmithCoordinator]
 
-async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
+
+async def async_setup_entry(hass: HomeAssistant, entry: PocketSmithConfigEntry) -> bool:
     """Set up PocketSmith from a config entry."""
     coordinator = PocketSmithCoordinator(
         hass,
@@ -26,17 +28,13 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
         entry=entry,
     )
     await coordinator.async_config_entry_first_refresh()
-    hass.data.setdefault(DOMAIN, {})
-    hass.data[DOMAIN][entry.entry_id] = coordinator
+    entry.runtime_data = coordinator
 
     await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)
 
     return True
 
 
-async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
+async def async_unload_entry(hass: HomeAssistant, entry: PocketSmithConfigEntry) -> bool:
     """Handle unloading of an entry."""
-    unload_ok = await hass.config_entries.async_unload_platforms(entry, PLATFORMS)
-    if unload_ok:
-        hass.data[DOMAIN].pop(entry.entry_id)
-    return unload_ok
+    return await hass.config_entries.async_unload_platforms(entry, PLATFORMS)
diff --git a/custom_components/ha_pocketsmith/binary_sensor.py b/custom_components/ha_pocketsmith/binary_sensor.py
@@ -22,7 +22,7 @@ async def async_setup_entry(
     async_add_entities: AddEntitiesCallback,
 ) -> None:
     """Set up PocketSmith binary sensors from a config entry."""
-    coordinator: PocketSmithCoordinator = hass.data[DOMAIN][entry.entry_id]
+    coordinator: PocketSmithCoordinator = entry.runtime_data
 
     async_add_entities([
         PocketSmithOverBudgetBinarySensor(coordinator),
@@ -34,6 +34,8 @@ async def async_setup_entry(
 class PocketSmithOverBudgetBinarySensor(CoordinatorEntity, BinarySensorEntity):
     """Binary sensor that is on when any non-transfer category is over budget."""
 
+    _attr_has_entity_name = True
+
     def __init__(self, coordinator: PocketSmithCoordinator) -> None:
         """Initialise the sensor."""
         super().__init__(coordinator)
@@ -99,6 +101,8 @@ def extra_state_attributes(self) -> dict:
 class PocketSmithForecastNeedsRecalculateBinarySensor(CoordinatorEntity, BinarySensorEntity):
     """Binary sensor that is on when the forecast is stale or missing."""
 
+    _attr_has_entity_name = True
+
     def __init__(self, coordinator: PocketSmithCoordinator) -> None:
         """Initialise the sensor."""
         super().__init__(coordinator)
@@ -155,6 +159,8 @@ def icon(self) -> str:
 class PocketSmithHasUncategorisedBinarySensor(CoordinatorEntity, BinarySensorEntity):
     """Binary sensor that is on when there are uncategorised transactions."""
 
+    _attr_has_entity_name = True
+
     def __init__(self, coordinator: PocketSmithCoordinator) -> None:
         """Initialise the sensor."""
         super().__init__(coordinator)
diff --git a/custom_components/ha_pocketsmith/diagnostics.py b/custom_components/ha_pocketsmith/diagnostics.py
@@ -15,7 +15,7 @@ async def async_get_config_entry_diagnostics(
     hass: HomeAssistant, entry: ConfigEntry
 ) -> dict[str, Any]:
     """Return diagnostics for a PocketSmith config entry."""
-    coordinator = hass.data[DOMAIN][entry.entry_id]
+    coordinator = entry.runtime_data
     data = coordinator.data
 
     return {
diff --git a/custom_components/ha_pocketsmith/sensor.py b/custom_components/ha_pocketsmith/sensor.py
@@ -50,7 +50,7 @@ async def async_setup_entry(
     async_add_entities: AddEntitiesCallback,
 ) -> None:
     """Set up PocketSmith sensors from a config entry."""
-    coordinator: PocketSmithCoordinator = hass.data[DOMAIN][entry.entry_id]
+    coordinator: PocketSmithCoordinator = entry.runtime_data
 
     sensors = [
         PocketSmithSensor(coordinator, account)
@@ -70,6 +70,8 @@ async def async_setup_entry(
 class PocketSmithSensor(CoordinatorEntity, SensorEntity):
     """Representation of a PocketSmith account balance sensor."""
 
+    _attr_has_entity_name = True
+
     def __init__(self, coordinator: PocketSmithCoordinator, account: dict) -> None:
         """Initialise the sensor."""
         super().__init__(coordinator)
@@ -130,6 +132,8 @@ def extra_state_attributes(self) -> dict:
 class PocketSmithUncategorisedTransactions(CoordinatorEntity, SensorEntity):
     """Sensor reporting the count of uncategorised transactions."""
 
+    _attr_has_entity_name = True
+
     def __init__(self, coordinator: PocketSmithCoordinator) -> None:
         """Initialise the sensor."""
         super().__init__(coordinator)
@@ -168,6 +172,8 @@ def icon(self) -> str:
 class PocketSmithCategoriesSensor(CoordinatorEntity, SensorEntity):
     """Sensor reporting the total number of PocketSmith categories."""
 
+    _attr_has_entity_name = True
+
     def __init__(self, coordinator: PocketSmithCoordinator) -> None:
         """Initialise the sensor."""
         super().__init__(coordinator)
@@ -210,6 +216,8 @@ def extra_state_attributes(self) -> dict:
 class PocketSmithCategorySensor(CoordinatorEntity, SensorEntity):
     """Sensor representing a single enriched PocketSmith category."""
 
+    _attr_has_entity_name = True
+
     def __init__(self, coordinator: PocketSmithCoordinator, enriched_category: dict) -> None:
         """Initialise the sensor."""
         super().__init__(coordinator)
@@ -280,6 +288,8 @@ def extra_state_attributes(self) -> dict:
 class PocketSmithNetWorthSensor(CoordinatorEntity, SensorEntity):
     """Sensor reporting the total net worth across all accounts."""
 
+    _attr_has_entity_name = True
+
     def __init__(self, coordinator: PocketSmithCoordinator) -> None:
         """Initialise the sensor."""
         super().__init__(coordinator)
@@ -326,6 +336,8 @@ def icon(self) -> str:
 class PocketSmithUserSensor(CoordinatorEntity, SensorEntity):
     """Sensor reporting PocketSmith user profile information."""
 
+    _attr_has_entity_name = True
+
     def __init__(self, coordinator: PocketSmithCoordinator) -> None:
         """Initialise the sensor."""
         super().__init__(coordinator)
diff --git a/custom_components/ha_pocketsmith/strings.json b/custom_components/ha_pocketsmith/strings.json
@@ -6,6 +6,9 @@
         "description": "Enter your PocketSmith developer key. You can find it under PocketSmith \u2192 Settings \u2192 API.",
         "data": {
           "developer_key": "Developer Key"
+        },
+        "data_description": {
+          "developer_key": "Your PocketSmith developer API key. Find it in PocketSmith under Settings → API → Developer Keys."
         }
       }
     },
diff --git a/custom_components/ha_pocketsmith/system_health.py b/custom_components/ha_pocketsmith/system_health.py
@@ -22,8 +22,8 @@ async def system_health_info(hass: HomeAssistant) -> dict[str, Any]:
 
     entry = entries[0]
     try:
-        coordinator = hass.data[DOMAIN][entry.entry_id]
-    except KeyError:
+        coordinator = entry.runtime_data
+    except AttributeError:
         return {"api_reachable": False}
 
     return {
diff --git a/custom_components/ha_pocketsmith/translations/en.json b/custom_components/ha_pocketsmith/translations/en.json
@@ -6,6 +6,9 @@
         "description": "Enter your PocketSmith developer key. You can find it under PocketSmith \u2192 Settings \u2192 API.",
         "data": {
           "developer_key": "Developer Key"
+        },
+        "data_description": {
+          "developer_key": "Your PocketSmith developer API key. Find it in PocketSmith under Settings → API → Developer Keys."
         }
       }
     },
diff --git a/tests/__init__.py b/tests/__init__.py
diff --git a/tests/components/__init__.py b/tests/components/__init__.py
diff --git a/tests/components/ha_pocketsmith/__init__.py b/tests/components/ha_pocketsmith/__init__.py
diff --git a/tests/components/ha_pocketsmith/conftest.py b/tests/components/ha_pocketsmith/conftest.py
@@ -0,0 +1,51 @@
+"""Fixtures for ha_pocketsmith config flow tests."""
+import pytest
+from unittest.mock import patch
+
+
+@pytest.fixture(autouse=True)
+def auto_enable_custom_integrations(enable_custom_integrations):
+    """Enable custom integrations defined in the test dir."""
+    yield
+
+
+@pytest.fixture
+def mock_validate_ok():
+    """Return a fixture that mocks a successful developer key validation."""
+    with patch(
+        "custom_components.ha_pocketsmith.config_flow._validate_developer_key",
+        return_value=None,
+    ) as mock:
+        yield mock
+
+
+@pytest.fixture
+def mock_validate_invalid_auth():
+    """Return a fixture that mocks an invalid-auth error."""
+    with patch(
+        "custom_components.ha_pocketsmith.config_flow._validate_developer_key",
+        side_effect=ValueError("invalid_auth"),
+    ) as mock:
+        yield mock
+
+
+@pytest.fixture
+def mock_validate_insufficient_permissions():
+    """Return a fixture that mocks an insufficient-permissions error."""
+    with patch(
+        "custom_components.ha_pocketsmith.config_flow._validate_developer_key",
+        side_effect=ValueError("insufficient_permissions"),
+    ) as mock:
+        yield mock
+
+
+@pytest.fixture
+def mock_validate_cannot_connect():
+    """Return a fixture that mocks a network/connectivity error."""
+    import aiohttp
+
+    with patch(
+        "custom_components.ha_pocketsmith.config_flow._validate_developer_key",
+        side_effect=aiohttp.ClientError(),
+    ) as mock:
+        yield mock
diff --git a/tests/components/ha_pocketsmith/test_config_flow.py b/tests/components/ha_pocketsmith/test_config_flow.py
@@ -0,0 +1,121 @@
+"""Tests for the PocketSmith config flow."""
+import aiohttp
+import pytest
+from unittest.mock import patch
+
+from homeassistant import config_entries
+from homeassistant.data_entry_flow import FlowResultType
+
+from custom_components.ha_pocketsmith.const import DOMAIN
+
+
+async def test_form_is_shown(hass):
+    """Test that the config form is presented on initial load."""
+    result = await hass.config_entries.flow.async_init(
+        DOMAIN, context={"source": config_entries.SOURCE_USER}
+    )
+
+    assert result["type"] == FlowResultType.FORM
+    assert result["step_id"] == "user"
+    assert result["errors"] == {}
+
+
+async def test_successful_setup(hass):
+    """Test a valid developer key creates a config entry."""
+    result = await hass.config_entries.flow.async_init(
+        DOMAIN, context={"source": config_entries.SOURCE_USER}
+    )
+
+    with patch(
+        "custom_components.ha_pocketsmith.config_flow._validate_developer_key",
+        return_value=None,
+    ):
+        result = await hass.config_entries.flow.async_configure(
+            result["flow_id"],
+            {"developer_key": "valid_test_key"},
+        )
+
+    assert result["type"] == FlowResultType.CREATE_ENTRY
+    assert result["title"] == "PocketSmith"
+    assert result["data"] == {"developer_key": "valid_test_key"}
+
+
+async def test_invalid_auth(hass):
+    """Test that an invalid developer key shows the invalid_auth error."""
+    result = await hass.config_entries.flow.async_init(
+        DOMAIN, context={"source": config_entries.SOURCE_USER}
+    )
+
+    with patch(
+        "custom_components.ha_pocketsmith.config_flow._validate_developer_key",
+        side_effect=ValueError("invalid_auth"),
+    ):
+        result = await hass.config_entries.flow.async_configure(
+            result["flow_id"],
+            {"developer_key": "bad_key"},
+        )
+
+    assert result["type"] == FlowResultType.FORM
+    assert result["errors"] == {"base": "invalid_auth"}
+
+
+async def test_insufficient_permissions(hass):
+    """Test that a key without permissions shows the insufficient_permissions error."""
+    result = await hass.config_entries.flow.async_init(
+        DOMAIN, context={"source": config_entries.SOURCE_USER}
+    )
+
+    with patch(
+        "custom_components.ha_pocketsmith.config_flow._validate_developer_key",
+        side_effect=ValueError("insufficient_permissions"),
+    ):
+        result = await hass.config_entries.flow.async_configure(
+            result["flow_id"],
+            {"developer_key": "restricted_key"},
+        )
+
+    assert result["type"] == FlowResultType.FORM
+    assert result["errors"] == {"base": "insufficient_permissions"}
+
+
+async def test_cannot_connect(hass):
+    """Test that a network error shows the cannot_connect error."""
+    result = await hass.config_entries.flow.async_init(
+        DOMAIN, context={"source": config_entries.SOURCE_USER}
+    )
+
+    with patch(
+        "custom_components.ha_pocketsmith.config_flow._validate_developer_key",
+        side_effect=aiohttp.ClientError(),
+    ):
+        result = await hass.config_entries.flow.async_configure(
+            result["flow_id"],
+            {"developer_key": "some_key"},
+        )
+
+    assert result["type"] == FlowResultType.FORM
+    assert result["errors"] == {"base": "cannot_connect"}
+
+
+async def test_duplicate_entry(hass):
+    """Test that a second setup attempt aborts with already_configured."""
+    # First setup succeeds
+    result = await hass.config_entries.flow.async_init(
+        DOMAIN, context={"source": config_entries.SOURCE_USER}
+    )
+    with patch(
+        "custom_components.ha_pocketsmith.config_flow._validate_developer_key",
+        return_value=None,
+    ):
+        result = await hass.config_entries.flow.async_configure(
+            result["flow_id"],
+            {"developer_key": "valid_test_key"},
+        )
+    assert result["type"] == FlowResultType.CREATE_ENTRY
+
+    # Second attempt with the same unique_id should abort
+    result2 = await hass.config_entries.flow.async_init(
+        DOMAIN, context={"source": config_entries.SOURCE_USER}
+    )
+    assert result2["type"] == FlowResultType.ABORT
+    assert result2["reason"] == "already_configured"

Original file line number	Diff line number	Diff line change
`@@ -6,6 +6,9 @@`
`6`	`6`	`"description": "Enter your PocketSmith developer key. You can find it under PocketSmith \u2192 Settings \u2192 API.",`
`7`	`7`	`"data": {`
`8`	`8`	`"developer_key": "Developer Key"`
	`9`	`+ },`
	`10`	`+ "data_description": {`
	`11`	`+ "developer_key": "Your PocketSmith developer API key. Find it in PocketSmith under Settings → API → Developer Keys."`
`9`	`12`	`}`
`10`	`13`	`}`
`11`	`14`	`},`