feat(opnsense): implement send_wake_on_lan() via the os-wol plugin API

Calls POST /api/wol/wol/set with no uuid in the payload, which makes
the os-wol plugin's WolController::setAction validate and wake
immediately without persisting a host to config.xml. Requires the
os-wol plugin installed and the target interface to have a static
IPv4 (OPNsense derives the broadcast address from the interface's own
IP/subnet). Endpoint/payload verified against the plugin's source
(opnsense/plugins net/wol), not guessed.

tests/unit/test_driver.py

@@ -1007,6 +1007,54 @@ class TestInternalPost:
         assert result == {"result": "saved"}
 
 
+# ---------------------------------------------------------------------------
+# send_wake_on_lan()
+# ---------------------------------------------------------------------------
+
+class TestSendWakeOnLan:
+    def test_raises_value_error_without_interface(self, driver):
+        with pytest.raises(ValueError):
+            driver.send_wake_on_lan("AA:BB:CC:DD:EE:FF")
+        driver.session.post.assert_not_called()
+
+    def test_sends_correct_request(self, driver):
+        driver.session.post.return_value = _make_json_response({"status": ""})
+        driver.send_wake_on_lan("AA:BB:CC:DD:EE:FF", interface="lan")
+        driver.session.post.assert_called_once_with(
+            "https://opnsense.example.com/api/wol/wol/set",
+            json={"wake": {"interface": "lan", "mac": "AA:BB:CC:DD:EE:FF"}},
+            timeout=60,
+        )
+
+    def test_success_on_empty_status(self, driver):
+        # OPNsense's WolController returns {"status": trim(configd output)} on
+        # success — the underlying `wol` CLI tool typically prints nothing.
+        driver.session.post.return_value = _make_json_response({"status": ""})
+        result = driver.send_wake_on_lan("AA:BB:CC:DD:EE:FF", interface="lan")
+        assert result == {"success": True, "output": "Magic packet sent to AA:BB:CC:DD:EE:FF via lan"}
+
+    def test_returns_failure_on_error_status(self, driver):
+        driver.session.post.return_value = _make_json_response(
+            {"status": "error", "error_msg": "Incorrect IPv4 configuration on interface"}
+        )
+        result = driver.send_wake_on_lan("AA:BB:CC:DD:EE:FF", interface="opt1")
+        assert result == {"success": False, "output": "Incorrect IPv4 configuration on interface"}
+
+    def test_returns_failure_on_empty_response(self, driver):
+        # OPNsense's model validation (bad MAC/interface) silently returns {}
+        # with HTTP 200 rather than an error status.
+        driver.session.post.return_value = _make_json_response({})
+        result = driver.send_wake_on_lan("AA:BB:CC:DD:EE:FF", interface="lan")
+        assert result["success"] is False
+
+    def test_returns_failure_on_request_exception(self, driver):
+        # e.g. HTTP 404 — the os-wol plugin is not installed on this firewall.
+        driver.session.post.side_effect = Exception("404 Client Error: Not Found")
+        result = driver.send_wake_on_lan("AA:BB:CC:DD:EE:FF", interface="lan")
+        assert result["success"] is False
+        assert "404" in result["output"]
+
+
 # ---------------------------------------------------------------------------
 # load_merge_candidate()
 # ---------------------------------------------------------------------------