Testing Overview

The package ships with its full test suite — nine harnesses, 437 checks, runnable with npm test in a few seconds, no framework and no Node-RED runtime required. This section documents why each test exists: the harnesses are the project's executable specification, written contract-first (expected behavior agreed before implementation), and these pages are that specification made readable.

Philosophy

Test-first, contract-first. Every module's behavior was pinned as a contract — exact output shapes, exact semantics for edge cases — before its code existed. Several tests are literally the design document: the report harness asserts timeline rows character-for-character against the layout agreed in design.

No framework, no runtime. Each harness is a plain Node script using a tiny check(label, condition) helper, exiting nonzero on any failure. Node-RED itself is stubbed (a minimal RED object; for the tap, a fake hooks dispatcher), which keeps the suite fast and dependency-free. The trade-off is documented honestly: the real hook event shapes are the one believed-not-proven seam — see the Roadmap's integration-test entry.

Determinism everywhere. Time-dependent behavior (deltas, cooldowns, persistence debounce) runs against an injected fake clock with manually advanced timers; date formatting is pinned to UTC; the report tests render an incident generated by a real recorder store driven by that fake clock, so timestamps are exact.

Layered isolation. Library modules (normalize, core, persistence, report) are tested with zero Node-RED involvement; node wrappers are tested through the stub; the sanity harnesses test the package — editor files, manifest, and every shipped example flow.

The harnesses

Harness	Area	Checks	Detail page
normalize-harness	Message encoding pipeline: clone, redact, encode, truncate	53	Tests: Normalize
core-harness	The recording engine: ring buffer, commands, incidents, persistence policy	91	Tests: Core
persistence-harness	The file adapter: atomic writes, sanitization, restart round-trip	25	Tests: Persistence
inline-harness	The inline recorder node	46	Tests: Inline Node
control-harness	The control node and the command registry seam	25	Tests: Control Node
tap-harness	The tap node: scope, hooks, muting, auto-error	41	Tests: Tap Node
report-harness	The report engine and node: rendering, files, retention	83	Tests: Report Node
html-sanity + package-sanity	Structural: editor files, manifest, example flows	73	Tests: Sanity

Running

npm test            # all nine, in dependency order
node test-scripts/tap-harness.js    # any one alone

Two self-enforcing properties worth knowing: package-sanity fails if any harness in test-scripts/ isn't named in the npm test script (a new harness can't silently go unrun), and html-sanity fails if a node's editor file drifts from the config keys its runtime actually reads or if the control node's help panel stops documenting a runtime command.