testcase

Documentation

Overview

Package testcase is the pure-data foundation for this module's canonical test-case corpus: a typed, generic Case/Corpus model with closed-set classification and provenance metadata, a pure YAML loader, and pure validators. It carries NO testing dependency.

The testing-side helpers (which take *testing.T) live in the sibling subpackage github.com/peasant-labs/schema/testcase/assert. Splitting them out keeps this data/leaf package free of the testing import, mirroring the isolation the module already applies to its *testing.T corpus runners (a helper that needs testing is kept in a dedicated file, consumed only by test packages, so production code never pulls testing). Here that isolation is promoted from a file boundary to a package boundary: testcase is pure data, testcase/assert is the testing seam.

This package is the module's canonical standard for a case corpus. The idiom:

• author a table of {input, expected} rows as a YAML file in the Corpus schema, each case naming its Classification (must-pass or must-fail), its Provenance (source category plus a concrete ref), and the Mutation under test;
• load and boundary-validate it with LoadCorpus[I, E];
• use Corpus.Validate directly for a corpus assembled programmatically;
• guard coverage: assert.RequireMin for a growable floor, or an exact "len == N" control (catching a drop or a stray add) plus a lean value-based coverage assertion (catching a count-preserving swap that drops a real case and adds a filler, which an exact-count check cannot detect) when migrating a fixed corpus;
• drive the system under test over each case and assert its result against the case's Expected and Classification.

New case corpora should adopt this shape. The version_kind and parse_tag grammar corpora under internal/release are a worked migration onto it. A feature whose fixtures split into heterogeneous behavioral arms uses the segmented convention: a typed struct of named per-arm Corpus fields, each guarded by assert.RequireMin plus assert.RequireValid (see TESTING.md).

Index

• Variables
• type Case
  • func (c Case[I, E]) Validate() error
• type Classification
  • func (c Classification) IsValid() bool
  • func (c Classification) String() string
• type Corpus
  • func LoadCorpus[I any, E any](data []byte) (Corpus[I, E], error)
  • func (c Corpus[I, E]) CheckMin(n int) error
  • func (c Corpus[I, E]) Validate() error
• type Mutation
• type Provenance
• type ProvenanceSource
  • func (s ProvenanceSource) IsValid() bool
  • func (s ProvenanceSource) String() string

Variables

var AllClassifications = []Classification{MustPass, MustFail}

AllClassifications is the canonical ordered closed set used by generators and boundary validators.

var AllProvenanceSources = []ProvenanceSource{
	SourceRequirement,
	SourceBug,
	SourceEnum,
	SourceBoundary,
	SourceManual,
}

AllProvenanceSources is the canonical ordered closed set used by generators and boundary validators.

Types

type Case

type Case[I any, E any] struct {
	Name           string         `json:"name" yaml:"name"`
	Input          I              `json:"input" yaml:"input"`
	Expected       E              `json:"expected" yaml:"expected"`
	Classification Classification `json:"classification" yaml:"classification"`
	Provenance     Provenance     `json:"provenance" yaml:"provenance"`
	Mutation       Mutation       `json:"mutation" yaml:"mutation"`
}

Case is one generic test case: a named input with its expected output, a pass/fail classification, and the provenance + mutation metadata that keep the corpus traceable and non-vacuous. I is the input type, E the expected-output type; both are decoded from YAML by the caller-chosen instantiation.

func (Case[I, E]) Validate

func (c Case[I, E]) Validate() error

Validate reports the first way a case is under-populated. Every case must carry an in-set classification, a valid provenance source, a non-empty provenance ref (why it exists), and a non-empty mutation description (what it changes). An empty ref or description is treated as a vacuous case and rejected.

type Classification

type Classification string

Classification is the closed set of a case's expectation against the system under test: an input the SUT must accept, or one it must reject.

const (
	// MustPass marks a valid input the system under test must accept.
	MustPass Classification = "must-pass"
	// MustFail marks an invalid input the system under test must reject.
	MustFail Classification = "must-fail"
)

func (Classification) IsValid

func (c Classification) IsValid() bool

IsValid reports whether the classification is one of the known members.

func (Classification) String

func (c Classification) String() string

type Corpus

type Corpus[I any, E any] struct {
	Cases []Case[I, E] `json:"cases" yaml:"cases"`
}

Corpus is an ordered collection of cases sharing an input/expected type.

func LoadCorpus

func LoadCorpus[I any, E any](data []byte) (Corpus[I, E], error)

LoadCorpus parses and validates a YAML corpus document into a typed Corpus. It is pure: it returns an error rather than failing a test, mirroring the module's production fixture loaders so this package stays free of the testing dependency. Programmatically assembled corpora can call Corpus.Validate directly.

func (Corpus[I, E]) CheckMin

func (c Corpus[I, E]) CheckMin(n int) error

CheckMin is the pure minimum-size meta-guard: it returns an error when the corpus holds fewer than n cases, and nil otherwise. It is a floor (len >= n), not an exact-count guard, so a corpus may grow without tripping it.

It is exported (rather than an unexported helper) because the testing seam assert.RequireMin, in the sibling testcase/assert package, wraps it: keeping the size check here as one pure, package-crossable function means the loud *testing.T wrapper and its own negative-control test share a single source of truth instead of re-deriving the floor.

func (Corpus[I, E]) Validate

func (c Corpus[I, E]) Validate() error

Validate runs Case.Validate over every case, returning the first failure with the offending case's index for locality.

type Mutation

type Mutation struct {
	Description string `json:"description" yaml:"description"`
}

Mutation records how a case was derived: the single change under test. For a must-fail case it is the mutation that makes a valid input invalid, so a negative case is never vacuous; for a must-pass case it names what the case exercises.

type Provenance

type Provenance struct {
	Source ProvenanceSource `json:"source" yaml:"source"`
	Ref    string           `json:"ref" yaml:"ref"`
}

Provenance records why a case exists: its source category plus a concrete, non-empty reference (a requirement id, a bug link, an enum name, and so on).

type ProvenanceSource

type ProvenanceSource string

ProvenanceSource is the closed set of why a case earns a place in the corpus: the category of evidence it came from.

const (
	// SourceRequirement: the case pins a stated requirement or spec clause.
	SourceRequirement ProvenanceSource = "requirement"
	// SourceBug: the case is a regression captured from a real defect.
	SourceBug ProvenanceSource = "bug"
	// SourceEnum: the case is generated from a closed enum's members.
	SourceEnum ProvenanceSource = "enum"
	// SourceBoundary: the case probes an edge of an allowed range or format.
	SourceBoundary ProvenanceSource = "boundary"
	// SourceManual: the case was authored by hand for a reason recorded in Ref.
	SourceManual ProvenanceSource = "manual"
)

func (ProvenanceSource) IsValid

func (s ProvenanceSource) IsValid() bool

IsValid reports whether the provenance source is one of the known members.

func (ProvenanceSource) String

func (s ProvenanceSource) String() string