knowledge-genome-orchestrator/tests/README.md

Tests

Deterministic tests for the mechanical layer of the framework — no LLM, no GPU, no network. They simulate pi's output with fixtures and exercise the scripts directly, so they run anywhere (laptop, CI, a git hook). They do not belong on vm101 or in n8n.

What's covered

File	Covers
scripts.bats	slug.sh, log-append.sh, index-append.py (insert, sort, bump, idempotent)
lint.bats	lib/lint.sh validators + scoped-lint.sh reuse + duplicate-slug advisory (edit-distance math, self-match skip, once-per-run)
structure.bats	lib/structure.sh report/sync
run-ingest.bats	run-ingest.sh end-to-end (DRY_RUN, local bare remote) — needs jq

run-ingest.bats auto-skips if jq is missing; everything else needs only bash + git (+ python3 for the index tests).

Install bats

# Debian/Ubuntu
sudo apt install bats
# or pinned, as a vendored submodule
git submodule add https://github.com/bats-core/bats-core.git test/bats

Run

bats tests/            # whole suite
bats tests/lint.bats   # one file
bats -f "sorted" tests/scripts.bats   # filter by name

Each test builds its own throwaway genome under BATS_TEST_TMPDIR (auto-cleaned) with a local bare git remote, so open-pr.sh --DRY_RUN can branch/commit/push without touching Forgejo.

Makefile targets

test:
	@bats tests/

verify-structure:
	@bash scripts/verify-genomes.sh

sync-structure:
	@bash scripts/verify-genomes.sh --sync

Note on helpers.bash

FIXTURE_DIRS in helpers.bash must match GENOME_DIRS in lib/structure.sh. If you change the canonical layout, update both (the structure tests assume a clean baseline).