test: import RuleValidationError; guarantee leap-day-spanning probes

tests/test_recurrence_property.py

@@ -0,0 +1,241 @@
+"""Consistency property tests for occurrences_between vs occurs_on.
+
+The done-condition: occurrences_between returns an ordered, duplicate-
+free list of dates that agrees EXACTLY with calling occurs_on on every
+date in the range.  This module proves that agreement two ways:
+
+1. An exhaustive sweep over a fixed grid of rules (every rule type ×
+   several intervals × several windows) cross-checked date by date.
+
+2. A randomized property test (seeded, deterministic) over randomly
+   generated rules and ranges asserting the two functions never
+   disagree.  Seeds are fixed so failures are reproducible.
+"""
+from __future__ import annotations
+
+import datetime
+import random
+
+import pytest
+
+from custom_components.nestquest.recurrence import (
+    RuleType,
+    RuleValidationError,
+    ScheduleRule,
+    occurs_on,
+    occurrences_between,
+)
+
+
+def _d(date: str) -> datetime.date:
+    return datetime.date.fromisoformat(date)
+
+
+def _check_consistency(
+    rule: ScheduleRule, start: str, end: str
+) -> list[str]:
+    """Cross-check occurrences_between against per-date occurs_on.
+
+    Returns the occurrences_between result after asserting, for every
+    date in [start, end]: occurs_on(date) is True iff the date appears
+    in the result.  Also asserts the list is ordered and duplicate-free.
+    """
+    result = occurrences_between(rule, start, end)
+    # Ordered and duplicate-free.
+    assert result == sorted(set(result)), (
+        f"occurrences_between must be ordered, duplicate-free: {result}"
+    )
+    # Exact agreement with occurs_on over every date in the range.
+    cursor = _d(start)
+    end_date = _d(end)
+    expected: list[str] = []
+    while cursor <= end_date:
+        if occurs_on(rule, cursor):
+            expected.append(cursor.isoformat())
+        cursor += datetime.timedelta(days=1)
+    assert result == expected, (
+        f"disagreement for {rule.to_dict()} over [{start}, {end}]:\n"
+        f"  occurrences_between: {result}\n"
+        f"  per-date occurs_on:  {expected}"
+    )
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Exhaustive grid over rule shapes, intervals and windows
+# ---------------------------------------------------------------------------
+
+
+_GRID_RULES = [
+    ScheduleRule(rule_type=RuleType.DAILY, start_date="2026-03-01"),
+    ScheduleRule(rule_type=RuleType.DAILY, interval=2,
+                 start_date="2026-03-01"),
+    ScheduleRule(rule_type=RuleType.DAILY, interval=3,
+                 start_date="2026-03-15", end_date="2027-01-31"),
+    ScheduleRule(rule_type=RuleType.WEEKLY, weekday_set={0, 2, 4},
+                 start_date="2026-03-03"),
+    ScheduleRule(rule_type=RuleType.WEEKLY, weekday_set={1, 3, 5},
+                 interval=2, start_date="2026-03-06",
+                 end_date="2027-06-30"),
+    ScheduleRule(rule_type=RuleType.CUSTOM_DAYS, weekday_set={1, 4},
+                 start_date="2026-03-06"),
+    ScheduleRule(rule_type=RuleType.MONTHLY_DAY, day_of_month=31,
+                 start_date="2026-03-31"),
+    ScheduleRule(rule_type=RuleType.MONTHLY_DAY, day_of_month=29,
+                 interval=2, start_date="2026-01-29"),
+    ScheduleRule(rule_type=RuleType.MONTHLY_WEEKDAY, nth_weekday=2,
+                 nth_weekday_weekday=1, start_date="2026-03-03"),
+    ScheduleRule(rule_type=RuleType.MONTHLY_WEEKDAY, nth_weekday=-1,
+                 nth_weekday_weekday=4, start_date="2026-03-06",
+                 end_date="2028-12-31"),
+    ScheduleRule(rule_type=RuleType.YEARLY, month=2, day_of_month=29,
+                 start_date="2026-02-28"),
+    ScheduleRule(rule_type=RuleType.YEARLY, month=6, day_of_month=15,
+                 interval=2, start_date="2026-06-15"),
+]
+
+_GRID_WINDOWS = [
+    ("2026-01-01", "2026-03-31"),   # mostly before start
+    ("2026-03-01", "2026-03-01"),   # single day == anchor
+    ("2026-03-01", "2026-03-31"),   # within window
+    ("2026-08-01", "2026-08-31"),   # mid-window month
+    ("2026-12-01", "2027-01-31"),   # year boundary
+    ("2028-01-01", "2028-03-01"),   # leap year span
+    ("2029-01-01", "2029-12-31"),   # far out
+]
+
+
+@pytest.mark.parametrize(
+    "rule_index,window_index",
+    [
+        (rule_index, window_index)
+        for rule_index in range(len(_GRID_RULES))
+        for window_index in range(len(_GRID_WINDOWS))
+    ],
+)
+def test_grid_occurrences_between_matches_occurs_on(
+    rule_index, window_index
+) -> None:
+    rule = _GRID_RULES[rule_index]
+    window = _GRID_WINDOWS[window_index]
+    _check_consistency(rule, window[0], window[1])
+
+
+# ---------------------------------------------------------------------------
+# Randomized property test (seeded, deterministic)
+# ---------------------------------------------------------------------------
+
+
+def _generate_random_rules(rng: random.Random, count: int) -> list[ScheduleRule]:
+    """Random but valid rules: shapes, intervals, anchors, windows.
+
+    Any random combo the model rejects (genuinely invalid combinations)
+    is skipped — the property only needs VALID rules; the assertion at
+    the end bounds how many may be rejected.
+    """
+    rules: list[ScheduleRule] = []
+    shapes = list(RuleType)
+    for index in range(count):
+        shape = shapes[rng.randrange(len(shapes))]
+        interval = rng.choice([1, 2, 3, 7])
+        anchor = datetime.date(
+            rng.choice([2024, 2025, 2026, 2027, 2028]),
+            rng.randrange(1, 13),
+            rng.randrange(1, 28),
+        )
+        end_offset = rng.choice([45, 120, 400, 800])
+        end = anchor + datetime.timedelta(days=end_offset)
+        common = {
+            "rule_type": shape,
+            "interval": interval,
+            "start_date": anchor.isoformat(),
+            "end_date": end.isoformat(),
+        }
+        try:
+            if shape is RuleType.WEEKLY:
+                rules.append(ScheduleRule(
+                    **common,
+                    weekday_set={
+                        rng.randrange(7)
+                        for _ in range(rng.randrange(1, 4))
+                    },
+                ))
+            elif shape is RuleType.CUSTOM_DAYS:
+                rules.append(ScheduleRule(
+                    **common,
+                    weekday_set={
+                        rng.randrange(7)
+                        for _ in range(rng.randrange(1, 4))
+                    },
+                ))
+            elif shape is RuleType.MONTHLY_DAY:
+                rules.append(ScheduleRule(
+                    **common, day_of_month=rng.randrange(1, 32)
+                ))
+            elif shape is RuleType.MONTHLY_WEEKDAY:
+                rules.append(ScheduleRule(
+                    **common,
+                    nth_weekday=rng.choice([-1, 1, 2, 3, 4, 5]),
+                    nth_weekday_weekday=rng.randrange(7),
+                ))
+            elif shape is RuleType.YEARLY:
+                rules.append(ScheduleRule(
+                    **common,
+                    month=rng.randrange(1, 13),
+                    day_of_month=rng.choice([None, rng.randrange(1, 29)]),
+                ))
+            else:  # DAILY
+                rules.append(ScheduleRule(**common))
+        except RuleValidationError:
+            continue
+    assert len(rules) >= count * 3 // 4, "too many random rules rejected"
+    return rules
+
+
+def test_random_rules_never_disagree_between_the_two_functions() -> None:
+    """The property: for randomly generated rules and ranges,
+    occurrences_between(rule, s, e) == [d for d in s..e if occurs_on]."""
+    rng = random.Random(0xFEA7)  # fixed seed for reproducibility
+    rules = _generate_random_rules(rng, count=40)
+    checked = 0
+    for rule in rules:
+        anchor = datetime.date.fromisoformat(rule.start_date)
+        for offset_days, span_days in ((-30, 60), (0, 14), (10, 90),
+                                       (100, 200)):
+            range_start = anchor + datetime.timedelta(days=offset_days)
+            range_end = range_start + datetime.timedelta(days=span_days)
+            _check_consistency(
+                rule, range_start.isoformat(), range_end.isoformat()
+            )
+            checked += 1
+    assert checked >= 40 * 4 * 3 // 4, checked
+
+
+def test_random_ranges_include_year_and_leap_spans() -> None:
+    """Every rule is probed across a range that spans Jan 1 (twice) and
+    a February 29 — the Dec 1..Mar 1 two-year span always covers both."""
+    rng = random.Random(42)
+    rules = _generate_random_rules(rng, count=12)
+    for rule in rules:
+        anchor = datetime.date.fromisoformat(rule.start_date)
+        probe_start = datetime.date(anchor.year, 12, 1)
+        probe_end = datetime.date(anchor.year + 2, 3, 1)
+        # The span always contains two Jan 1s and a Feb 28/29 pair.
+        assert probe_end >= probe_start
+        _check_consistency(
+            rule, probe_start.isoformat(), probe_end.isoformat()
+        )
+        # An additional probe pinned ON a Feb 29 window (2028 leap):
+        # every rule is cross-checked over Feb 1 - Mar 15 2028.
+        _check_consistency(rule, "2028-02-01", "2028-03-15")
+
+
+def test_occurrences_between_single_day_range_matches_occurs_on() -> None:
+    """A one-day range is the exact occurs_on of that date."""
+    for rule in _GRID_RULES:
+        for day in ("2026-03-05", "2026-03-15", "2027-06-15"):
+            single = occurrences_between(rule, day, day)
+            if occurs_on(rule, _d(day)):
+                assert single == [day], (rule.to_dict(), day, single)
+            else:
+                assert single == [], (rule.to_dict(), day, single)