Skip to content

stdharn.md

Latest commit

 

History

History
102 lines (82 loc) · 4.63 KB

stdharn.md

File metadata and controls

102 lines (82 loc) · 4.63 KB
module STDHARN
tag
phase
stable stable
since
synopsis resident test/coverage harness orchestrator (v0.0.1)
labels
RUN
run
errors
conformance
see_also

STDHARN — Resident test/coverage harness orchestrator

The server-side half of run-and-verify (m-cli spec §9, stage 5.1). STDHARN runs *TST suites in the live namespace — next to the real FileMan DD and data — and emits a deterministic result frame that the Go m-cli client splits back through its unchanged mtest / mcov consumers. The contract is the frame, not the transport: the same envelope travels over the CLI's engine adapter and the editor's WebSocket.

Portable pure-M: suite execution + framing run identically on YottaDB and IRIS, so the splitter and the cross-engine parity tests are exercisable file-side with no IRIS. Only the ^%MONLBL coverage probe (a follow-up) and the watch hooks are IRIS-bound.

Why a resident orchestrator

The fast file-side tier runs each suite in its own process, so a failing suite's halt (inside report^STDASSERT) just ends that process. A resident orchestrator runs many suites in one process, where that halt would kill the run. STDHARN flips STDASSERT into no-halt mode (nohalt^STDASSERT): report then stashes its counts and returns instead of halting, and STDHARN reads them for the trailer. Each suite is crash-isolated — a mid-suite error becomes a non-zero ##END exit and the run continues — matching the file-side runner's OK = summary.OK && exit==0 semantics.

The result frame (spec §3.2)

##M-HARNESS frame=1 tier=integration engine=ydb ns=
##SUITE ^STDMATHTST
  PASS  clamp: 99 → 10
Results: 36 tests  36 passed  0 failed
All tests passed.
##END ^STDMATHTST exit=0
##END-HARNESS suites=1 pass=36 fail=0

Per-suite payloads are verbatim ^STDASSERT output (so mtest.ParseOutput consumes them unchanged); only the ## delimiter lines are new, and they never collide with ^STDASSERT / LCOV content. A ##LCOV block (coverage follow-up) slots in before the trailer.

Public API

Entry Signature Role
RUN ydb -run RUN^STDHARN "MATHTST STRTST" YDB CLI trigger: run the suites named in $ZCMDLINE, emit the frame.
run do run^STDHARN(scope) Run each suite in scope (space-separated names/entryrefs); emit header, per-suite blocks, trailer. The portable trigger path (m test --resident) drives this via RunScript (IRIS has no $ZCMDLINE).
cov do cov^STDHARN(scope,routines) Like run, but wrap execution in the IRIS line monitor and add a ##MON block of raw per-line counts.

Internal helpers compose the delimiter lines (header / suiteOpen / suiteClose / trailer), resolve the engine label (engine / ns), buffer the frame for in-M self-tests (capture / captured), and drive the IRIS line monitor (monStart / monDump / monStop).

Coverage — the ##MON block

Resident coverage is the IRIS tier (^%MONLBL / %Monitor.System.LineByLine); YDB coverage stays the host-side view "TRACE" path, so a YDB coverage frame carries an empty ##MON block. The resident side emits only raw per-line counts (MLINE:<routine>:<line>:<count>), not finished LCOV: the executable- line denominator is parse-tree-derived and lives host-side, so m-cli's mcov.FromMonitor joins the counts to that denominator. Because the host uses the same monitor data either way, resident coverage == file-side coverage by construction (the m-cli G4 gate proves it: STDMATH 29/30, host == resident).

Coverage-gate note. The IRIS monitor block (monStart / monDump / monDumpOne / monStop) is IRIS-only ObjectScript-via-XECUTE, so it is not line-counted when STDHARN coverage is measured on YDB; and it cannot be self-measured on IRIS because the harness monitor and the coverage monitor are the same %Monitor.System.LineByLine singleton (nesting clobbers counts). Those lines are functionally exercised by STDHARNTST on IRIS (real MLINE rows). The pure-orchestration core is fully covered; the engine-specific branches are covered on their native engine (same pattern as raises^STDASSERT).

Dependency

STDASSERT — the suite protocol (start / eq / report) plus its no-halt orchestration mode (nohalt / stash), which STDHARN drives.

Engine portability

Pure-M. The crash-isolation unwind splits by engine exactly as raises^STDASSERT does: YDB uses $ZLEVEL + ZGOTO, IRIS uses an ObjectScript try/catch. Coverage gate: ≥ 85 % (STDHARNTST).

See also

  • STDASSERT — the assertion protocol STDHARN orchestrates.