Skip to content

stdseed.md

Latest commit

 

History

History
154 lines (127 loc) · 6.47 KB

stdseed.md

File metadata and controls

154 lines (127 loc) · 6.47 KB
module STDSEED
tag v0.1.3
phase Phase 1b
stable stable
since v0.1.3
synopsis declarative test data loader (v0.1.3)
labels
clear
load
loadJson
loaded
validate
errors
U-STDSEED-FILE-NOT-FOUND
U-STDSEED-FILER-ERROR
U-STDSEED-INVALID-JSON
U-STDSEED-INVALID-MANIFEST
U-STDSEED-MISSING-FIELD
U-STDSEED-MISSING-FILE
U-STDSEED-NO-FILER
conformance
see_also
STDJSON
created 2026-05-05
last_modified 2026-05-10
revisions 6
doc_type
REFERENCE

STDSEED — declarative test data

Loads a TSV manifest of FileMan records into the runtime environment so a test can run against a known fixture set. Each row is dispatched to a filer — a caller-supplied tag^routine reference. STDSEED is engine-neutral (the m layer of the m/v waterline): it ships no FileMan default, so the filer argument is required. A VistA caller injects a FileMan-backed filer (wrapping FILE^DIE) from the v layer (v-stdlib); a unit test injects a stub filer. This keeps the parser testable on a bare M engine with no VistA host.

Public API

Label Signature Returns
load do load^STDSEED(path,filer) — (mutates the database via filer).
loaded $$loaded^STDSEED(path) 1 iff path is currently tracked.
clear do clear^STDSEED(path) — (drops STDSEED's bookkeeping for path; idempotent).
validate $$validate^STDSEED(path) 1 if every row parses cleanly; raises $ECODE on syntax error.
loadJson do loadJson^STDSEED(jsonText,filer) — (mutates the database via filer; parses a JSON-array manifest).

The filer argument is required — STDSEED ships no FileMan default (the m/v waterline keeps FILE^DIE out of the m layer). An empty filer raises ,U-STDSEED-NO-FILER,. The filer is invoked once per row as

do @filer@(file,.fda,.iens)

with fda(file,"+1,",field)=value and iens an output IEN. STDSEED records the returned IEN under ^STDLIB($job,"stdseed",path,...) so clear() can drop it later.

Manifest format

# file 9.4 — package
9.4	.01=DEMO PACKAGE	1=DEMO	8=DEMO PACKAGE
# file 200 — user
200	.01=USER,TEST ONE	2=THING
  • One row per record. Columns are tab-separated.
  • The first column is the FileMan file number.
  • Subsequent columns are field=value pairs. The first = is the separator; embedded = characters are preserved in the value.
  • Lines starting with # and pure-whitespace lines are ignored.
  • Trailing CR (Windows-style line endings) is stripped automatically.

Examples

; against real FileMan — inject a v-layer FileMan filer (v-stdlib)
do load^STDSEED("/data/seed/widgets.tsv","fileViaDie^VSLSEED")
write $$loaded^STDSEED("/data/seed/widgets.tsv"),!  ; 1
do clear^STDSEED("/data/seed/widgets.tsv")          ; drops bookkeeping

; testing without FileMan — stub filer
do load^STDSEED("/tmp/widgets.tsv","capture^MYTEST")

; pre-flight validate
if '$$validate^STDSEED("/tmp/widgets.tsv") write "manifest broken",!

A custom filer has the shape:

capture(file,fda,iens)
        ; record fda(file,"+1,",field)=value somewhere observable
        set ^TMP("seed-capture",file,$increment(^TMP("seed-capture",file,"n")))=fda(file,"+1,",".01")
        set iens=42
        quit

A FileMan-backed filer is not part of STDSEED — it lives in the v layer (v-stdlib), wrapping FILE^DIE, and is injected by the VistA caller. This is the m/v waterline G2 decision (2026-06-14): the engine-neutral m layer carries no VistA symbol. Real-environment validation (filing inside an STDFIX rollback boundary against a FileMan-bearing endpoint) is therefore a v-stdlib concern; STDSEED's own suite injects stub filers exclusively and is fully covered.

Transactions

STDSEED does not open a transaction. The intended use is to wrap a load → test → clear cycle inside an STDFIX (v0.1.1+) TSTART / TROLLBACK pair so that filing side-effects roll back automatically. clear() only removes STDSEED's bookkeeping; it does not delete the records that the filer wrote. Until STDFIX ships, callers either (a) point the load at a stub filer for unit testing, or (b) rely on manual rollback.

Error codes

$ECODE When
,U-STDSEED-NO-FILER, load() / loadJson() called with an empty filer (it is required — no FileMan default)
,U-STDSEED-FILE-NOT-FOUND, path cannot be opened readonly
,U-STDSEED-MISSING-FILE, A row's first column (TSV) or a JSON element's file is empty
,U-STDSEED-MISSING-FIELD, A field=value pair has no =
,U-STDSEED-FILER-ERROR, The filer set $ECODE; STDSEED relays the failure
,U-STDSEED-INVALID-JSON, loadJson() text does not parse as JSON
,U-STDSEED-INVALID-MANIFEST, loadJson() parsed JSON is not an array of {"file":..} objects

See also

  • STDARGS — pairs with the m-cli m test --seed PATH flag (track Y) once the runner protocol lands at M1.
  • The TDD orchestration plan, §6.3 (tdd-orchestration-plan.md) — narrative around STDFIX / STDMOCK / STDSEED.

History

The original v0.1.3 release shipped TSV + a loadJson stub raising U-STDSEED-NOT-IMPLEMENTED. The real loadJson implementation (driven by $$parse^STDJSON) landed at v0.2.0 once STDJSON was available.

Through v0.2.x STDSEED bundled a fileViaDie default filer that called FILE^DIE when no filer was passed. That lone FileMan reference was removed (2026-06-14) to make STDSEED strictly engine-neutral for the m/v waterline G2 (no-VistA-symbols in the m layer): the filer argument is now required (U-STDSEED-NO-FILER if absent) and the FileMan-backed filer (fileViaDie^VSLSEED) lives in the v layer (v-stdlib), injected by the caller.

The six loadJson raises-path tests (U-STDSEED-LOAD-FAIL, U-STDSEED-NOT-IMPLEMENTED, U-STDSEED-INVALID-JSON, etc.) were parked at v0.2.0 alongside STDLOG-JSON's similarly-blocked tests and re-enabled together at e637425 once raises^STDASSERT gained use $principal to release SEQ-device context before the ZGOTO unwind. The actual hanging test was tLoadFilerErrorPropagatesEcode (test #12, mis-identified as #14 because of a TAP plan miscount); root cause was $ETRAP firing deep in walk^STDSEED while the OPENed TSV fixture was the current device. Post-fix STDSEEDTST runs 37/37 green on both engines (the two U-STDSEED-NO-FILER raises-tests were added with the G2 filer-required change; dual-engine verified YDB + IRIS).