Add HEOS options flow for optional authentication (#134105)

* Add heos options flow

* Add options flow tests

* Test error condition during options sign out

* Use credentials when setting up

* Update warning instructions

* Simplify exception logic

* Cover unknown command error condition

* Add test for options

* Correct const import location

* Review feedback

* Update per feedback

* Parameterize tests and remaining feedback

* Correct log level in init

* nitpick feedback

tests/components/heos/conftest.py

@@ -18,21 +18,60 @@ import pytest
 import pytest_asyncio
 
 from homeassistant.components import ssdp
-from homeassistant.components.heos import DOMAIN
-from homeassistant.const import CONF_HOST
+from homeassistant.components.heos import (
+    CONF_PASSWORD,
+    DOMAIN,
+    ControllerManager,
+    GroupManager,
+    HeosRuntimeData,
+    SourceManager,
+)
+from homeassistant.const import CONF_HOST, CONF_USERNAME
 
 from tests.common import MockConfigEntry
 
 
 @pytest.fixture(name="config_entry")
-def config_entry_fixture():
+def config_entry_fixture(heos_runtime_data):
     """Create a mock HEOS config entry."""
-    return MockConfigEntry(
+    entry = MockConfigEntry(
         domain=DOMAIN,
         data={CONF_HOST: "127.0.0.1"},
         title="HEOS System (via 127.0.0.1)",
         unique_id=DOMAIN,
     )
+    entry.runtime_data = heos_runtime_data
+    return entry
+
+
+@pytest.fixture(name="config_entry_options")
+def config_entry_options_fixture(heos_runtime_data):
+    """Create a mock HEOS config entry with options."""
+    entry = MockConfigEntry(
+        domain=DOMAIN,
+        data={CONF_HOST: "127.0.0.1"},
+        title="HEOS System (via 127.0.0.1)",
+        options={CONF_USERNAME: "user", CONF_PASSWORD: "pass"},
+        unique_id=DOMAIN,
+    )
+    entry.runtime_data = heos_runtime_data
+    return entry
+
+
+@pytest.fixture(name="heos_runtime_data")
+def heos_runtime_data_fixture(controller_manager, players):
+    """Create a mock HeosRuntimeData fixture."""
+    return HeosRuntimeData(
+        controller_manager, Mock(GroupManager), Mock(SourceManager), players
+    )
+
+
+@pytest.fixture(name="controller_manager")
+def controller_manager_fixture(controller):
+    """Create a mock controller manager fixture."""
+    mock_controller_manager = Mock(ControllerManager)
+    mock_controller_manager.controller = controller
+    return mock_controller_manager
 
 
 @pytest.fixture(name="controller")
@@ -43,6 +82,7 @@ def controller_fixture(
     mock_heos = Mock(Heos)
     for player in players.values():
         player.heos = mock_heos
+    mock_heos.return_value = mock_heos
     mock_heos.dispatcher = dispatcher
     mock_heos.get_players.return_value = players
     mock_heos.players = players
@@ -55,11 +95,10 @@ def controller_fixture(
     mock_heos.connection_state = const.STATE_CONNECTED
     mock_heos.get_groups.return_value = group
     mock_heos.create_group.return_value = None
-    mock = Mock(return_value=mock_heos)
 
     with (
-        patch("homeassistant.components.heos.Heos", new=mock),
-        patch("homeassistant.components.heos.config_flow.Heos", new=mock),
+        patch("homeassistant.components.heos.Heos", new=mock_heos),
+        patch("homeassistant.components.heos.config_flow.Heos", new=mock_heos),
     ):
         yield mock_heos
 

tests/components/heos/test_config_flow.py

@@ -1,11 +1,12 @@
 """Tests for the Heos config flow module."""
 
-from pyheos import HeosError
+from pyheos import CommandFailedError, HeosError
+import pytest
 
 from homeassistant.components import heos, ssdp
 from homeassistant.components.heos.const import DOMAIN
 from homeassistant.config_entries import SOURCE_SSDP, SOURCE_USER
-from homeassistant.const import CONF_HOST
+from homeassistant.const import CONF_HOST, CONF_PASSWORD, CONF_USERNAME
 from homeassistant.core import HomeAssistant
 from homeassistant.data_entry_flow import FlowResultType
 
@@ -190,3 +191,141 @@ async def test_reconfigure_cannot_connect_recovers(
     assert config_entry.unique_id == DOMAIN
     assert result["reason"] == "reconfigure_successful"
     assert result["type"] is FlowResultType.ABORT
+
+
+@pytest.mark.parametrize(
+    ("error", "expected_error_key"),
+    [
+        (
+            CommandFailedError("sign_in", "Invalid credentials", 6),
+            "invalid_auth",
+        ),
+        (
+            CommandFailedError("sign_in", "User not logged in", 8),
+            "invalid_auth",
+        ),
+        (CommandFailedError("sign_in", "user not found", 10), "invalid_auth"),
+        (CommandFailedError("sign_in", "System error", 12), "unknown"),
+        (HeosError(), "unknown"),
+    ],
+)
+async def test_options_flow_signs_in(
+    hass: HomeAssistant,
+    config_entry,
+    controller,
+    error: HeosError,
+    expected_error_key: str,
+) -> None:
+    """Test options flow signs-in with entered credentials."""
+    config_entry.add_to_hass(hass)
+
+    # Start the options flow. Entry has not current options.
+    assert CONF_USERNAME not in config_entry.options
+    assert CONF_PASSWORD not in config_entry.options
+    result = await hass.config_entries.options.async_init(config_entry.entry_id)
+    assert result["step_id"] == "init"
+    assert result["errors"] == {}
+    assert result["type"] is FlowResultType.FORM
+
+    # Invalid credentials, system error, or unexpected error.
+    user_input = {CONF_USERNAME: "user", CONF_PASSWORD: "pass"}
+    controller.sign_in.side_effect = error
+    result = await hass.config_entries.options.async_configure(
+        result["flow_id"], user_input
+    )
+    assert controller.sign_in.call_count == 1
+    assert controller.sign_out.call_count == 0
+    assert result["step_id"] == "init"
+    assert result["errors"] == {"base": expected_error_key}
+    assert result["type"] is FlowResultType.FORM
+
+    # Valid credentials signs-in and creates entry
+    controller.sign_in.reset_mock()
+    controller.sign_in.side_effect = None
+    result = await hass.config_entries.options.async_configure(
+        result["flow_id"], user_input
+    )
+    assert controller.sign_in.call_count == 1
+    assert controller.sign_out.call_count == 0
+    assert result["data"] == user_input
+    assert result["type"] is FlowResultType.CREATE_ENTRY
+
+
+async def test_options_flow_signs_out(
+    hass: HomeAssistant, config_entry, controller
+) -> None:
+    """Test options flow signs-out when credentials cleared."""
+    config_entry.add_to_hass(hass)
+
+    # Start the options flow. Entry has not current options.
+    result = await hass.config_entries.options.async_init(config_entry.entry_id)
+    assert result["step_id"] == "init"
+    assert result["errors"] == {}
+    assert result["type"] is FlowResultType.FORM
+
+    # Fail to sign-out, show error
+    user_input = {}
+    controller.sign_out.side_effect = HeosError()
+    result = await hass.config_entries.options.async_configure(
+        result["flow_id"], user_input
+    )
+    assert controller.sign_in.call_count == 0
+    assert controller.sign_out.call_count == 1
+    assert result["step_id"] == "init"
+    assert result["errors"] == {"base": "unknown"}
+    assert result["type"] is FlowResultType.FORM
+
+    # Clear credentials
+    controller.sign_out.reset_mock()
+    controller.sign_out.side_effect = None
+    result = await hass.config_entries.options.async_configure(
+        result["flow_id"], user_input
+    )
+    assert controller.sign_in.call_count == 0
+    assert controller.sign_out.call_count == 1
+    assert result["data"] == user_input
+    assert result["type"] is FlowResultType.CREATE_ENTRY
+
+
+@pytest.mark.parametrize(
+    ("user_input", "expected_errors"),
+    [
+        ({CONF_USERNAME: "user"}, {CONF_PASSWORD: "password_missing"}),
+        ({CONF_PASSWORD: "pass"}, {CONF_USERNAME: "username_missing"}),
+    ],
+)
+async def test_options_flow_missing_one_param_recovers(
+    hass: HomeAssistant,
+    config_entry,
+    controller,
+    user_input: dict[str, str],
+    expected_errors: dict[str, str],
+) -> None:
+    """Test options flow signs-in after recovering from only username or password being entered."""
+    config_entry.add_to_hass(hass)
+
+    # Start the options flow. Entry has not current options.
+    assert CONF_USERNAME not in config_entry.options
+    assert CONF_PASSWORD not in config_entry.options
+    result = await hass.config_entries.options.async_init(config_entry.entry_id)
+    assert result["step_id"] == "init"
+    assert result["errors"] == {}
+    assert result["type"] is FlowResultType.FORM
+
+    # Enter only username or password
+    result = await hass.config_entries.options.async_configure(
+        result["flow_id"], user_input
+    )
+    assert result["step_id"] == "init"
+    assert result["errors"] == expected_errors
+    assert result["type"] is FlowResultType.FORM
+
+    # Enter valid credentials
+    user_input = {CONF_USERNAME: "user", CONF_PASSWORD: "pass"}
+    result = await hass.config_entries.options.async_configure(
+        result["flow_id"], user_input
+    )
+    assert controller.sign_in.call_count == 1
+    assert controller.sign_out.call_count == 0
+    assert result["data"] == user_input
+    assert result["type"] is FlowResultType.CREATE_ENTRY

tests/components/heos/test_init.py

@@ -1,6 +1,7 @@
 """Tests for the init module."""
 
 import asyncio
+from typing import cast
 from unittest.mock import Mock, patch
 
 from pyheos import CommandFailedError, HeosError, const
@@ -8,11 +9,14 @@ import pytest
 
 from homeassistant.components.heos import (
     ControllerManager,
+    HeosOptions,
     HeosRuntimeData,
     async_setup_entry,
     async_unload_entry,
 )
 from homeassistant.components.heos.const import DOMAIN
+from homeassistant.config_entries import ConfigEntryState
+from homeassistant.const import CONF_HOST, CONF_PASSWORD, CONF_USERNAME
 from homeassistant.core import HomeAssistant
 from homeassistant.exceptions import ConfigEntryNotReady
 from homeassistant.setup import async_setup_component
@@ -61,6 +65,32 @@ async def test_async_setup_entry_loads_platforms(
         controller.disconnect.assert_not_called()
 
 
+async def test_async_setup_entry_with_options_loads_platforms(
+    hass: HomeAssistant,
+    config_entry_options,
+    config,
+    controller,
+    input_sources,
+    favorites,
+) -> None:
+    """Test load connects to heos with options, retrieves players, and loads platforms."""
+    config_entry_options.add_to_hass(hass)
+    assert await async_setup_component(hass, DOMAIN, config)
+    await hass.async_block_till_done()
+
+    # Assert options passed and methods called
+    assert config_entry_options.state is ConfigEntryState.LOADED
+    options = cast(HeosOptions, controller.call_args[0][0])
+    assert options.host == config_entry_options.data[CONF_HOST]
+    assert options.credentials.username == config_entry_options.options[CONF_USERNAME]
+    assert options.credentials.password == config_entry_options.options[CONF_PASSWORD]
+    assert controller.connect.call_count == 1
+    assert controller.get_players.call_count == 1
+    assert controller.get_favorites.call_count == 1
+    assert controller.get_input_sources.call_count == 1
+    controller.disconnect.assert_not_called()
+
+
 async def test_async_setup_entry_not_signed_in_loads_platforms(
     hass: HomeAssistant,
     config_entry,
@@ -85,8 +115,7 @@ async def test_async_setup_entry_not_signed_in_loads_platforms(
         assert controller.get_input_sources.call_count == 1
         controller.disconnect.assert_not_called()
     assert (
-        "127.0.0.1 is not logged in to a HEOS account and will be unable to retrieve "
-        "HEOS favorites: Use the 'heos.sign_in' service to sign-in to a HEOS account"
+        "The HEOS System is not logged in: Enter credentials in the integration options to access favorites and streaming services"
         in caplog.text
     )