selftest

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() HostInfo

func (h HostInfo) FormatBanner() string

type Options ¶

type Options struct {
	Out          io.Writer
	Filters      []string
	Verbose      bool
	NoColor      bool
	NoSpinner    bool
	JSON         bool
	SaveBaseline bool
}

Options configures a self-test run.

type PerfBaseline ¶ added in v0.14.0

type PerfBaseline struct {
	Allocs        uint64 `json:"allocs"`
	AllocBytes    uint64 `json:"alloc_bytes"`
	CompileAllocs uint64 `json:"compile_allocs"`
	RunAllocs     uint64 `json:"run_allocs"`

	AllocsDeltaPct  float64 `json:"allocs_delta_pct"`
	BytesDeltaPct   float64 `json:"bytes_delta_pct"`
	CompileDeltaPct float64 `json:"compile_delta_pct"`
	RunDeltaPct     float64 `json:"run_delta_pct"`

	Regressed bool `json:"regressed"`
}

PerfBaseline is the allocation comparison against a previously saved baseline. It is populated by ComputeScore only when a baseline file exists and was recorded on the same OS/arch as the current run.

Timing is deliberately absent. It is host-specific and would produce a false regression on any machine that is not the one the baseline was recorded on. Allocations are deterministic for the same code and toolchain, so they are what the delta tracks.

Regressed is a threshold, not any increase: a run that grew allocations by 3% when the baseline was recorded with one fewer allocation is not a regression, and a boolean that flipped on any increase would be noise instead of signal.

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 (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 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 (r Result) TotalAllocBytes() uint64

func (r Result) TotalAllocs() uint64

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"`

	// PerfBaseline is present only when a baseline file exists and
	// was recorded on the current OS/arch. It is nil on a first run.
	PerfBaseline *PerfBaseline `json:"perf_baseline,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.

Two concerns are reported from this type, deliberately distinguished by the fields they read:

• Correctness — Value() and Grade(). A single number because it answers a single question: did the code do what it should. The denominator excludes skipped features; a skipped feature was intentionally not exercised and cannot say anything about whether the code is correct.

• Performance — the raw allocation and timing measurements (TotalAllocs, Slowest, TopAllocators), plus the delta against a stored baseline (PerfBaseline). Several numbers because they answer several questions — did allocations grow, did they grow in the compile phase or the run phase, did any metric cross the tolerance.

There is no single "benchmark score". A number that merges allocations, bytes, compile, and run into one figure hides which metric moved; the deltas are what a reader acts on.

func ComputeScore(results []Result) Score

func (s Score) Grade() string

func (s Score) Scored() int

func (s Score) Value() float64

type Status ¶

type Status uint8

const (
	StatusPass Status = iota
	StatusFail
	StatusSkip
)