cuetxtar

Documentation

Index

• func Load(a *txtar.Archive, dir string, args ...string) []*build.Instance
• type Test
  • func (t *Test) Bool(key string) bool
  • func (t *Test) HasTag(key string) bool
  • func (t *Test) Instance() *build.Instance
  • func (t *Test) Instances(args ...string) []*build.Instance
  • func (t *Test) RawInstances(args ...string) []*build.Instance
  • func (t *Test) Rel(filename string) string
  • func (t *Test) Value(key string) (value string, ok bool)
  • func (t *Test) Write(b []byte) (n int, err error)
  • func (t *Test) WriteErrors(err errors.Error)
  • func (t *Test) WriteFile(f *ast.File)
  • func (t *Test) Writer(name string) io.Writer
• type TxTarTest
  • func (x *TxTarTest) Run(t *testing.T, f func(tc *Test))

Functions

func Load

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

Load loads the intstances of a txtar file. By default, it only loads files in the root directory. Relative files in the archive are given an absolute location by prefixing it with dir.

Types

type Test

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

	Archive    *txtar.Archive
	LoadConfig load.Config

	// The absolute path of the current test directory.
	Dir string
	// contains filtered or unexported fields
}

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

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

Entries within the txtar file define CUE files (available via the Instances and RawInstances methods) and expected output (or "golden") files (names starting with "out/\(testname)"). The "main" golden file is "out/\(testname)" itself, used when Test is used directly as an io.Writer and with Test.WriteFile.

When the test function has returned, output written with Test.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 Test.Value methods. The #skip tag causes a Test to be skipped. The #noformat tag causes the $CUE_FORMAT_TXTAR value to be ignored.

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

If $CUE_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 (*Test) Bool

func (t *Test) 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 (*Test) HasTag

func (t *Test) 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 (*Test) Instance

func (t *Test) Instance() *build.Instance

Instance returns the single instance representing the root directory in the txtar file.

func (*Test) Instances

func (t *Test) Instances(args ...string) []*build.Instance

Instances returns the valid instances for this .txtar file or skips the test if there is an error loading the instances.

func (*Test) RawInstances

func (t *Test) RawInstances(args ...string) []*build.Instance

RawInstances returns the intstances represented by this .txtar file. The returned instances are not checked for errors.

func (*Test) Rel

func (t *Test) 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 (*Test) Value

func (t *Test) 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 (*Test) Write

func (t *Test) 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 (*Test) WriteErrors

func (t *Test) WriteErrors(err errors.Error)

WriteErrors writes the full list of errors in err to the test output.

func (*Test) WriteFile

func (t *Test) WriteFile(f *ast.File)

WriteFile formats f and writes it to the main output, prefixed by a line of the form:

== name

where name is the base name of f.Filename.

func (*Test) Writer

func (t *Test) 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)".

type TxTarTest

type TxTarTest struct {
	// Run TxTarTest 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

	// Fallback allows the golden tests named by Fallback to pass tests in
	// case the golden file corresponding to Name does not exist.
	// The feature can be used to have two implementations of the same
	// functionality share the same test sets.
	Fallback 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

	// LoadConfig is passed to load.Instances when loading instances.
	// It's copied before doing that and the Dir and Overlay fields are overwritten.
	LoadConfig load.Config
}

A TxTarTest represents a test run that process all CUE tests in the txtar format rooted in a given directory. See the Test documentation for more details.

func (*TxTarTest) Run

func (x *TxTarTest) Run(t *testing.T, f func(tc *Test))

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 Test documentation for more details.