tdata

README

tdata - go testing data utilities

A collection of utilities for working with go package unit testing data files.

There are two main interfaces provided by this package. The first is TestData which makes working with testdata directories trivial. The second is TempData which makes working with temporary directories more convenient than using the standard os functions.

Installation

> go get github.com/go-corelibs/tdata@latest

Examples

TestData

var (
    // construct a new instance for accessing the `testdata` top-level path
    // this can be within functions or as a global shared instance
    td = tdata.New()
)

func TestSomeThing(t *testing.T) {
    contents := td.F("filename.txt")
    if SomeThing() == contents {
        t.Log("SomeThing is correct")
    } else {
        t.Error("SomeThing is not correct")
    }
}

TempData

func TestSomeThing(t *testing.T) {
    tmpd, err := tdata.NewTempData("", "prefix-*.d")
    if err != nil {
        t.Fatalf("error creating TempData: %v", err)
    }
    defer tmpd.Destroy() // destroy the temporary directory when done
    
    // do stuff with tmpd.Path() or tmpd.Join()
}

Go-CoreLibs

Go-CoreLibs is a repository of shared code between the Go-Curses and Go-Enjin projects.

License

Copyright 2024 The Go-CoreLibs Authors

Licensed under the Apache License, Version 2.0 (the "License");
you may not use file except in compliance with the License.
You may obtain a copy of the license at

 http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Documentation

Overview

Package tdata provides simple unit testing utilities

Index

• Variables
• func TempFile(dir, pattern string) (filename string)
• type TData
• type TempData
  • func NewTempData(dir, pattern string) (td TempData, err error)
• type TestCheck
  • func NewTestCheck[V comparable](condition bool, arguments ...V) TestCheck[V]
• type TestData
  • func New() TestData
  • func NewNamed(custom string) TestData

Variables

var (
	ErrNotFound      = errors.New("directory not found")
	ErrRuntimeCaller = errors.New("runtime.Caller not ok")
)

var (
	// DefaultTestData is the default name of the top-level package directory used
	// for storing unit test data files, "testdata" by default
	DefaultTestData = "testdata"
)

Functions

func TempFile

func TempFile(dir, pattern string) (filename string)

TempFile is a convenience wrapper around os.CreateTemp. It is the caller's responsibility to remove any temporary files made with TempFile when done

Note: will return an empty string if os.CreateTemp returns an error

Types

type TData

type TData interface {
	// Path returns the absolute path to this instance's directory
	Path() (path string)
	// Join is a convenience wrapper around Path and filepath.Join
	Join(names ...string) (joined string)
	// E reports whether the given file exists (as a file or a directory)
	E(filename string) (exists bool)
	// F reads the given file and returns the contents
	F(filename string) (contents string)
	// L lists files and directories within the dirname given
	L(dirname string) (found []string)
	// LD lists directories within the dirname given
	LD(dirname string) (found []string)
	// LF lists files within the dirname given
	LF(dirname string) (found []string)
	// LA lists files and directories, recursively
	LA(dirname string) (found []string)
	// LAF lists files, recursively
	LAF(dirname string) (found []string)
	// LAD lists directories, recursively
	LAD(dirname string) (found []string)
	// LH is the same as L except including hidden files
	LH(dirname string) (found []string)
	// LAH is the same as LA except including hidden files
	LAH(dirname string) (found []string)
	// LAFH is the same as LAF except including hidden files
	LAFH(dirname string) (found []string)
	// LADH is the same as LAD except including hidden files
	LADH(dirname string) (found []string)
}

TData is the filesystem interface common to both TestData and TempData implementations

type TempData

type TempData interface {
	// Create will make the temporary directory associated with this TempData
	// instance if it does not exist. Create does nothing if the directory
	// exists. Create is only useful after a call to Destroy because the
	// temporary directory for this instance has already been created during
	// the call to NewTempData
	Create() (err error)
	// Destroy attempts to correct any file permissions and removes the
	// entire temporary directory associated with this TempData instance
	Destroy() (err error)

	TData
}

TempData is an interface for creating and interacting with temporary directories for unit testing purposes

func NewTempData

func NewTempData(dir, pattern string) (td TempData, err error)

NewTempData constructs a new TempData instance using the given `dir` and `pattern` arguments in a call to os.MkdirTemp

type TestCheck

type TestCheck[V comparable] interface {
	// Check returns conditional given during TestCheck construction
	Check() (ok bool)
	// List returns the argument list given during TestCheck construction
	List() (argv []V)
	// Present returns true if the conditional is true and the value
	// given is also present in the constructor arguments list
	Present(value V) (ok bool)
	// NotPresent returns true if the conditional is true and the value
	// given is not present in the constructor arguments list
	NotPresent(value V) (ok bool)
}

TestCheck is a generic interface for working with lists of comparable values during unit testing or other conditional branching procedures

Example:

if the original code does something like this:

slice := []string{"one", "two"}
check := len(slice) > 0
lookup := make(map[string]struct{})
for _, item := range slice {
  lookup[item] = struct{}{}
}

and then further on, the above is used in cases like:

if _, present := lookup[item]; check && !present {
  ... do stuff ...
}

then migrating to TestCheck would look like the following:

slice := []string{"one", "two"}
tc := NewTestCheck(len(slice) > 0, slice...)
... further on ...
if tc.NotPresent(item) {
  ... do stuff ...
}

func NewTestCheck

func NewTestCheck[V comparable](condition bool, arguments ...V) TestCheck[V]

NewTestCheck constructs a new TestCheck instance of any comparable type

type TestData

type TestData interface {
	// Name returns the name of the testdata directory
	Name() (name string)

	TData
}

TestData is an interface for interacting with a project's top-level unit testing files directory

func New

func New() TestData

New is a convenience wrapper around NewNamed and the DefaultTestData directory name

func NewNamed

func NewNamed(custom string) TestData

NewNamed constructs a new TestData instance using the directory of the runtime.Caller filename to find the correct package source directory, finds the `go.mod` file indicating the top-level of the Go package and then looks for the specified directory there. NewNamed will panic if the runtime.Caller response is not ok or if the test data directory is not found