Documentation
¶
Overview ¶
Package selftest runs the Nexss Flow self-test suite: a feature-by- feature check of every registered bundle, run in-process against the binary's own compiler and runtime.
It is designed to be embedded: `nflow self test` prints a live, category-colored checklist and exits 0 only when every feature passes. Both inline SelfTest() sections and *.nflow fixtures embedded by each bundle (Bundle.Fixtures) are discovered automatically and executed identically regardless of working directory or installed files.
Index ¶
- func Run(ctx context.Context, opts Options) int
- func SaveBaseline(s Score) error
- func Sections() []core.SelfTestSection
- type FeatureStat
- type HostInfo
- type Options
- type Renderer
- func (r *Renderer) Banner(sections []core.SelfTestSection)
- func (r *Renderer) FeatureDone(res Result)
- func (r *Renderer) FeatureStart(_ core.SelfTestFeature)
- func (r *Renderer) ScoreSummary(s Score, host HostInfo)
- func (r *Renderer) SectionDone(s core.SelfTestSection, all []Result, elapsed time.Duration)
- func (r *Renderer) SectionStart(s core.SelfTestSection)
- func (r *Renderer) Summary(results []Result, elapsed time.Duration)
- func (r *Renderer) TopMetrics(s Score)
- func (r *Renderer) UnmatchedFilters(filters []string)
- type Result
- type Score
- type Status
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Run ¶
Run executes the suite and returns a process exit code: 0 when every selected feature passes, 1 when at least one fails, 2 on configuration error (bad filter matched nothing).
The runner configuration is built exactly once. It is shared across every feature; fixtures are expected to be self-contained (each one declares its own @pipeline / @pool names). A fixture that references a name declared only by another fixture would still compile here, because the resolver is shared — the same way production behaves when two .nflow files are loaded into one process.
func SaveBaseline ¶
SaveBaseline writes the current run's fingerprint to the working directory. Overwrites any existing baseline; the caller is expected to invoke this only when the new behavior is intended.
func Sections ¶
func Sections() []core.SelfTestSection
Sections returns every feature contributed by every registered bundle. Inline self-tests come first (in declaration order); auto-discovered fixtures follow in lexical order.
Types ¶
type FeatureStat ¶
type FeatureStat struct {
Name string `json:"name"`
Section string `json:"section,omitempty"`
Elapsed time.Duration `json:"elapsed_ns"`
Allocs uint64 `json:"allocs"`
CompileAllocs uint64 `json:"compile_allocs"`
RunAllocs uint64 `json:"run_allocs"`
}
FeatureStat is one row in the slowest/top-allocator rankings.
type HostInfo ¶
type HostInfo struct {
GOOS string `json:"goos"`
GOARCH string `json:"goarch"`
GoVersion string `json:"go_version"`
NumCPU int `json:"num_cpu"`
CPUModel string `json:"cpu_model,omitempty"`
Goroutines int `json:"goroutines"`
}
HostInfo captures the runtime environment at the moment `nflow self test` starts. Every field is populated without spawning a subprocess and without CGo, so detection costs microseconds and behaves identically on Windows, Linux, macOS, and inside containers.
func DetectHost ¶
func DetectHost() HostInfo
func (HostInfo) FormatBanner ¶
FormatBanner returns the one-line host summary shown above the report.
type Options ¶
type Options struct {
Out io.Writer // terminal output (default os.Stdout)
Filters []string // case-insensitive substrings; empty = all sections
Verbose bool // print DSL and full failure details
NoColor bool // disable ANSI color
NoSpinner bool // disable live updates (for CI logs)
JSON bool // emit machine-readable JSON summary instead of text
SaveBaseline bool // write .nflow_selftest_baseline.json after the run
}
Options configures a self-test run.
type Renderer ¶
type Renderer struct {
// contains filtered or unexported fields
}
Renderer writes the live checklist. When its writer is a TTY it overwrites each feature line in place as the result arrives; when redirected, it prints plain lines suitable for CI logs.
func (*Renderer) Banner ¶
func (r *Renderer) Banner(sections []core.SelfTestSection)
func (*Renderer) FeatureDone ¶
FeatureDone prints one feature line: elapsed time, allocation counts split by phase, and — when the feature lives in an embedded *.nflow fixture — the path of that file. The path is deliberately shown last so the aligned columns stay readable when only some features are file-backed.
func (*Renderer) FeatureStart ¶
func (r *Renderer) FeatureStart(_ core.SelfTestFeature)
func (*Renderer) ScoreSummary ¶
func (*Renderer) SectionDone ¶
func (*Renderer) SectionStart ¶
func (r *Renderer) SectionStart(s core.SelfTestSection)
func (*Renderer) TopMetrics ¶
TopMetrics prints the slowest features and the biggest allocators. The allocator list shows the compile and run split so a reader can tell which phase dominated for that feature.
func (*Renderer) UnmatchedFilters ¶
UnmatchedFilters prints a red block after the summary listing every filter argument that matched no section and no feature.
type Result ¶
type Result struct {
core.SelfTestFeature
Section string
Status Status
Elapsed time.Duration
CompileAllocs uint64
CompileAllocBytes uint64
RunAllocs uint64
RunAllocBytes uint64
Err error
AssertErrs []error
SkipReason string
Captured []byte
}
Result is one feature's outcome.
Elapsed covers the whole runner.Execute call. CompileAllocs and RunAllocs split the allocation count by phase: the compile phase is the compiler's cost for parsing and building this DSL fragment, the run phase is the actual runtime cost of the pipeline. In a feature like `noop` all the work is in CompileAllocs and RunAllocs is zero.
func (Result) TotalAllocBytes ¶
TotalAllocBytes is the per-feature sum of compile and run bytes.
func (Result) TotalAllocs ¶
TotalAllocs is the per-feature sum of compile and run allocations.
type Score ¶
type Score struct {
Passed int `json:"passed"`
Failed int `json:"failed"`
Skipped int `json:"skipped"`
Total int `json:"total"`
Fingerprint string `json:"fingerprint"`
TotalAllocs uint64 `json:"total_allocs"`
TotalAllocBytes uint64 `json:"total_alloc_bytes"`
TotalCompileAllocs uint64 `json:"total_compile_allocs"`
TotalRunAllocs uint64 `json:"total_run_allocs"`
Slowest []FeatureStat `json:"slowest,omitempty"`
TopAllocators []FeatureStat `json:"top_allocators,omitempty"`
BaselineFingerprint string `json:"baseline_fingerprint,omitempty"`
BaselineMatched bool `json:"baseline_matched,omitempty"`
BaselinePresent bool `json:"baseline_present,omitempty"`
}
Score summarizes one self-test run in a form that is comparable across machines and stable across runs. The allocation totals split compile and run phases so a review can distinguish compiler cost from runtime cost at the run level, not just per feature.
func ComputeScore ¶
ComputeScore builds a Score from a completed run's results and attaches baseline comparison when the baseline file exists.
Source Files