# 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

<!-- topology:start (auto-generated; do not edit) -->
```mermaid
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
```
<!-- topology:end -->

## 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):

```bash
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`