# lib-core.maps-test

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

**Version:** 0.1.0  
**Lib-ID:** lib-core.maps-test  
**Requires:** lib-core.maps v>=0.1.1  
**Tags:** test, maps

## Topology

<!-- topology:start (auto-generated; do not edit) -->
```mermaid
graph LR
  this["lib-core.maps-test"]
  lib_core_maps["lib-core.maps"]
  this --> lib_core_maps
  engine["engine.*"]
  this --> engine
```
<!-- topology:end -->

## Coverage Statement

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

| Section | Assertion-Count | Coverage |
|---|---|---|
| Geometry | 3 | `size.w == 16`, `size.h == 16`, `tile_size() == 32` |
| Tile-Lookup + Walkability | 4 | `tile_at(0,0) == stone`, `tile_at(5,5) == grass`, `is_walkable(0,0) == false`, `is_walkable(5,5) == true` |
| Arity-flex tile_at | 1 | 3-arg with `nil` map_id falls back to current_map |
| Out-of-bounds | 2 | `tile_at(-1, 0) == nil`, `tile_at(0, 16) == nil` |
| `list()` | 1 | Returns 1 registered map after `load` |
| **TOTAL** | **11** | |

### Tested-Surface
- `maps.load`, `maps.set_current`
- `maps.size`, `maps.tile_size`
- `maps.tile_at` (2-arg and 3-arg nil-fallback forms)
- `maps.is_walkable`
- `maps.list`

### Fault-Injection Audit (2026-05-16)

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

#### Caught Mutations

| # | Mutation | Caught by |
|---|---|---|
| M1 | `M.tile_at` renamed (API-break) | Runtime error "attempt to call a nil value (field 'tile_at')" — test aborts at assertion 4 |
| M2 | `M.is_walkable` body prefixed with `do return false end` | Assertion `grass interior walkable` fails (`not ok`, actual=false) |

#### Uncaught Mutations (Gaps)

| # | Mutation | Why uncaught | Severity |
|---|---|---|---|
| M3 | OOB guard in `M.tile_at` removed | Lua's 1-indexed tables return `nil` for index 0 and negative indices — tested OOB coordinates (`-1,0` and `0,16`) still produce `nil` without the guard | Low |

**Resolution:** Headless-reachable in principle, but guard is coincidentally shadowed by Lua nil-on-out-of-range semantics for all tested coordinates. Cheap fill would require a wrapping scenario — not applicable here. Future-Slice B: no cheap fix available; asserting the guard itself is not meaningful headless-side.

### Structurally Untestable
- Render-output of `maps.draw` (not part of API tested here; verified manually).

### Deferred
- Tile-mutation API (none in v0.1.x — read-only maps).

## Running

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

```bash
Sporel.exe --libs-dir=<libs-path> --test-libs=lib-core.maps-test
```

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

## API

### `run_tests(ctx)`
**Syntax:** `M.run_tests(ctx) → void` (test-lib entrypoint per ADR-0037)

Executes the test-suite against `lib-core.maps`. Calls `engine.exit(engine.test.failures())` at end; exit-code = failure-count.

## References

- ADR-0037 (Tests-as-Libs Convention)
- ADR-0038 (API-Doc-Convention)
- Production-Lib: `~/Projects/Sporel/sporel-libs/lib-core/maps/README.md`
- Spec: `meta/docs/superpowers/specs/2026-05-10-test-module-pattern-design.md`