testing

package
v0.11.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 4, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Index

Constants

View Source
const (
	TitleDelimiter       = "### TITLE ###"
	DescriptionDelimiter = "### DESCRIPTION ###"
	SkipDelimiter        = "### SKIP ###"
	InputDelimiter       = "### INPUT ###"
	ArgsDelimiter        = "### ARGS ###"
	RawArgsDelimiter     = "### RAW_ARGS ###"
	TermWidthDelimiter   = "### TERM_WIDTH ###"
	KeysDelimiter        = "### KEYS ###"
	StdoutDelimiter      = "### STDOUT ###"
	StderrDelimiter      = "### STDERR ###"
	FramesDelimiter      = "### FRAMES ###"
	ExitDelimiter        = "### EXIT ###"
)

Variables

This section is empty.

Functions

func CheckSnapshotUpdateFlags added in v0.11.0

func CheckSnapshotUpdateFlags(t *testing.T)

CheckSnapshotUpdateFlags fails fast on common -update misuse. Call once at the top of a snapshot test. The main trap is `-update -run X`: because -update now takes a value, the flag parser swallows `-run` as that value. Catch the flag-shaped target and point the user at the `=` form.

func CompareSnapshotResult added in v0.9.0

func CompareSnapshotResult(t *testing.T, tc *SnapshotCase, actual SnapshotResult, updating bool) bool

CompareSnapshotResult compares actual output against expected. Returns true if the snapshot needs updating. In update mode, it does not fail the test on mismatch. CompareSnapshotResult compares actual output against the expected case and returns whether they differ (i.e. the snapshot needs rewriting). When `updating` is true the diff is suppressed (the caller will rewrite this file); otherwise a mismatch fails the test - so a scoped `-update` still catches regressions in files it isn't rewriting.

func ShouldUpdateSnapshotFile added in v0.11.0

func ShouldUpdateSnapshotFile(path string) bool

ShouldUpdateSnapshotFile reports whether the snapshot file at the given path should be rewritten this run: true under -update-all, or when the path contains any -update substring. Matching on the path means a target like "types/str_lexing" or just "str_lexing" both work, and it's agnostic to each caller's snapshot-directory layout.

func WriteSnapshotFile added in v0.9.0

func WriteSnapshotFile(path string, cases []SnapshotCase) error

WriteSnapshotFile writes test cases back to a .snap file.

Types

type ErrorOrExit

type ErrorOrExit struct {
	// contains filtered or unexported fields
}

type SnapshotCase added in v0.9.0

type SnapshotCase struct {
	Title       string
	Description string // Optional documentation/comments about the test
	Input       string
	Args        []string // Command-line arguments to pass to the script

	// Skip support - if SkipReason is non-empty, the test is skipped
	SkipReason string

	// RawArgs suppresses automatic flag additions (like --color=never).
	// Use ### RAW_ARGS ### instead of ### ARGS ### to enable this.
	RawArgs bool

	// TermWidth overrides terminal width for the test, enabling truncation testing.
	// 0 means not set (default behavior: no width override).
	TermWidth int

	// Keys scripts the keystrokes fed to interactive prompts (pick, etc.), one
	// token per line: a named key ("up", "enter", "ctrl-c", "space", ...) or a
	// "quoted literal" whose runes are typed in order. Authored by hand; preserved
	// verbatim on update.
	Keys []string

	Stdout string
	Stderr string

	// Frames captures the rendered interactive frames (one block per keystroke,
	// plus the initial render and final summary). Regenerated on update like
	// Stdout; empty for non-interactive tests.
	Frames string

	ExitCode int
}

SnapshotCase holds one test case from a snapshot file.

func ParseSnapshotFile added in v0.9.0

func ParseSnapshotFile(path string) ([]SnapshotCase, error)

ParseSnapshotFile reads a .snap file and extracts test cases.

Format:

### TITLE ###
<test name>
### DESCRIPTION ###
<optional documentation, can be multi-line>
### SKIP ###
<optional skip reason - if section present, test is skipped>
### INPUT ###
<code to run>
### ARGS ###         (or ### RAW_ARGS ### to suppress auto --color=never)
<args, one per line> (optional)
### STDOUT ###
<expected stdout> (optional, omit section for empty)
### STDERR ###
<expected stderr> (optional, omit section for empty)
### EXIT ###
<exit code> (optional, defaults to 0)

Multiple test cases can be included by repeating the pattern.

type SnapshotResult added in v0.9.0

type SnapshotResult struct {
	Stdout   string
	Stderr   string
	Frames   string
	ExitCode int
}

SnapshotResult holds the actual output from running a test case.

type TestParams

type TestParams struct {
	// contains filtered or unexported fields
}

func NewTestParams

func NewTestParams(script string, args ...string) *TestParams

func (*TestParams) ConfirmResponder added in v0.11.0

func (tp *TestParams) ConfirmResponder(f func(title, prompt string) (bool, error)) *TestParams

ConfirmResponder drives the shell-confirmation prompt for this run. Returning (false, nil) simulates declining ("n"); a non-nil error simulates an abort (Ctrl-C / Esc).

func (*TestParams) Keys added in v0.11.0

func (tp *TestParams) Keys(keys ...string) *TestParams

Keys scripts keystrokes for interactive prompts (pick, etc.). Each token is a named key ("up", "enter", "ctrl-c", "space", ...) or a "quoted literal" whose runes are typed in order.

func (*TestParams) StdinInput

func (tp *TestParams) StdinInput(stdinInput string) *TestParams

func (*TestParams) TermWidth added in v0.10.0

func (tp *TestParams) TermWidth(width int) *TestParams

type Tolerance added in v0.11.0

type Tolerance struct {
	// Skip bypasses the check entirely. Use for fragments / pseudo-code
	// that can't stand alone.
	Skip bool

	// MaxSeverity allows diagnostics with severity at or below this level
	// (case-insensitive: "hint" | "warning" | "info" | "error"). Empty means
	// no severity-based tolerance.
	//
	// Severity ordering (from rts/check/structs.go): Hint < Warning < Info < Error.
	MaxSeverity string

	// ExpectedCodes is a strict set of RAD codes (e.g. "RAD30001") that
	// MUST appear in the snippet's diagnostics. Any diagnostic with a code
	// outside this set fails (subject to MaxSeverity). Missing expected
	// codes also fail.
	ExpectedCodes []string

	// Reason is mandatory: a human-readable note explaining why this
	// entry exists. Test fails if an entry has Reason == "".
	Reason string
}

Tolerance describes the diagnostics we allow (or require) for a single doc snippet. The default for any snippet not in docSnippetTolerances is "must produce zero diagnostics of any severity".

Snippets are identified by "<relative-path-from-repo-root>#<8-hex-content-hash>" e.g. "docs-web/docs/guide/error-handling.md#a1b2c3d4". The hash changes whenever the snippet body changes, which orphans any matching tolerance entry and forces re-review on the next run.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL