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
• type TempData
  • func NewTempData(dir, pattern string) (td TempData, err error)
• 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"
)

Types

type TempData

type TempData interface {
	// Path returns the absolute path to the top-level temporary directory
	// associated with this TempData instance
	Path() (abs string)
	// Join is a wrapper around filepath.Join, returning this temporary
	// directory joined with the names given
	Join(names ...string) (joined string)
	// Create will make the temporary directory associated with this TestData
	// 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)
}

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 TestData

type TestData interface {
	// Path returns the absolute path to this instance's testdata 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) within
	// the testdata filesystem
	E(filename string) (exists bool)
	// F reads the given file from the testdata filesystem 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)
}

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