mtest

Documentation

Overview

Package mtest is m-cli's test runner (spec §3.2): it discovers *TST.m suites, runs them through the Engine adapter, and parses the pure-M ^STDASSERT / TESTRUN output. The assertion library and suites are unchanged M that runs on both YottaDB and IRIS; only the host-side discovery + parsing live here.

Index

• Constants
• func DetectProtocol(src []byte) string
• func DetectTier(src []byte) string
• func IsSuiteFile(path string) bool
• func ReferencedRoutines(p *parse.Parser, src []byte) ([]string, error)
• type Assertion
• type Outcome
• type RunResult
  • func Run(ctx context.Context, eng engine.Engine, suites []TestSuite) ([]RunResult, error)
  • func RunSuite(ctx context.Context, eng engine.Engine, s TestSuite) (RunResult, error)
• type Summary
  • func ParseOutput(stdout string) Summary
• type TestCase
  • func FindCases(p *parse.Parser, suiteName string, src []byte) ([]TestCase, error)
• type TestSuite
  • func Affected(suites []TestSuite, changed map[string]bool) []TestSuite
  • func Discover(p *parse.Parser, paths []string) ([]TestSuite, error)

Constants

const (
	// TierPureLogic suites are deterministic, with no live DD/data dependency.
	// They run file-side (host-orchestrated) and are the PR gate. The safe
	// default for an untagged suite.
	TierPureLogic = "pure-logic"
	// TierIntegration suites exist because of the live FileMan DD + populated
	// globals and cannot be reproduced file-side. They run resident (in the dev
	// IRIS, next to the data).
	TierIntegration = "integration"
)

Tier classifies where a suite is authoritative (spec §9.1-Q6, design §3.4).

Functions

func DetectProtocol

func DetectProtocol(src []byte) string

DetectProtocol returns the routine hosting start/report for src (the first `do start^XYZ(.pass,.fail)`), defaulting to TESTRUN for legacy suites.

func DetectTier

func DetectTier(src []byte) string

DetectTier reads the suite's tier directive. An untagged suite is TierPureLogic — the safe default that keeps it the file-side PR gate; only an explicit `;; tier: integration` moves it to the resident tier.

func IsSuiteFile

func IsSuiteFile(path string) bool

IsSuiteFile reports whether path names a test suite by convention: stem matches [A-Z][A-Z0-9]*TST with an M extension (.m on YDB, .mac/.int on IRIS).

func ReferencedRoutines

func ReferencedRoutines(p *parse.Parser, src []byte) ([]string, error)

ReferencedRoutines returns the external routines src calls out to — every LABEL^ROUTINE / ^ROUTINE / $$^ROUTINE site — upper-cased and sorted. Local (bare-label / intra-routine) calls are excluded: they add no cross-file dependency. This maps a changed routine to the suites that exercise it.

Types

type Assertion

type Assertion struct {
	Outcome     Outcome
	Description string
	Expected    string
	Actual      string
}

Assertion is one " PASS/FAIL <desc>" line (with optional expected/actual).

type Outcome

type Outcome string

Outcome is a single assertion's result.

const (
	Pass Outcome = "pass"
	Fail Outcome = "fail"
)

type RunResult

type RunResult struct {
	Suite    string
	Summary  Summary
	OK       bool
	ExitCode int
	Stdout   string
}

RunResult is the outcome of running one suite.

func Run

func Run(ctx context.Context, eng engine.Engine, suites []TestSuite) ([]RunResult, error)

Run runs every suite in order and returns the per-suite results. It stops at the first engine error (e.g. the engine is unreachable), returning what ran.

func RunSuite

func RunSuite(ctx context.Context, eng engine.Engine, s TestSuite) (RunResult, error)

RunSuite runs the suite's entry routine ^SUITE through the engine and parses its ^STDASSERT/TESTRUN output. A suite is ok only when the parsed summary is ok AND the engine process exited 0 (a crash mid-suite must not read as a pass). Routines must already be available to the engine: on YDB they auto-compile from $ydb_routines; on IRIS the caller pre-loads them (OBJ.Load) during staging, since there is no compile-from-path.

type Summary

type Summary struct {
	Passed     int
	Failed     int
	Total      int
	OK         bool
	Assertions []Assertion
}

Summary is the parsed result of running a suite.

func ParseOutput

func ParseOutput(stdout string) Summary

ParseOutput parses ^STDASSERT / TESTRUN output into a Summary. The contract (STDASSERT.m): per-assertion " PASS/FAIL <desc>" lines, a "Results: <total> tests <p> passed <f> failed" summary, then either "All tests passed." or "<n> test(s) FAILED.".

type TestCase

type TestCase struct {
	Suite       string
	Label       string
	Description string
	Line        int
}

TestCase is one test label inside a suite.

func FindCases

func FindCases(p *parse.Parser, suiteName string, src []byte) ([]TestCase, error)

FindCases returns the test labels in src: a label qualifies when it matches t<UpperCase> and has formals containing both `pass` and `fail`. The first label (the routine entry / orchestrator) is never a test.

type TestSuite

type TestSuite struct {
	Name     string
	Path     string
	Protocol string // routine hosting start/report (STDASSERT, TESTRUN, …)
	Tier     string // TierPureLogic (default) | TierIntegration — see DetectTier
	Cases    []TestCase
	Deps     []string // external routines the suite calls (upper, sorted) — for affected-test selection
}

TestSuite is one *TST.m file with its cases.

func Affected

func Affected(suites []TestSuite, changed map[string]bool) []TestSuite

Affected returns the suites that exercise any of the changed routines: a suite matches when its own routine changed (the suite file itself) or it references a changed routine via its Deps. changed holds upper-cased routine names. Order is preserved from suites.

func Discover

func Discover(p *parse.Parser, paths []string) ([]TestSuite, error)

Discover walks paths and returns the suites in name order. Directories are scanned recursively for suite-named files; explicit file args are trusted (parsed even if the name doesn't match).