Add a global disable for downloaded cycles and clarify setup instructions

Issue #364: several reporters got the "downloaded cycles not set up"
Repair despite never meaning to use the feature -- one device appears
to auto-populate a slot from a SmartThings-provided example. The two
reporters who did complete setup successfully both hit the same root
cause for their earlier failures: the SmartThings app has two
similarly-named screens ("Cycle", which lists everything including
local courses, and "Download cycles", the one that actually matters
here), and nothing in our instructions said to use the second one
specifically.

Global disable (CONF_CLOUD_COURSES_ENABLED, entry.options, default
on):
- New coordinator.cloud_courses_enabled property, mirroring
  CONF_LEARN_MODES' shape -- off stops the Repair and stops offering
  already-named programs as cycles, without discarding anything
  already learned or named.
- Deliberately does NOT stop _observe_cloud_courses' passive recording:
  guided/manual setup depend on live observation to detect a newly
  selected program at all, and leaving it running means turning the
  option back on immediately surfaces anything set up in the meantime
  instead of asking the user to redo it. Documented on the const and
  on the property.
- New __init__.py options-update listener calls a new
  coordinator._on_cloud_courses_changed(), which both clears the
  canonical-view cache (memoized, so a stale view would otherwise keep
  answering with pre-toggle state -- caught by two failing tests
  before this) and refreshes the Repair. Nothing else needed this
  because every other option is read live on its own next use; cloud
  courses is the only one with standing Repair/cache state to refresh
  immediately rather than on the next unrelated change.
- Toggle exposed in Device settings as "Offer downloaded cycles",
  alongside prose explaining why some devices show the Repair
  unprompted.

Instructions, in every shipped locale (en/de/es/it/cs/nl/ko) --
otherwise a locale missing the new/changed strings would silently show
English or the old text, the same gap issue #376 already tests for:
- Every guided-setup screen, the manual edit form, and the Repair
  itself now say explicitly: open the SmartThings app (not the
  appliance), and tap "Download cycles" specifically -- a separate row
  from "Cycle", further down the screen -- not the general cycle
  picker. Also states plainly that the appliance doesn't need to be
  nearby or running the cycle, just powered on and connected.
  SmartThings' own screen names are kept in English in every locale
  (verified only in the English app via the reporter's screenshots;
  translating them without evidence of what Samsung's own localized
  app shows would be a guess this codebase's translations otherwise
  avoid).
- The Repair's description now also points at the new toggle for
  anyone who doesn't want the feature at all.
- The "cloud_courses" menu screen shows a note when the option is
  currently off, since guided/manual setup still work in that state
  but nothing named there will appear as a selectable cycle until it's
  turned back on.

Tests: coordinator-level tests cover the option defaulting on,
suppressing a new Repair, clearing an already-open one, hiding/
restoring the cycle-select entry as the option flips (which caught the
canonical-cache bug above), and that passive observation keeps running
regardless of the option. Options-flow tests cover the new field's
default and that it persists. Translation catalog tests
(test_every_language_mirrors_the_english_catalog et al.) cover every
locale's topology and placeholders for the changed/added strings.

Full suite (1583 tests), ruff, and `ty check custom_components tests`
(CI's exact invocation) all pass.
This commit is contained in:
Marc Billow committed 2026-08-16 05:04:44 +00:00
1 parent 93cd6ae6fe
commit d5dc6421ba
13 files changed
+307 -65

No files matched your search

+94 -2
View File
@@ -22,7 +22,11 @@ from homeassistant.helpers import issue_registry as ir
from pytest_homeassistant_custom_component.common import MockConfigEntry
from custom_components.localthings import cloudcourse
from custom_components.localthings.const import CONF_CLOUD_COURSES, DOMAIN
from custom_components.localthings.const import (
CONF_CLOUD_COURSES,
CONF_CLOUD_COURSES_ENABLED,
DOMAIN,
)
from custom_components.localthings.coordinator import LocalThingsCoordinator
from custom_components.localthings.registry.entities import SelectDesc
from custom_components.localthings.registry.subdevices import MAIN
@@ -55,10 +59,11 @@ async def _flush(hass: HomeAssistant) -> None:
await hass.async_block_till_done()
def _entry(hass: HomeAssistant, data=None) -> MockConfigEntry:
def _entry(hass: HomeAssistant, data=None, options=None) -> MockConfigEntry:
entry = MockConfigEntry(
domain=DOMAIN,
data={**ENTRY_DATA, **(data or {})},
options=options or {},
unique_id="localthings_CLOUD-COURSE-TEST",
)
entry.add_to_hass(hass)
@@ -240,6 +245,93 @@ async def test_a_malformed_entry_record_does_not_block_setup(hass: HomeAssistant
assert coordinator.cloud_courses.snapshot()["slots"]["55"]["blob"] == SPORTS
# ---------------------------------------------------------------------------
# cloud_courses_enabled toggle (issue #364) -- some devices report a
# downloaded program's payload before the owner has ever meant to use the
# feature, so the Repair and the entity offering need a way to be turned
# off entirely without discarding what was already learned.
# ---------------------------------------------------------------------------
def test_cloud_courses_enabled_defaults_to_true(hass: HomeAssistant):
coordinator = LocalThingsCoordinator(hass, _entry(hass))
assert coordinator.cloud_courses_enabled is True
async def test_disabling_suppresses_the_repair(hass: HomeAssistant):
entry = _entry(hass, options={CONF_CLOUD_COURSES_ENABLED: False})
coordinator = await _coordinator(hass, entry)
coordinator._refresh_cloud_course_issue()
await _flush(hass)
registry = ir.async_get(hass)
assert registry.async_get_issue(DOMAIN, f"cloud_courses_{entry.entry_id}") is None
async def test_disabling_clears_an_already_open_repair(hass: HomeAssistant):
"""Turning the option off has to reach a Repair that's already showing,
not just prevent a future one -- otherwise the toggle looks broken to
anyone who flips it after already seeing the nudge."""
entry = _entry(hass)
coordinator = await _coordinator(hass, entry)
coordinator._refresh_cloud_course_issue()
await _flush(hass)
registry = ir.async_get(hass)
issue_id = f"cloud_courses_{entry.entry_id}"
assert registry.async_get_issue(DOMAIN, issue_id) is not None
hass.config_entries.async_update_entry(entry, options={CONF_CLOUD_COURSES_ENABLED: False})
coordinator._refresh_cloud_course_issue()
await _flush(hass)
assert registry.async_get_issue(DOMAIN, issue_id) is None
async def test_disabling_hides_an_already_named_program_from_the_cycle_select(
hass: HomeAssistant,
):
"""`coordinator._on_cloud_courses_changed()` after the option write
stands in for __init__.py's options-update listener, which this
lightweight coordinator (no async_setup_entry) never registers --
see test_disabling_clears_an_already_open_repair for the same shape."""
entry = _entry(hass)
coordinator = await _coordinator(hass, entry)
coordinator.apply_cloud_courses({"55": "Sports"}, "87")
await _flush(hass)
assert "cloud:55" in _cycle_options(coordinator)
hass.config_entries.async_update_entry(entry, options={CONF_CLOUD_COURSES_ENABLED: False})
coordinator._on_cloud_courses_changed()
assert "cloud:55" not in _cycle_options(coordinator)
# Not discarded -- the store itself is untouched, only what
# entity_resources() hands the registry changes.
assert coordinator.cloud_courses.named() == {"55": "Sports"}
assert entry.data[CONF_CLOUD_COURSES]["slots"]["55"]["name"] == "Sports"
async def test_re_enabling_immediately_restores_the_offering(hass: HomeAssistant):
entry = _entry(hass, options={CONF_CLOUD_COURSES_ENABLED: False})
coordinator = await _coordinator(hass, entry)
coordinator.apply_cloud_courses({"55": "Sports"}, "87")
await _flush(hass)
assert "cloud:55" not in _cycle_options(coordinator)
hass.config_entries.async_update_entry(entry, options={CONF_CLOUD_COURSES_ENABLED: True})
coordinator._on_cloud_courses_changed()
assert "cloud:55" in _cycle_options(coordinator)
async def test_disabling_does_not_stop_passive_observation(hass: HomeAssistant):
"""Guided/manual setup depend on live observation to detect a newly
selected program at all -- see CONF_CLOUD_COURSES_ENABLED's own comment
for why the option leaves this running rather than gating it too."""
entry = _entry(hass, options={CONF_CLOUD_COURSES_ENABLED: False})
coordinator = await _coordinator(hass, entry)
assert coordinator.cloud_courses.snapshot()["slots"]["55"]["blob"] == SPORTS
assert entry.data[CONF_CLOUD_COURSES]["slots"]["55"]["blob"] == SPORTS
# ---------------------------------------------------------------------------
# Options flow
# ---------------------------------------------------------------------------