txtartest

Documentation

Index

• func Context() *cue.Context
• func ForEachSchema(t *LineageTest, lin thema.Lineage, f func(*LineageTest, thema.Schema))
• func Load(a *txtar.Archive, dir string, args ...string) ([]*build.Instance, error)
• func Runtime() *thema.Runtime
• type LineageSuite
  • func (x *LineageSuite) Run(t *testing.T, f func(tc *LineageTest))
• type LineageTest
  • func (t *LineageTest) BindLineage(rt *thema.Runtime) thema.Lineage
  • func (t *LineageTest) Bool(key string) bool
  • func (t *LineageTest) HasTag(key string) bool
  • func (t *LineageTest) Rel(filename string) string
  • func (t *LineageTest) Value(key string) (value string, ok bool)
  • func (t *LineageTest) Write(b []byte) (n int, err error)
  • func (t *LineageTest) WriteErrors(err error, name string)
  • func (t *LineageTest) WriteFile(f *ast.File, name string)
  • func (t *LineageTest) WriteFileOrErr(name string) func(*ast.File, error)
  • func (t *LineageTest) WriteFileOrErrBytes(name string) func([]byte, error)
  • func (t *LineageTest) Writer(name string) io.Writer

Functions

func Context

func Context() *cue.Context

Context returns the central context used by default for testing.

func ForEachSchema

func ForEachSchema(t *LineageTest, lin thema.Lineage, f func(*LineageTest, thema.Schema))

ForEachSchema iterates over the provided lineage's schemas, calling the provided test func for each one. The call is made from within a new Go subtest, named by the schema version.

func Load

func Load(a *txtar.Archive, dir string, args ...string) ([]*build.Instance, error)

Load loads the instance at the logical root of a txtar file. Relative files in the archive are given an absolute location by prefixing it with dir.

func Runtime

func Runtime() *thema.Runtime

Runtime returns the central runtime used by default for testing.

Types

type LineageSuite

type LineageSuite struct {
	// Run LineageSuite on this directory.
	Root string

	// Name is a unique name for this test. The golden file for this test is
	// derived from the out/<name> file in the .txtar file.
	//
	// TODO: by default derive from the current base directory name.
	Name string

	// Skip is a map of tests to skip; the key is the test name; the value is the
	// skip message.
	Skip map[string]string

	// ToDo is a map of tests that should be skipped now, but should be fixed.
	ToDo map[string]string

	// IncludeExemplars specifies whether the standard Thema lineage exemplars
	// should be included as inputs to the executed test.
	//
	// If true, the Thema exemplars will be loaded and test results will be
	// placed within Root with the naming pattern exemplar_<name>.txtar.
	IncludeExemplars bool
}

A LineageSuite represents a suite of tests run against a single thema.Lineage that exercise a particular set of related behaviors that operate on lineage. Inputs and outputs for the test suite are collected within a single .txtar file. See the LineageTest documentation for more details.

func (*LineageSuite) Run

func (x *LineageSuite) Run(t *testing.T, f func(tc *LineageTest))

Run runs tests defined in txtar files in x.Root or its subdirectories.

The function f is called for each such txtar file. See the LineageTest documentation for more details.

type LineageTest

type LineageTest struct {
	// Allow LineageTest to be used as a T.
	*testing.T

	Archive *txtar.Archive

	// The absolute path of the current test directory.
	Dir string

	// AllowFilesetDivergence indicates whether a correctness criteria for the
	// test is that set of files in the Archive should be exactly equal to
	// the set in outFiles.
	//
	// If true, divergent filesets are not considered a failure criteria, and
	// updating golden files will not remove files from the archive.
	//
	// If true, divergent filesets are considered a failure criteria, and
	// updating golden files will remove files from the archive.
	AllowFilesetDivergence bool
	// contains filtered or unexported fields
}

A LineageTest represents a single test based on a .txtar file.

A LineageTest embeds *testing.T and should be used to report errors.

Entries within the txtar file define CUE files containing lineage inputs, and expected output (or "golden") files (names starting with "out/\(testname)"). The "main" golden file is "out/\(testname)" itself, used when LineageTest is used directly as an io.Writer and with LineageTest.WriteFile.

When the test function has returned, output written with LineageTest.Write, [Test.Writer] and friends is checked against the expected output files.

A txtar file can define test-specific tags and values in the comment section. These are available via the [Test.HasTag] and LineageTest.Value methods. The #skip tag causes a LineageTest to be skipped. The #noformat tag causes the $THEMA_FORMAT_TXTAR value to be ignored.

If the output differs and $THEMA_UPDATE_GOLDEN is non-empty, the txtar file will be updated and written to disk with the actual output data replacing the out files.

If $THEMA_FORMAT_TXTAR is non-empty, any CUE files in the txtar file will be updated to be properly formatted, unless the #noformat tag is present.

func (*LineageTest) BindLineage

func (t *LineageTest) BindLineage(rt *thema.Runtime) thema.Lineage

BindLineage attempts to bind a lineage from the root instance in the txtar. By default, it will assume the entire instance is intended to be a lineage. However, if a #lineagePath key exists with a value, that path will be used instead.

func (*LineageTest) Bool

func (t *LineageTest) Bool(key string) bool

Bool searches for a line starting with #key: value in the comment and reports whether the key exists and its value is true.

func (*LineageTest) HasTag

func (t *LineageTest) HasTag(key string) bool

HasTag reports whether the tag with the given key is defined for the current test. A tag x is defined by a line in the comment section of the txtar file like:

#x

func (*LineageTest) Rel

func (t *LineageTest) Rel(filename string) string

Rel converts filename to a normalized form so that it will given the same output across different runs and OSes.

func (*LineageTest) Value

func (t *LineageTest) Value(key string) (value string, ok bool)

Value returns the value for the given key for this test and reports whether it was defined.

A value is defined by a line in the comment section of the txtar file like:

#key: value

White space is trimmed from the value before returning.

func (*LineageTest) Write

func (t *LineageTest) Write(b []byte) (n int, err error)

Write implements io.Writer by writing to the output for the test, which will be tested against the main golden file.

func (*LineageTest) WriteErrors

func (t *LineageTest) WriteErrors(err error, name string)

WriteErrors writes the full list of errors in err to the output with the given name, joined to any active prefixes.

func (*LineageTest) WriteFile

func (t *LineageTest) WriteFile(f *ast.File, name string)

WriteFile formats f and writes it to an output with the provided name, joined to any active prefixes.

func (*LineageTest) WriteFileOrErr

func (t *LineageTest) WriteFileOrErr(name string) func(*ast.File, error)

WriteFileOrErr creates a function that will write either a file or an error to the provided output name, joined onto any active prefixes on the LineageTest.

func (*LineageTest) WriteFileOrErrBytes

func (t *LineageTest) WriteFileOrErrBytes(name string) func([]byte, error)

WriteFileOrErrBytes creates a function that will write either a file or an error to the provided output name, joined onto any active prefixes on the LineageTest.

func (*LineageTest) Writer

func (t *LineageTest) Writer(name string) io.Writer

Writer returns a Writer with the given name. Data written will be checked against the file with name "out/\(testName)/\(name)" in the txtar file. If name is empty, data will be written to the test output and checked against "out/\(testName)".