assert

Documentation

Overview

Package assert evaluates assertion steps against the current run result. Each Check returns a CheckResult carrying enough structured context (expected/actual/hint) for the console failure output and the JSON report.

Index

• func AllOK(results []*CheckResult) bool
• type ArtifactBlob
• type ArtifactFile
• type CheckResult
  • func Check(a *spec.Assert, res *runner.Result, env Env) *CheckResult
  • func CheckAll(a *spec.Assert, res *runner.Result, env Env) []*CheckResult
• type Env

Functions

func AllOK

func AllOK(results []*CheckResult) bool

AllOK reports whether every check in the slice passed.

Types

type ArtifactBlob

type ArtifactBlob struct {
	Role string
	Ext  string
	Data []byte
}

ArtifactBlob is one named binary payload to persist for a failed assertion (#52). Role shapes the filename (e.g. "actual", "baseline", "diff", "metadata") and Ext is its file extension (e.g. "png", "json").

type ArtifactFile

type ArtifactFile struct {
	Role string // "actual" | "expected"
	Path string // relative to the artifacts dir root, slash-separated
}

ArtifactFile references one sidecar file written for a failed assertion when --artifacts-dir is set (#48).

type CheckResult

type CheckResult struct {
	OK       bool
	Desc     string // human label, e.g. `assert stdout contains "Alice"`
	Expected string
	Actual   string
	Hint     string

	// ArtifactKind, ArtifactActual, and ArtifactExpected carry the full,
	// untruncated payloads a failed text assertion compared, for durable export
	// via --artifacts-dir (#48). Unlike Actual/Expected, which are excerpted for
	// display, these hold the complete bytes so a reviewer can inspect exactly
	// what atago matched against. They are set only for text-based assertions
	// (stdout/stderr/body/rows/message/value/file/snapshot); other checks leave
	// ArtifactKind empty, meaning "nothing to export". ArtifactExpected is nil
	// when the assertion has no meaningful expected payload (e.g. contains). The
	// engine masks these before writing, using the same masker as the display
	// fields.
	ArtifactKind     string
	ArtifactActual   []byte
	ArtifactExpected []byte

	// ArtifactBlobs are additional named binary payloads to persist for this
	// failed assertion (#52). Where ArtifactActual/ArtifactExpected are text, a
	// blob carries its own role and file extension, letting an image similar_to
	// failure emit the actual image, the baseline image, a deterministic visual
	// diff heatmap, and a metadata JSON as separate sidecar files.
	ArtifactBlobs []ArtifactBlob

	// ArtifactFiles lists the sidecar files the engine wrote for this failed
	// assertion when --artifacts-dir was set (#48). Paths are relative to the
	// artifacts dir root, in stable role order (actual before expected). It is
	// empty when no artifacts dir was configured or the assertion passed.
	ArtifactFiles []ArtifactFile
}

CheckResult is the structured outcome of one assertion.

func Check

func Check(a *spec.Assert, res *runner.Result, env Env) *CheckResult

Check evaluates an assert step and returns a single verdict: the first failing target's result, or the first result when all pass. It is a convenience over CheckAll for callers (and tests) that only need one pass/fail outcome.

func CheckAll

func CheckAll(a *spec.Assert, res *runner.Result, env Env) []*CheckResult

CheckAll evaluates every target set on an assert step and returns one CheckResult per target, in SetTargets order. An assert may set more than one target (exit_code + stdout + file …); each is an independent check and all must hold. res may be nil for targets that do not depend on a command (e.g. file assertions), in which case env.Workdir is still used to resolve paths. The returned slice always has at least one element.

type Env

type Env struct {
	Workdir         string
	SpecDir         string
	UpdateSnapshots bool
	// Secrets, when set, masks declared secret values in captured output before a
	// snapshot is written or compared, so a real credential is never committed to
	// a golden file (issue #11).
	Secrets func([]byte) []byte
	// Scrub, when set, applies the spec's declarative regex→placeholder rewrites
	// (#137) during snapshot normalization, so volatile output patterns the
	// built-in normalizers do not cover (auto-increment IDs, request identifiers)
	// are determinized before a snapshot is written or compared.
	Scrub func([]byte) []byte
	// MockRecords, when set, resolves a mock server's recorded requests by
	// name for the `mock:` assertion target (#24). Nil in contexts with no
	// mock servers (retry `until` asserts, direct API use).
	MockRecords func(name string) ([]mock.Record, bool)
}

Env carries the resolution context an assertion needs: the scenario's working directory (for file paths and snapshot normalization), the spec file's directory (where committed snapshot files live), and whether snapshots should be written rather than compared.