Documentation
¶
Index ¶
- Constants
- func CheckSnapshotUpdateFlags(t *testing.T)
- func CompareSnapshotResult(t *testing.T, tc *SnapshotCase, actual SnapshotResult, updating bool) bool
- func ShouldUpdateSnapshotFile(path string) bool
- func WriteSnapshotFile(path string, cases []SnapshotCase) error
- type ErrorOrExit
- type SnapshotCase
- type SnapshotResult
- type TestParams
- type Tolerance
Constants ¶
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
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
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
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.