"
+ },
+ {
+ "equals": "watched-changed",
+ "replacement": "
"
+ },
+ {
+ "equals": "new",
+ "replacement": "
"
+ },
+ {
+ "equals": "missing-in-last-scan",
+ "replacement": "
"
+ }
+ ],
+ "localized": ["name"],
+ "name": [
+ {
+ "language_code": "en_us",
+ "string": "Status"
+ }
+ ]
+ }
+ ]
+}
diff --git a/front/plugins/fritzbox/fritzbox.py b/front/plugins/fritzbox/fritzbox.py
new file mode 100755
index 00000000..08915ecb
--- /dev/null
+++ b/front/plugins/fritzbox/fritzbox.py
@@ -0,0 +1,273 @@
+#!/usr/bin/env python
+
+import hashlib
+import os
+import sys
+from pytz import timezone
+
+# Define the installation path and extend the system path for plugin imports
+INSTALL_PATH = os.getenv('NETALERTX_APP', '/app')
+sys.path.extend([f"{INSTALL_PATH}/front/plugins", f"{INSTALL_PATH}/server"])
+
+from const import logPath # noqa: E402, E261 [flake8 lint suppression]
+from plugin_helper import Plugin_Objects, normalize_mac # noqa: E402, E261 [flake8 lint suppression]
+from logger import mylog, Logger # noqa: E402, E261 [flake8 lint suppression]
+from helper import get_setting_value # noqa: E402, E261 [flake8 lint suppression]
+
+import conf # noqa: E402, E261 [flake8 lint suppression]
+
+# Make sure the TIMEZONE for logging is correct
+conf.tz = timezone(get_setting_value('TIMEZONE'))
+
+# Make sure log level is initialized correctly
+Logger(get_setting_value('LOG_LEVEL'))
+
+pluginName = 'FRITZBOX'
+
+INTERFACE_MAP = {
+ '802.11': 'WiFi',
+ 'Ethernet': 'LAN',
+}
+
+# Define the current path and log file paths
+LOG_PATH = logPath + '/plugins'
+LOG_FILE = os.path.join(LOG_PATH, f'script.{pluginName}.log')
+RESULT_FILE = os.path.join(LOG_PATH, f'last_result.{pluginName}.log')
+
+# Initialize the Plugin obj output file
+plugin_objects = Plugin_Objects(RESULT_FILE)
+
+
+def get_fritzbox_connection(host, port, user, password, use_tls):
+ """
+ Create FritzConnection with error handling.
+ Returns: FritzConnection object or None on failure
+ """
+ try:
+ from fritzconnection import FritzConnection
+
+ mylog('verbose', [f'[{pluginName}] Attempting connection to {host}:{port} (TLS: {use_tls})'])
+
+ fc = FritzConnection(
+ address=host,
+ port=port,
+ user=user,
+ password=password,
+ use_tls=use_tls,
+ )
+
+ mylog('verbose', [f'[{pluginName}] Successfully connected to Fritz!Box'])
+ mylog('verbose', [f'[{pluginName}] Model: {fc.modelname}, Software: {fc.system_version}'])
+
+ return fc
+ except ImportError as e:
+ mylog('none', [f'[{pluginName}] ⚠ ERROR: fritzconnection library not installed: {e}'])
+ mylog('none', [f'[{pluginName}] Please install with: pip install fritzconnection'])
+ return None
+ except Exception as e:
+ mylog('none', [f'[{pluginName}] ⚠ ERROR: Failed to connect to Fritz!Box: {e}'])
+ mylog('none', [f'[{pluginName}] Check host ({host}), port ({port}), and credentials'])
+ mylog('none', [f'[{pluginName}] Ensure TR-064 is enabled in Fritz!Box settings'])
+ return None
+
+
+def get_connected_devices(fc, active_only):
+ """
+ Query all hosts from Fritz!Box via FritzHosts service.
+ Use get_hosts_info() for count, then get_generic_host_entry(index) for each.
+ Filter by NewActive status if active_only=True.
+ Returns: List of device dictionaries
+ """
+ devices = []
+
+ try:
+ from fritzconnection.lib.fritzhosts import FritzHosts
+
+ hosts = FritzHosts(fc)
+ host_count = hosts.host_numbers
+
+ mylog('verbose', [f'[{pluginName}] Found {host_count} total hosts in Fritz!Box'])
+
+ for index in range(host_count):
+ try:
+ host_info = hosts.get_generic_host_entry(index)
+
+ # Extract relevant fields
+ mac_address = host_info.get('NewMACAddress', '')
+ ip_address = host_info.get('NewIPAddress', '')
+ hostname = host_info.get('NewHostName', '')
+ active = host_info.get('NewActive', 0)
+ interface_type = host_info.get('NewInterfaceType', 'Unknown')
+
+ # Skip if active_only and device is not active
+ if active_only and not active:
+ continue
+
+ # Skip entries without MAC address
+ if not mac_address:
+ continue
+
+ # Normalize MAC address
+ mac_address = normalize_mac(mac_address)
+
+ # Map interface type to readable format
+ interface_display = interface_type
+ for key, value in INTERFACE_MAP.items():
+ if key in interface_type:
+ interface_display = value
+ break
+
+ # Build device dictionary
+ device = {
+ 'mac_address': mac_address,
+ 'ip_address': ip_address if ip_address else '',
+ 'hostname': hostname if hostname else 'Unknown',
+ 'active_status': 'Active' if active else 'Inactive',
+ 'interface_type': interface_display
+ }
+
+ devices.append(device)
+ mylog('verbose', [f'[{pluginName}] Device: {mac_address} ({hostname}) - {ip_address} - {interface_display}'])
+
+ except Exception as e:
+ mylog('minimal', [f'[{pluginName}] Warning: Failed to get host entry {index}: {e}'])
+ continue
+
+ mylog('verbose', [f'[{pluginName}] Processed {len(devices)} devices'])
+
+ except ImportError as e:
+ mylog('none', [f'[{pluginName}] ⚠ ERROR: fritzconnection library not properly installed: {e}'])
+ except Exception as e:
+ mylog('none', [f'[{pluginName}] ⚠ ERROR: Failed to query devices: {e}'])
+
+ return devices
+
+
+def check_guest_wifi_status(fc, guest_service_num):
+ """
+ Query a specific WLANConfiguration service for guest network status.
+ Returns: Dict with active status and interface info
+ """
+ guest_info = {
+ 'active': False,
+ 'ssid': 'Guest WiFi',
+ 'interface': 'Guest Network'
+ }
+
+ try:
+ service = f'WLANConfiguration{guest_service_num}'
+ result = fc.call_action(service, 'GetInfo')
+ status = result.get('NewEnable', False)
+ ssid = result.get('NewSSID', '')
+
+ if status:
+ guest_info['active'] = True
+ guest_info['ssid'] = ssid if ssid else 'Guest WiFi'
+ mylog('verbose', [f'[{pluginName}] Guest WiFi active on service {guest_service_num}: {guest_info["ssid"]}'])
+ else:
+ mylog('verbose', [f'[{pluginName}] Guest WiFi service {guest_service_num} is disabled'])
+
+ except Exception as e:
+ mylog('minimal', [f'[{pluginName}] Warning: Failed to query WLANConfiguration{guest_service_num}: {e}'])
+
+ return guest_info
+
+
+def create_guest_wifi_device(fc):
+ """
+ Create a synthetic device entry for guest WiFi.
+ Derives a locally-administered MAC (02:xx:xx:xx:xx:xx) from the Fritz!Box MAC.
+ Returns: Device dictionary
+ """
+ try:
+ # Get Fritz!Box MAC address
+ fritzbox_mac = fc.call_action('DeviceInfo:1', 'GetInfo').get('NewMACAddress', '')
+
+ if fritzbox_mac:
+ # Derive a deterministic locally-administered MAC (02:xx:xx:xx:xx:xx).
+ # The 02 prefix sets the locally-administered bit, ensuring no collision
+ # with real OUI-assigned MACs. The remaining 5 bytes come from an MD5
+ # hash of the Fritz!Box MAC so the guest MAC is stable across runs.
+ digest = hashlib.md5(f'GUEST:{normalize_mac(fritzbox_mac)}'.encode()).digest()
+ guest_mac = '02:' + ':'.join(f'{b:02x}' for b in digest[:5])
+ else:
+ # Fallback if we can't get Fritz!Box MAC
+ guest_mac = '02:00:00:00:00:01'
+
+ device = {
+ 'mac_address': guest_mac,
+ 'ip_address': '',
+ 'hostname': 'Guest WiFi Network',
+ 'active_status': 'Active',
+ 'interface_type': 'Access Point'
+ }
+
+ mylog('verbose', [f'[{pluginName}] Created guest WiFi device: {guest_mac}'])
+ return device
+
+ except Exception as e:
+ mylog('minimal', [f'[{pluginName}] Warning: Failed to create guest WiFi device: {e}'])
+ return None
+
+
+def main():
+ mylog('verbose', [f'[{pluginName}] In script'])
+
+ # Retrieve configuration settings
+ host = get_setting_value('FRITZBOX_HOST')
+ port = get_setting_value('FRITZBOX_PORT')
+ user = get_setting_value('FRITZBOX_USER')
+ password = get_setting_value('FRITZBOX_PASS')
+ use_tls = get_setting_value('FRITZBOX_USE_TLS')
+ report_guest = get_setting_value('FRITZBOX_REPORT_GUEST')
+ guest_service = get_setting_value('FRITZBOX_GUEST_SERVICE')
+ active_only = get_setting_value('FRITZBOX_ACTIVE_ONLY')
+
+ mylog('verbose', [f'[{pluginName}] Settings: host={host}, port={port}, use_tls={use_tls}, active_only={active_only}'])
+
+ # Create Fritz!Box connection
+ fc = get_fritzbox_connection(host, port, user, password, use_tls)
+
+ if not fc:
+ mylog('none', [f'[{pluginName}] ⚠ ERROR: Could not establish connection to Fritz!Box'])
+ mylog('none', [f'[{pluginName}] Plugin will return empty results'])
+ plugin_objects.write_result_file()
+ return 1
+
+ # Retrieve device data
+ device_data = get_connected_devices(fc, active_only)
+
+ # Check guest WiFi if enabled
+ if report_guest:
+ guest_status = check_guest_wifi_status(fc, guest_service)
+ if guest_status['active']:
+ guest_device = create_guest_wifi_device(fc)
+ if guest_device:
+ device_data.append(guest_device)
+
+ # Process the data into native application tables
+ if device_data:
+ for device in device_data:
+ plugin_objects.add_object(
+ primaryId=device['mac_address'],
+ secondaryId=device['ip_address'],
+ watched1=device['hostname'],
+ watched2=device['active_status'],
+ watched3=device['interface_type'],
+ watched4='',
+ extra='',
+ foreignKey=device['mac_address']
+ )
+
+ mylog('verbose', [f'[{pluginName}] Successfully processed {len(device_data)} devices'])
+ else:
+ mylog('minimal', [f'[{pluginName}] No devices found'])
+
+ # Log result
+ plugin_objects.write_result_file()
+
+ return 0
+
+
+if __name__ == '__main__':
+ sys.exit(main())
diff --git a/requirements.txt b/requirements.txt
index f713720d..2deb2cbd 100755
--- a/requirements.txt
+++ b/requirements.txt
@@ -34,3 +34,4 @@ freebox-api
mcp
psutil
pydantic>=2.0,<3.0
+fritzconnection>=1.15.1
diff --git a/test/plugins/test_fritzbox.py b/test/plugins/test_fritzbox.py
new file mode 100644
index 00000000..4a1d13a8
--- /dev/null
+++ b/test/plugins/test_fritzbox.py
@@ -0,0 +1,423 @@
+"""
+Tests for Fritz!Box plugin (fritzbox.py).
+
+fritzbox.py is imported directly. Its module-level side effects
+(get_setting_value, Logger, Plugin_Objects) are patched out before the
+first import so no live config reads, log files, or result files are
+created during tests.
+"""
+
+import hashlib
+import sys
+import os
+from unittest.mock import patch, MagicMock
+
+import pytest
+
+# ---------------------------------------------------------------------------
+# Path setup
+# ---------------------------------------------------------------------------
+
+_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
+_SERVER = os.path.join(_ROOT, "server")
+_PLUGIN_DIR = os.path.join(_ROOT, "front", "plugins", "fritzbox")
+
+for _p in [_ROOT, _SERVER, _PLUGIN_DIR]:
+ if _p not in sys.path:
+ sys.path.insert(0, _p)
+
+# ---------------------------------------------------------------------------
+# Import fritzbox with module-level side effects patched
+# ---------------------------------------------------------------------------
+# fritzbox.py calls get_setting_value(), Logger(), and Plugin_Objects() at
+# module level. Patching these before the first import prevents live config
+# reads, log-file creation, and result-file creation during tests.
+
+with patch("helper.get_setting_value", return_value="UTC"), \
+ patch("logger.Logger"), \
+ patch("plugin_helper.Plugin_Objects"):
+ import fritzbox # noqa: E402
+
+from plugin_helper import normalize_mac # noqa: E402
+
+# ---------------------------------------------------------------------------
+# Shared helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_host_entry(mac="AA:BB:CC:DD:EE:FF", ip="192.168.1.10",
+ hostname="testdevice", active=1, interface="Ethernet"):
+ return {
+ "NewMACAddress": mac,
+ "NewIPAddress": ip,
+ "NewHostName": hostname,
+ "NewActive": active,
+ "NewInterfaceType": interface,
+ }
+
+
+@pytest.fixture
+def mock_fritz_hosts():
+ """
+ Patches fritzconnection.lib.fritzhosts in sys.modules so that
+ fritzbox.get_connected_devices() uses a controllable FritzHosts mock.
+ Yields the FritzHosts *instance* (what FritzHosts(fc) returns).
+ """
+ hosts_instance = MagicMock()
+ fritz_hosts_module = MagicMock()
+ fritz_hosts_module.FritzHosts = MagicMock(return_value=hosts_instance)
+
+ with patch.dict("sys.modules", {
+ "fritzconnection": MagicMock(),
+ "fritzconnection.lib": MagicMock(),
+ "fritzconnection.lib.fritzhosts": fritz_hosts_module,
+ }):
+ yield hosts_instance
+
+
+# ===========================================================================
+# get_connected_devices
+# ===========================================================================
+
+class TestGetConnectedDevices:
+
+ def test_returns_active_device(self, mock_fritz_hosts):
+ mock_fritz_hosts.host_numbers = 1
+ mock_fritz_hosts.get_generic_host_entry.return_value = _make_host_entry(active=1)
+ devices = fritzbox.get_connected_devices(MagicMock(), active_only=True)
+ assert len(devices) == 1
+ assert devices[0]["active_status"] == "Active"
+
+ def test_active_only_filters_inactive_device(self, mock_fritz_hosts):
+ mock_fritz_hosts.host_numbers = 2
+ mock_fritz_hosts.get_generic_host_entry.side_effect = [
+ _make_host_entry(mac="AA:BB:CC:DD:EE:01", active=1),
+ _make_host_entry(mac="AA:BB:CC:DD:EE:02", active=0),
+ ]
+ devices = fritzbox.get_connected_devices(MagicMock(), active_only=True)
+ assert len(devices) == 1
+ assert devices[0]["mac_address"] == "aa:bb:cc:dd:ee:01"
+
+ def test_active_only_false_includes_inactive_device(self, mock_fritz_hosts):
+ mock_fritz_hosts.host_numbers = 2
+ mock_fritz_hosts.get_generic_host_entry.side_effect = [
+ _make_host_entry(mac="AA:BB:CC:DD:EE:01", active=1),
+ _make_host_entry(mac="AA:BB:CC:DD:EE:02", active=0),
+ ]
+ devices = fritzbox.get_connected_devices(MagicMock(), active_only=False)
+ assert len(devices) == 2
+ assert devices[1]["active_status"] == "Inactive"
+
+ def test_device_without_mac_is_skipped(self, mock_fritz_hosts):
+ mock_fritz_hosts.host_numbers = 2
+ mock_fritz_hosts.get_generic_host_entry.side_effect = [
+ _make_host_entry(mac=""),
+ _make_host_entry(mac="AA:BB:CC:DD:EE:01"),
+ ]
+ devices = fritzbox.get_connected_devices(MagicMock(), active_only=False)
+ assert len(devices) == 1
+ assert devices[0]["mac_address"] == "aa:bb:cc:dd:ee:01"
+
+ def test_ethernet_interface_maps_to_lan(self, mock_fritz_hosts):
+ mock_fritz_hosts.host_numbers = 1
+ mock_fritz_hosts.get_generic_host_entry.return_value = _make_host_entry(interface="Ethernet")
+ devices = fritzbox.get_connected_devices(MagicMock(), active_only=False)
+ assert devices[0]["interface_type"] == "LAN"
+
+ def test_wifi_interface_maps_to_wifi(self, mock_fritz_hosts):
+ mock_fritz_hosts.host_numbers = 1
+ mock_fritz_hosts.get_generic_host_entry.return_value = _make_host_entry(interface="802.11")
+ devices = fritzbox.get_connected_devices(MagicMock(), active_only=False)
+ assert devices[0]["interface_type"] == "WiFi"
+
+ def test_unknown_interface_is_preserved(self, mock_fritz_hosts):
+ mock_fritz_hosts.host_numbers = 1
+ mock_fritz_hosts.get_generic_host_entry.return_value = _make_host_entry(interface="SomeOtherType")
+ devices = fritzbox.get_connected_devices(MagicMock(), active_only=False)
+ assert devices[0]["interface_type"] == "SomeOtherType"
+
+ def test_mac_address_is_normalized_to_lowercase(self, mock_fritz_hosts):
+ mock_fritz_hosts.host_numbers = 1
+ mock_fritz_hosts.get_generic_host_entry.return_value = _make_host_entry(mac="AA:BB:CC:DD:EE:FF")
+ devices = fritzbox.get_connected_devices(MagicMock(), active_only=False)
+ assert devices[0]["mac_address"] == "aa:bb:cc:dd:ee:ff"
+
+ def test_missing_hostname_defaults_to_unknown(self, mock_fritz_hosts):
+ mock_fritz_hosts.host_numbers = 1
+ mock_fritz_hosts.get_generic_host_entry.return_value = _make_host_entry(hostname="")
+ devices = fritzbox.get_connected_devices(MagicMock(), active_only=False)
+ assert devices[0]["hostname"] == "Unknown"
+
+ def test_failed_host_entry_does_not_abort_remaining(self, mock_fritz_hosts):
+ mock_fritz_hosts.host_numbers = 3
+ mock_fritz_hosts.get_generic_host_entry.side_effect = [
+ _make_host_entry(mac="AA:BB:CC:DD:EE:01"),
+ Exception("TR-064 timeout"),
+ _make_host_entry(mac="AA:BB:CC:DD:EE:03"),
+ ]
+ devices = fritzbox.get_connected_devices(MagicMock(), active_only=False)
+ assert len(devices) == 2
+
+ def test_empty_host_list_returns_empty(self, mock_fritz_hosts):
+ mock_fritz_hosts.host_numbers = 0
+ devices = fritzbox.get_connected_devices(MagicMock(), active_only=False)
+ assert devices == []
+
+
+# ===========================================================================
+# check_guest_wifi_status
+# ===========================================================================
+
+class TestCheckGuestWifiStatus:
+
+ def test_disabled_service_returns_inactive(self):
+ fc = MagicMock()
+ fc.call_action.return_value = {"NewEnable": False, "NewSSID": ""}
+ result = fritzbox.check_guest_wifi_status(fc, guest_service_num=3)
+ assert result["active"] is False
+
+ def test_enabled_service_returns_active(self):
+ fc = MagicMock()
+ fc.call_action.return_value = {"NewEnable": True, "NewSSID": "MyGuestWiFi"}
+ result = fritzbox.check_guest_wifi_status(fc, guest_service_num=3)
+ assert result["active"] is True
+ assert result["ssid"] == "MyGuestWiFi"
+
+ def test_queries_correct_service_number(self):
+ fc = MagicMock()
+ fc.call_action.return_value = {"NewEnable": True, "NewSSID": "Guest"}
+ fritzbox.check_guest_wifi_status(fc, guest_service_num=2)
+ fc.call_action.assert_called_once_with("WLANConfiguration2", "GetInfo")
+
+ def test_service_exception_returns_inactive(self):
+ fc = MagicMock()
+ fc.call_action.side_effect = Exception("Service unavailable")
+ result = fritzbox.check_guest_wifi_status(fc, guest_service_num=3)
+ assert result["active"] is False
+
+ def test_empty_ssid_uses_default_label(self):
+ fc = MagicMock()
+ fc.call_action.return_value = {"NewEnable": True, "NewSSID": ""}
+ result = fritzbox.check_guest_wifi_status(fc, guest_service_num=3)
+ assert result["active"] is True
+ assert result["ssid"] == "Guest WiFi"
+
+ def test_service1_can_be_guest(self):
+ fc = MagicMock()
+ fc.call_action.return_value = {"NewEnable": True, "NewSSID": "Gast"}
+ result = fritzbox.check_guest_wifi_status(fc, guest_service_num=1)
+ assert result["active"] is True
+ fc.call_action.assert_called_once_with("WLANConfiguration1", "GetInfo")
+
+
+# ===========================================================================
+# create_guest_wifi_device
+# ===========================================================================
+
+class TestCreateGuestWifiDevice:
+
+ def _fc_with_mac(self, mac):
+ fc = MagicMock()
+ fc.call_action.return_value = {"NewMACAddress": mac}
+ return fc
+
+ def test_returns_device_dict(self):
+ device = fritzbox.create_guest_wifi_device(self._fc_with_mac("AA:BB:CC:DD:EE:FF"))
+ assert device is not None
+ assert "mac_address" in device
+ assert device["hostname"] == "Guest WiFi Network"
+ assert device["active_status"] == "Active"
+ assert device["interface_type"] == "Access Point"
+ assert device["ip_address"] == ""
+
+ def test_guest_mac_has_locally_administered_bit(self):
+ """First byte must be 0x02 — locally-administered, unicast."""
+ device = fritzbox.create_guest_wifi_device(self._fc_with_mac("AA:BB:CC:DD:EE:FF"))
+ first_byte = int(device["mac_address"].split(":")[0], 16)
+ assert first_byte == 0x02
+
+ def test_guest_mac_format_is_valid(self):
+ """MAC must be 6 colon-separated lowercase hex pairs."""
+ device = fritzbox.create_guest_wifi_device(self._fc_with_mac("AA:BB:CC:DD:EE:FF"))
+ parts = device["mac_address"].split(":")
+ assert len(parts) == 6
+ for part in parts:
+ assert len(part) == 2
+ int(part, 16) # raises ValueError if not valid hex
+
+ def test_guest_mac_is_deterministic(self):
+ """Same Fritz!Box MAC must always produce the same guest MAC."""
+ fc = self._fc_with_mac("AA:BB:CC:DD:EE:FF")
+ mac1 = fritzbox.create_guest_wifi_device(fc)["mac_address"]
+ mac2 = fritzbox.create_guest_wifi_device(fc)["mac_address"]
+ assert mac1 == mac2
+
+ def test_different_fritzbox_macs_produce_different_guest_macs(self):
+ mac_a = fritzbox.create_guest_wifi_device(self._fc_with_mac("AA:BB:CC:DD:EE:01"))["mac_address"]
+ mac_b = fritzbox.create_guest_wifi_device(self._fc_with_mac("AA:BB:CC:DD:EE:02"))["mac_address"]
+ assert mac_a != mac_b
+
+ def test_no_fritzbox_mac_uses_fallback(self):
+ """When DeviceInfo returns no MAC, fall back to 02:00:00:00:00:01."""
+ fc = MagicMock()
+ fc.call_action.return_value = {"NewMACAddress": ""}
+ device = fritzbox.create_guest_wifi_device(fc)
+ assert device["mac_address"] == "02:00:00:00:00:01"
+
+ def test_device_info_exception_returns_none(self):
+ """If DeviceInfo call raises, create_guest_wifi_device must return None."""
+ fc = MagicMock()
+ fc.call_action.side_effect = Exception("Connection refused")
+ device = fritzbox.create_guest_wifi_device(fc)
+ assert device is None
+
+ def test_known_mac_produces_known_guest_mac(self):
+ """
+ Regression anchor: for a fixed Fritz!Box MAC, the expected guest MAC
+ is precomputed here independently. If the hashing logic in
+ fritzbox.py changes, this test fails immediately.
+ """
+ fritzbox_mac = "aa:bb:cc:dd:ee:ff" # normalize_mac output of "AA:BB:CC:DD:EE:FF"
+ digest = hashlib.md5(f"GUEST:{fritzbox_mac}".encode()).digest()
+ expected = "02:" + ":".join(f"{b:02x}" for b in digest[:5])
+
+ device = fritzbox.create_guest_wifi_device(self._fc_with_mac("AA:BB:CC:DD:EE:FF"))
+ assert device["mac_address"] == expected
+
+
+# ===========================================================================
+# get_fritzbox_connection
+# ===========================================================================
+
+class TestGetFritzboxConnection:
+
+ def test_successful_connection(self):
+ fc_instance = MagicMock()
+ fc_instance.modelname = "FRITZ!Box 7590"
+ fc_instance.system_version = "7.57"
+ fc_class = MagicMock(return_value=fc_instance)
+ fc_module = MagicMock()
+ fc_module.FritzConnection = fc_class
+
+ with patch.dict("sys.modules", {"fritzconnection": fc_module}):
+ result = fritzbox.get_fritzbox_connection("fritz.box", 49443, "admin", "pass", True)
+
+ assert result is fc_instance
+ fc_class.assert_called_once_with(
+ address="fritz.box", port=49443, user="admin", password="pass", use_tls=True,
+ )
+
+ def test_import_error_returns_none(self):
+ with patch.dict("sys.modules", {"fritzconnection": None}):
+ result = fritzbox.get_fritzbox_connection("fritz.box", 49443, "admin", "pass", True)
+
+ assert result is None
+
+ def test_connection_exception_returns_none(self):
+ fc_module = MagicMock()
+ fc_module.FritzConnection.side_effect = Exception("Connection refused")
+
+ with patch.dict("sys.modules", {"fritzconnection": fc_module}):
+ result = fritzbox.get_fritzbox_connection("fritz.box", 49443, "admin", "pass", True)
+
+ assert result is None
+
+
+# ===========================================================================
+# main
+# ===========================================================================
+
+class TestMain:
+
+ _SETTINGS = {
+ "FRITZBOX_HOST": "fritz.box",
+ "FRITZBOX_PORT": 49443,
+ "FRITZBOX_USER": "admin",
+ "FRITZBOX_PASS": "secret",
+ "FRITZBOX_USE_TLS": True,
+ "FRITZBOX_REPORT_GUEST": False,
+ "FRITZBOX_GUEST_SERVICE": 3,
+ "FRITZBOX_ACTIVE_ONLY": True,
+ }
+
+ def _patch_settings(self):
+ return patch.object(
+ fritzbox, "get_setting_value",
+ side_effect=lambda key: self._SETTINGS[key],
+ )
+
+ def test_connection_failure_returns_1(self):
+ mock_po = MagicMock()
+ with self._patch_settings(), \
+ patch.object(fritzbox, "get_fritzbox_connection", return_value=None), \
+ patch.object(fritzbox, "plugin_objects", mock_po):
+ result = fritzbox.main()
+
+ assert result == 1
+ mock_po.write_result_file.assert_called_once()
+ mock_po.add_object.assert_not_called()
+
+ def test_scan_processes_devices(self):
+ devices = [
+ {"mac_address": "aa:bb:cc:dd:ee:01", "ip_address": "192.168.1.10",
+ "hostname": "device1", "active_status": "Active", "interface_type": "LAN"},
+ {"mac_address": "aa:bb:cc:dd:ee:02", "ip_address": "192.168.1.11",
+ "hostname": "device2", "active_status": "Active", "interface_type": "WiFi"},
+ ]
+ mock_po = MagicMock()
+
+ with self._patch_settings(), \
+ patch.object(fritzbox, "get_fritzbox_connection", return_value=MagicMock()), \
+ patch.object(fritzbox, "get_connected_devices", return_value=devices), \
+ patch.object(fritzbox, "plugin_objects", mock_po):
+ result = fritzbox.main()
+
+ assert result == 0
+ assert mock_po.add_object.call_count == 2
+ mock_po.write_result_file.assert_called_once()
+
+ def test_guest_wifi_device_appended_when_active(self):
+ devices = [
+ {"mac_address": "aa:bb:cc:dd:ee:01", "ip_address": "192.168.1.10",
+ "hostname": "device1", "active_status": "Active", "interface_type": "LAN"},
+ ]
+ guest_device = {
+ "mac_address": "02:a1:b2:c3:d4:e5", "ip_address": "",
+ "hostname": "Guest WiFi Network", "active_status": "Active",
+ "interface_type": "Access Point",
+ }
+ settings = {**self._SETTINGS, "FRITZBOX_REPORT_GUEST": True}
+ mock_po = MagicMock()
+
+ with patch.object(fritzbox, "get_setting_value", side_effect=lambda k: settings[k]), \
+ patch.object(fritzbox, "get_fritzbox_connection", return_value=MagicMock()), \
+ patch.object(fritzbox, "get_connected_devices", return_value=devices), \
+ patch.object(fritzbox, "check_guest_wifi_status", return_value={"active": True, "ssid": "Guest"}), \
+ patch.object(fritzbox, "create_guest_wifi_device", return_value=guest_device), \
+ patch.object(fritzbox, "plugin_objects", mock_po):
+ result = fritzbox.main()
+
+ assert result == 0
+ assert mock_po.add_object.call_count == 2 # 1 device + 1 guest
+ # Verify the guest device was passed correctly
+ guest_call = mock_po.add_object.call_args_list[1]
+ assert guest_call.kwargs["primaryId"] == "02:a1:b2:c3:d4:e5"
+ assert guest_call.kwargs["watched3"] == "Access Point"
+
+ def test_guest_wifi_not_appended_when_inactive(self):
+ devices = [
+ {"mac_address": "aa:bb:cc:dd:ee:01", "ip_address": "192.168.1.10",
+ "hostname": "device1", "active_status": "Active", "interface_type": "LAN"},
+ ]
+ settings = {**self._SETTINGS, "FRITZBOX_REPORT_GUEST": True}
+ mock_po = MagicMock()
+
+ with patch.object(fritzbox, "get_setting_value", side_effect=lambda k: settings[k]), \
+ patch.object(fritzbox, "get_fritzbox_connection", return_value=MagicMock()), \
+ patch.object(fritzbox, "get_connected_devices", return_value=devices), \
+ patch.object(fritzbox, "check_guest_wifi_status", return_value={"active": False, "ssid": ""}), \
+ patch.object(fritzbox, "plugin_objects", mock_po):
+ result = fritzbox.main()
+
+ assert result == 0
+ assert mock_po.add_object.call_count == 1 # only the real device