blocker/docs/TESTING.md

Testing

What the golden tables are for

CLAUDE.md section 7 requires that the same decision table runs against the core and serves as the parity contract for all platforms.

The point is not to test the engine — unit tests do that. It is to make cross-platform divergence a build failure rather than a bug report from whichever platform nobody was testing that week.

golden/*.json ──┬──▶ core::evaluate          ──▶ must match `expect`
                ├──▶ Linux identity mapping  ──▶ must match `expect`
                └──▶ Android identity mapping ──▶ must match `expect`

Each platform implements a mapping from its own app identity (Android package name, Linux desktop-file id, Windows exe path) onto a Target. The engine is identical. If the mappings disagree about what an app is, a table case catches it.

The rule that keeps tables meaningful

A case is added before the engine changes.

A table written after the code records current behaviour. It can confirm nothing changed and can never catch a regression, because it was fitted to whatever the code happened to do.

So a PR that changes engine behaviour is reviewed on one question: is there a case added or updated in this same commit? If not, the change is undocumented behaviour, and that is a review failure, not a nit.

Format

JSON, one file per concern, under tests/golden/. The full type contract is in tests/src/golden.rs; that file is written before any parse layer exists, so M1 implements against a fixed format.

{
  "concern": "overnight",
  "cases": [
    {
      "name": "mon 22:00-06:00 window still active at tue 03:00",
      "covers": "7:overnight time ranges",
      "schedules": [
        { "id": "s1", "name": "Night", "mode": "Blocklist",
          "targets": [{"type": "app", "app": "com.example.social"}],
          "conditions": [{"type": "Time", "days": [0],
                           "start": "22:00", "end": "06:00"}] }
      ],
      "input": { "civil_time": "2026-10-06T03:00:00+02:00" },
      "expect": {
        "blocked_apps": [{"app": "com.example.social", "schedule": "s1"}],
        "next_wakeup": "2026-10-06T06:00:00+02:00"
      }
    }
  ]
}

Two conventions that matter:

• days is Monday = 0, matching time::Weekday.
• start > end means overnight. No crosses_midnight flag — the comparison already encodes it.
• civil_time always carries an explicit UTC offset, so a DST case is unambiguous.
• next_wakeup: "none" is a legal, meaningful expectation. It asserts the platform may sleep forever, which is the zero-idle-wakeup budget made testable.

Mandatory coverage

Every entry in golden::MANDATORY_COVERAGE must be claimed by at least one covers field, and a test asserts it — so a scenario cannot silently lose its test when someone reorganises files.

Tag	Scenario
7:overnight time ranges	Windows spanning midnight, including the weekday-of-start bug
7:DST changes	Spring-forward (a local time that does not exist) and fall-back (an ambiguous one)
7:timezone changes	Same instant, different local offset
7:clock tampering	System date moved; a lock must not shorten
7:strictest-wins	Overlapping schedules, blocklist and allowlist together
7:allowlist mode	Complement semantics, and the empty-inventory fail-open case
7:invalid condition combos	Each forbidden pairing from section 1.2
7:strict mode lock rules	Section 1.4: no editing, pausing, or uninstalling
1.2:time+usage rejected
1.2:time+launch rejected
1.2:usage+launch rejected
1.2:usage+location rejected
1.2:launch+location rejected
1.5.4:never-block list is unblockable
1.5.4:worst case 24h

Tables cannot express the passage of time

Most cases are pure data. Clock tampering is not: proving that moving the system date never shortens a lock requires actually moving a clock, which no JSON file can express.

Those cases live as code fixtures in tests/src/purity.rs instead, and the two coexist deliberately:

• Tables describe decisions. Given a state, what is the decision?
• Fixtures describe time. Given that time moved, does the lock behave?

Current fixtures, all of which pass:

Fixture	What it proves
backwards_wall_clock_never_shortens_a_lock	Setting the date back 3 days does not shorten a 12h lock
wall_clock_correction_respects_both_bounds	A skew extends, and clamps to the 24h cap
an_undisturbed_clock_costs_nothing	An honest clock adds no waiting
reboot_resumes_conservatively	A reboot does not reset a lock
worst_case_disable_path_is_capped	No level exceeds 24h
never_block_list_is_unblockable	The safety list is protected and does not over-match
engine_cannot_block_a_never_blocked_app	The engine itself enforces it, not just the list
dependency_purity	blocker-core still has zero dependencies

Engine unit tests

Alongside the tables, core/src/engine.rs carries tests for the logic that is hard to express as data — overnight windows, weekday indexing, boundaries, the allowlist complement, and next_wakeup behaviour.

weekday_indexing_is_monday_zero is the anchor test. If weekday arithmetic breaks, every other overnight test is quietly testing the wrong day, so this one asserts its own calendar dates directly.

Two tests exist specifically to protect the idle budget:

• wifi_schedule_declares_no_time_wakeup — a schedule only an OS event can change must not arm a timer.
• inactive_schedule_yields_no_wakeup — a schedule that is inactive now but starts later must still arm a wakeup. This is the subtle direction: over-sleeping means the schedule never fires.

Property tests

To be added in M1, once the tables exist. Candidates, in rough priority order:

• time_window_contains never panics for any days/start/end combination.
• evaluate is deterministic: same input, same output, always.
• A never-blocked target never appears in blocked_apps, for any schedule set.
• next_wakeup, when present, is strictly in the future relative to now.
• Strictest-wins is monotonic: adding a schedule never unblocks anything.

Platform testing

Linux

The X11 path is testable headless with Xvfb, which makes it the CI-exercised backend. The KWin path cannot be — it needs a real Plasma session — so its testing is manual, against the checklist below.

Manual, on a real session:

• Focusing a blocked native Wayland app raises the block screen within 150 ms
• Focusing a blocked XWayland app does the same
• Focusing an allowed app shows nothing
• The daemon survives a suspend/resume cycle
• The daemon survives logout/login
• Killing the daemon restarts it, and the tamper log records it
• The backend actually selected is the one expected on this session type, and the troubleshooting screen says which and why
• With KWin scripting disabled, the daemon falls back and says so
• Idle over 10 minutes: no wakeups, RSS under 15 MB

Android

Instrumented tests for the AccessibilityService path, which cannot run on a desktop JVM. M3-Android.

Manual checklist, per OS

The full checklist lives in docs/TESTING.md and grows with each milestone. Every entry maps to a section 1 requirement, so an uncovered requirement shows as an uncovered checklist line.

Running

scripts/ci.sh                  # everything, stop at first failure
scripts/ci.sh --keep-going     # everything, summarise all failures
cargo test --workspace         # just the tests

A milestone is not done until its acceptance checks pass and its performance numbers are recorded in PERF.md (section 7).

If a check fails, it gets reported and fixed. Weakening a test to make it pass is prohibited by section 10.6, and a test deleted to make a build green is the same mistake by another route.