tests: add pytest suite for the glue's time-window logic

Regression protection for the class of bug this glue keeps hitting: a stale
enable flag reopening a ~24h dispatch (2026-07-14) and export firing ~30 min
early (2026-09-02). Covers _parse_time_of_day, _in_window (incl. midnight
cross + fails-permissive), _minutes_remaining (incl. same-day-passed-end and
midnight roll), and _clamp_power. 37 tests.

alphaess_glue.py is a pyscript module and isn't importable normally, so
tests/conftest.py execs it with pyscript's globals stubbed and a frozen clock -
the shipped glue stays byte-identical to what runs in HA. Deliberately does not
mock hardware dispatch/triggers (that's the live manual-slot territory in
AI-ASSISTANT.md).

Adds requirements-dev.txt, pytest.ini, and a README Tests section. (CI
workflow .github/workflows/ci.yml added separately - needs the workflow token
scope to push.)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019LAJPmF1cvsq1XRgtuxFuu

Author: jonphob

.gitignore

@@ -1,2 +1,3 @@
 __pycache__/
 *.pyc
+.pytest_cache/

README.md

@@ -118,6 +118,27 @@ and Predbat restarts mid-dispatch.
 | `ha-packages/predbat_alphaess_decoys.yaml` | Decoy helper entities + template switches |
 | `apps.yaml.snippet.yaml` | Predbat `apps.yaml` inverter/control/telemetry section |
 | `AI-ASSISTANT.md` | Copy-paste prompts for setting up & testing safely with an AI assistant |
+| `tests/` | Unit tests for the glue's time-window logic (pytest) |
+
+## Tests
+
+The glue's **time-window logic** — the part where subtle bugs keep appearing
+(a stale flag reopening a ~24h dispatch; export firing ~30 min early) — has a
+small [pytest](tests/) suite as regression protection. It doesn't try to mock
+the hardware dispatch or triggers (that's what the live manual-slot checks in
+`AI-ASSISTANT.md` are for); it locks down the pure logic: `_parse_time_of_day`,
+`_in_window`, `_minutes_remaining` (incl. midnight-crossing) and `_clamp_power`.
+
+`alphaess_glue.py` is a pyscript module and isn't normally importable, so
+`tests/conftest.py` loads it with pyscript's globals stubbed and a frozen clock —
+the shipped glue stays byte-identical to what runs in Home Assistant.
+
+```sh
+pip install -r requirements-dev.txt
+pytest
+```
+
+CI (`.github/workflows/ci.yml`) runs `py_compile` + the suite on every push and PR.
 
 ## Safety & disclaimer
 

pytest.ini

@@ -0,0 +1,2 @@
+[pytest]
+testpaths = tests

requirements-dev.txt

@@ -0,0 +1,3 @@
+# Dev/test dependencies only. The glue itself has no pip dependencies - it runs
+# inside Home Assistant's pyscript, which provides its runtime.
+pytest>=7

tests/conftest.py

@@ -0,0 +1,133 @@
+"""Test harness for alphaess_glue.py.
+
+alphaess_glue.py is a pyscript module, not a normal importable one: it relies on
+globals pyscript injects at runtime (`state`, `log`, `switch`, `number`,
+`select`, `button`, `task`) and on the `@time_trigger` / `@state_trigger`
+decorators, which run at import time. It also reads the wall clock via
+`datetime.datetime.now()`.
+
+So we can't `import` it. Instead we read the source and `exec` it in a namespace
+where those globals are stubbed and the clock is controllable. This keeps the
+*shipped* glue byte-identical to what runs in Home Assistant - the tests adapt to
+it, never the other way round.
+
+The `glue` fixture returns that namespace (functions + module constants), plus:
+  glue["S"]        - the FakeState (set entity states / attrs)
+  glue["set_now"]  - set the frozen wall-clock datetime
+  glue["log"]      - the log recorder (inspect emitted warnings/errors)
+"""
+
+import datetime as _dt
+import pathlib
+import types
+
+import pytest
+
+GLUE_PATH = pathlib.Path(__file__).resolve().parents[1] / "pyscript" / "alphaess_glue.py"
+
+
+class FakeState:
+    """Stand-in for pyscript's `state`. Entity states and attributes are just
+    dicts you populate per-test."""
+
+    def __init__(self):
+        self._vals = {}
+        self._attrs = {}
+
+    # pyscript API used by the glue
+    def get(self, entity_id):
+        return self._vals.get(entity_id)
+
+    def getattr(self, entity_id):
+        return self._attrs.get(entity_id)
+
+    def set(self, entity_id, value=None, **kwargs):
+        self._vals[entity_id] = value
+
+    # test helpers
+    def put(self, entity_id, value):
+        self._vals[entity_id] = value
+        return self
+
+    def put_attrs(self, entity_id, attrs):
+        self._attrs[entity_id] = attrs
+        return self
+
+
+class Recorder:
+    """No-op stand-in for log / switch / number / select / button / task.
+    Records every call so tests can assert on side effects if they want."""
+
+    def __init__(self):
+        self.calls = []
+
+    def __getattr__(self, name):
+        def _capture(*args, **kwargs):
+            self.calls.append((name, args, kwargs))
+        return _capture
+
+    def messages(self, level):
+        """e.g. recorder.messages('warning') -> list of message strings."""
+        return [a[0] for (n, a, k) in self.calls if n == level and a]
+
+
+def _noop_decorator(*d_args, **d_kwargs):
+    def deco(fn):
+        return fn
+    return deco
+
+
+class _Clock:
+    value = _dt.datetime(2026, 9, 3, 12, 0, 0)
+
+
+class FakeDatetime(_dt.datetime):
+    """Real datetime in every way except now(), which returns the frozen value.
+    Subclassing keeps strptime/combine/etc. behaving normally."""
+
+    @classmethod
+    def now(cls, tz=None):
+        return _Clock.value
+
+
+def _fake_datetime_module():
+    return types.SimpleNamespace(
+        datetime=FakeDatetime,
+        timedelta=_dt.timedelta,
+        date=_dt.date,
+        time=_dt.time,
+    )
+
+
+@pytest.fixture
+def glue():
+    src = GLUE_PATH.read_text()
+    ns = {}
+    # decorators that execute at import
+    ns["time_trigger"] = _noop_decorator
+    ns["state_trigger"] = _noop_decorator
+    ns["service"] = _noop_decorator
+    # pyscript injected globals
+    state = FakeState()
+    log = Recorder()
+    ns["state"] = state
+    ns["log"] = log
+    for name in ("switch", "number", "select", "button", "task"):
+        ns[name] = Recorder()
+
+    exec(compile(src, str(GLUE_PATH), "exec"), ns)
+
+    # Replace the real datetime the module imported with our controllable one,
+    # so functions calling datetime.datetime.now() see the frozen clock.
+    ns["datetime"] = _fake_datetime_module()
+
+    ns["S"] = state
+    ns["log"] = log
+
+    def set_now(dt):
+        _Clock.value = dt
+
+    ns["set_now"] = set_now
+    # sensible default clock for any test that forgets to set it
+    set_now(_dt.datetime(2026, 9, 3, 12, 0, 0))
+    return ns

tests/test_window_logic.py

@@ -0,0 +1,158 @@
+"""Unit tests for the glue's time-window logic.
+
+This is the code where subtle, real-world bugs have repeatedly lived:
+  * 2026-07-14  a stale enable flag + an unchanged end time silently reopened a
+                ~24h dispatch  -> guarded by _minutes_remaining returning 0 for a
+                same-day window whose end has already passed.
+  * 2026-09-02  export ran ~30 min early because the glue dispatched the moment
+                the enable flag was armed, ignoring the window start time
+                -> guarded by _in_window().
+
+The tests below lock in both behaviours plus the ordinary and midnight-crossing
+cases. Everything else in the glue (dispatch commit, triggers, hardware writes)
+is integration territory - validated with real manual slots, not mocked here.
+"""
+
+import datetime as dt
+
+import pytest
+
+S, E = "test.start", "test.end"
+
+
+def _at(glue, hh, mm, start=None, end=None):
+    """Set the clock to today at hh:mm and (optionally) the window entities."""
+    glue["set_now"](dt.datetime(2026, 9, 3, hh, mm, 0))
+    if start is not None:
+        glue["S"].put(S, start)
+    if end is not None:
+        glue["S"].put(E, end)
+
+
+# --------------------------------------------------------------------------
+# _parse_time_of_day
+# --------------------------------------------------------------------------
+
+@pytest.mark.parametrize("raw,expected", [
+    ("20:00", dt.time(20, 0)),
+    ("20:00:00", dt.time(20, 0, 0)),
+    ("05:30:00", dt.time(5, 30, 0)),
+    ("00:00", dt.time(0, 0)),
+])
+def test_parse_time_valid(glue, raw, expected):
+    assert glue["_parse_time_of_day"](raw) == expected
+
+
+@pytest.mark.parametrize("raw", ["garbage", "", "25:99", None, "unknown", "unavailable"])
+def test_parse_time_invalid_returns_none(glue, raw):
+    assert glue["_parse_time_of_day"](raw) is None
+
+
+# --------------------------------------------------------------------------
+# _in_window - same-day window (this is the 2026-09-02 regression)
+# --------------------------------------------------------------------------
+
+@pytest.mark.parametrize("hh,mm,expected", [
+    (19, 30, False),   # <-- armed 30 min early: MUST NOT dispatch (the fix)
+    (19, 59, False),
+    (20, 0, True),     # start boundary inclusive
+    (20, 30, True),    # squarely inside
+    (21, 0, True),     # end boundary inclusive
+    (21, 1, False),    # just after end
+    (23, 0, False),
+])
+def test_in_window_same_day(glue, hh, mm, expected):
+    _at(glue, hh, mm, start="20:00:00", end="21:00:00")
+    assert glue["_in_window"](S, E) is expected
+
+
+# --------------------------------------------------------------------------
+# _in_window - window crossing midnight (e.g. the overnight charge 23:30->05:30)
+# --------------------------------------------------------------------------
+
+@pytest.mark.parametrize("hh,mm,expected", [
+    (22, 0, False),    # before start
+    (23, 29, False),
+    (23, 30, True),    # start boundary
+    (23, 59, True),
+    (0, 30, True),     # after midnight, still in window
+    (5, 0, True),
+    (5, 30, True),     # end boundary
+    (5, 31, False),
+    (6, 0, False),     # after end
+    (12, 0, False),    # midday, nowhere near
+])
+def test_in_window_crosses_midnight(glue, hh, mm, expected):
+    _at(glue, hh, mm, start="23:30:00", end="05:30:00")
+    assert glue["_in_window"](S, E) is expected
+
+
+# --------------------------------------------------------------------------
+# _in_window - fails permissive when the start can't be read
+# --------------------------------------------------------------------------
+
+def test_in_window_unreadable_start_is_permissive(glue):
+    _at(glue, 3, 0, start="unknown", end="21:00:00")
+    assert glue["_in_window"](S, E) is True
+
+
+def test_in_window_unreadable_end_is_permissive(glue):
+    _at(glue, 3, 0, start="20:00:00", end=None)
+    assert glue["_in_window"](S, E) is True
+
+
+# --------------------------------------------------------------------------
+# _minutes_remaining
+# --------------------------------------------------------------------------
+
+def test_minutes_remaining_same_day_counts_to_end(glue):
+    _at(glue, 20, 0, start="20:00:00", end="21:00:00")
+    assert glue["_minutes_remaining"](S, E) == 60
+
+
+def test_minutes_remaining_same_day_passed_end_returns_zero(glue):
+    # 2026-07-14 regression: a same-day window whose end has passed is OVER,
+    # not "see you tomorrow" - otherwise a stale flag reopens a ~24h dispatch.
+    _at(glue, 22, 0, start="20:00:00", end="21:00:00")
+    assert glue["_minutes_remaining"](S, E) == 0
+
+
+def test_minutes_remaining_midnight_before_midnight(glue):
+    # 23:00, window 23:30->05:30 -> end rolls to tomorrow 05:30 = 390 min away.
+    _at(glue, 23, 0, start="23:30:00", end="05:30:00")
+    assert glue["_minutes_remaining"](S, E) == 390
+
+
+def test_minutes_remaining_midnight_after_midnight(glue):
+    # 02:00, window 23:30->05:30 -> end is today 05:30 = 210 min away.
+    _at(glue, 2, 0, start="23:30:00", end="05:30:00")
+    assert glue["_minutes_remaining"](S, E) == 210
+
+
+def test_minutes_remaining_unparseable_end_returns_zero_and_logs(glue):
+    _at(glue, 20, 0, start="20:00:00", end="garbage")
+    assert glue["_minutes_remaining"](S, E) == 0
+    assert glue["log"].messages("error"), "expected an error log for unparseable end"
+
+
+# --------------------------------------------------------------------------
+# _clamp_power - the 2026-08-05 out-of-range guard
+# --------------------------------------------------------------------------
+
+def test_clamp_power_within_range_unchanged(glue):
+    glue["S"].put_attrs(glue["DISPATCH_POWER"], {"min": -5.0, "max": 5.0})
+    assert glue["_clamp_power"](3.0) == 3.0
+    assert glue["_clamp_power"](-5.0) == -5.0
+
+
+def test_clamp_power_clamps_both_ends(glue):
+    glue["S"].put_attrs(glue["DISPATCH_POWER"], {"min": -5.0, "max": 5.0})
+    assert glue["_clamp_power"](6.0) == 5.0
+    assert glue["_clamp_power"](-6.0) == -5.0
+
+
+def test_clamp_power_falls_back_to_conservative_limit(glue):
+    # No attrs available -> _dispatch_power_limits falls back to +/-3.0.
+    assert glue["_clamp_power"](5.0) == 3.0
+    assert glue["_clamp_power"](-5.0) == -3.0
+    assert glue["log"].messages("warning"), "expected a CLAMPED warning"