Files

Axel Meyer c5469d00d0 docs: add API section documenting run_tests entrypoint

Test-lib README now declares its public surface (M.run_tests) so the
doc-convention lint passes structural validation. Brings parity with
maps-test which already has this section.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-16 18:01:50 +02:00

3.8 KiB

Raw Permalink Blame History

lib-core.selection-test

Test-lib for lib-core.selection (Tests-as-Libs per ADR-0037).

Version: 0.1.0
Lib-ID: lib-core.selection-test
Requires: lib-core.selection v>=0.1.0, lib-core.input v>=0.4.0, lib-core.camera v>=0.3.0
Tags: test, selection

Topology

graph LR
  this["lib-core.selection-test"]
  lib_core_selection["lib-core.selection"]
  this --> lib_core_selection
  lib_core_input["lib-core.input"]
  this --> lib_core_input
  lib_core_camera["lib-core.camera"]
  this --> lib_core_camera

API

`run_tests(ctx)`

Syntax: M.run_tests(ctx) -> void

Description: Test-runner entrypoint. Executes 23 assertions against lib-core.selection. Called automatically by the engine's --test-libs= orchestrator. Exits via engine.exit(engine.test.failures()).

Coverage Statement

Per Fault-Injection-Audit-Convention (2026-05-16):

Section	Assertion-Count	Coverage
Register / Unregister	3	Handle positivity, `count_registered` after register/unregister
Set-Query (initial empty)	2	`is_empty()` true, `count() == 0`
Set-Mutation	5	`add`/`contains`, `count==1`, `remove`/`!contains`, `toggle` add/remove, `clear` -> empty
Unregister cascade	1	`unregister` removes from selection
Drag-Threshold	2	Default = 4, `set_drag_threshold` writes
Drag-State + box_rect	2	Initial `drag_state == "idle"`, `box_rect()` nil while idle
Enabled-Flag	2	Default true, `set_enabled(false)` writes
Visual-Setters	2	`set_drag_box_color` writes RGBA, `set_highlight_color` writes RGBA
Error-Handling	3	`set_drag_threshold(-1)` errors, `add(unregistered)` errors, `toggle(unregistered)` errors
TOTAL	22

Tested-Surface

selection.register, selection.unregister, selection.count_registered
selection.is_empty, selection.count, selection.contains
selection.add, selection.remove, selection.toggle, selection.clear
selection.drag_threshold, selection.set_drag_threshold
selection.drag_state, selection.box_rect
selection.enabled, selection.set_enabled
selection.set_drag_box_color, selection.drag_box_color
selection.set_highlight_color, selection.highlight_color

Fault-Injection Audit (2026-05-16)

Verified via deliberate-mutation in fixture-mirror; mutations reverted after observation.

Caught Mutations

#	Mutation	Caught by
M1	`M.contains` prefixed with `do return false end` (always false)	Assertions `add → contains` + `toggle adds when absent` fail (2 failures)
M2	`M.count` prefixed with `do return 0 end` (always zero)	Assertion `count = 1 after add` fails (expected 1, got 0)

Uncaught Mutations (Gaps) — Cheap-Fill Applied

#	Original Gap	Fill	Re-Inject Verifies
M3	`M.add` unregistered-handle guard removed	Added `pcall(add(99999))` + `pcall(toggle(99999))` error assertions	✓

Structurally Untestable

Mouse-drag selection-box interaction — requires real mouse events; headless drag_state stays idle.
Render output of highlight + drag-box visuals (verified manually).

Deferred

Integration test with simulated mouse events (Future-Slice B).

Running

Via --test-libs=lib-core.selection-test (Smoke P0-S-batch Stage):

Sporel.exe --libs-dir=<libs-path> --test-libs=lib-core.selection-test

Output is TAP version 13 on stdout; exit-code = failure-count (0 = all pass).

References

ADR-0037 (Tests-as-Libs Convention)
ADR-0038 (API-Doc-Convention)
Production-Lib: ~/Projects/Sporel/sporel-libs/lib-core/selection/README.md
Spec: meta/docs/superpowers/specs/2026-05-14-p3-6-lib-selection-design.md

3.8 KiB Raw Permalink Blame History