testutil

README

This repository contains test utilities used by grailbio.

• s3test: In-memory s3iface.S3API implementation.
• assert: gtest/gmock-style test helper.
• expect: gtest/gmock-style test helper.
• h: gmock-style test helper.

Documentation

Overview

Package testutil provides functionality commonly used by tests.

Index

• func Caller(depth int) string
• func CompareFile(t testing.TB, contents string, golden string, strip func(string) string)
• func CompareFiles(t testing.TB, a, golden string, strip func(string) string)
• func CreateDirectoryTree(t Testing, parent string, depth, fanout, files int)
• func GetFilePath(relativePath string) string
• func GetTmpDir() string
• func GetTmpPath() string
• func GoExecutable(t testing.TB, path string) string
• func GoExecutableEnv(t testing.TB, path string, env []string) string
• func IsBazel() bool
• func ListRecursively(t Testing, parent string) (dirs []string, files []string)
• func NoCleanupOnError(t testing.TB, cleanup func(), args ...interface{})
• func TempDir(t Testing, dir, prefix string) (name string, cleanup func())
• type ByteContent
  • func (bc *ByteContent) Checksum() string
  • func (bc *ByteContent) ReadAt(p []byte, off int64) (int, error)
  • func (bc *ByteContent) Size() int64
  • func (bc *ByteContent) WriteAt(p []byte, off int64) (int, error)
• type ContentAt
• type FakeContentAt
  • func (fca *FakeContentAt) Checksum() string
  • func (fca *FakeContentAt) Read(p []byte) (int, error)
  • func (fca *FakeContentAt) ReadAt(p []byte, off int64) (int, error)
  • func (fca *FakeContentAt) Seek(offset int64, whence int) (int64, error)
  • func (fca *FakeContentAt) Size() int64
  • func (fca *FakeContentAt) Write(p []byte) (int, error)
  • func (fca *FakeContentAt) WriteAt(p []byte, off int64) (int, error)
• type MockTB
  • func (m *MockTB) FailNow()
  • func (m *MockTB) Fatalf(format string, args ...interface{})
  • func (m *MockTB) Logf(format string, args ...interface{})
• type Testing

Functions

func Caller

func Caller(depth int) string

Caller returns a string of the form <file>:<line> for the caller at the specified depth.

func CompareFile

func CompareFile(t testing.TB, contents string, golden string, strip func(string) string)

CompareFile compares the supplied contents against the contents of the specified file and if they differ calls t.Errorf and displays a diff -u of them. If specified the strip function can be used to cleanup the contents to be compared to remove things such as dates or other spurious information that's not relevant to the comparison.

func CompareFiles

func CompareFiles(t testing.TB, a, golden string, strip func(string) string)

CompareFiles compares 2 files in the same manner as CompareFile.

func CreateDirectoryTree

func CreateDirectoryTree(t Testing, parent string, depth, fanout, files int)

CreateDirectoryTree creates a directory tree for use in tests. Parent specifies the root directory, depth the number of directory levels and fanout the number of directories at each level; files is the number of files to create at each level. Directories are named d0..n. Files are named f0..n and the contents of each file are its own name.

func GetFilePath

func GetFilePath(relativePath string) string

GetFilePath detects if we're running under "bazel test". If so, it builds a path to the test data file based on Bazel environment variables. Otherwise, it tries to build a path relative to $GRAIL. If that fails, it returns the input path unchanged.

relativePath will need to be prefixed with a Bazel workspace designation if the paths go across workspaces.

func GetTmpDir

func GetTmpDir() string

GetTmpDir will retrieve/generate a test-specific directory appropriate for writing scratch data. When running under Bazel, Bazel should clean up the directory. However, when running under vanilla Go tooling, it will not be cleaned up. Thus, it's probably best for a test to clean up any test directories itself.

func GetTmpPath

func GetTmpPath() string

GetTmpPath returns a random file inside of the appropriate scratch directory. The path is neither created nor cleaned up -- clients are expected to use do both.

func GoExecutable

func GoExecutable(t testing.TB, path string) string

GoExecutable returns the Go executable for "path", or builds the executable and returns its path. The latter happens when the caller is not running under Bazel. "path" must start with "//go/src/grail.com/". For example, "//go/src/grail.com/cmd/bio-metrics/bio-metrics".

func GoExecutableEnv

func GoExecutableEnv(t testing.TB, path string, env []string) string

GoExecutableEnv is like GoExecutable but allows environment variables to be specified.

func IsBazel

func IsBazel() bool

IsBazel checks if the current process is started by "bazel test".

func ListRecursively

func ListRecursively(t Testing, parent string) (dirs []string, files []string)

ListRecursively recursively lists the files and directories starting at parent.

func NoCleanupOnError

func NoCleanupOnError(t testing.TB, cleanup func(), args ...interface{})

NoCleanupOnError avoids calling the supplied cleanup function when a test has failed or paniced. The Log function is called with args when the test has failed and is typically used to log the location of the state that would have been removed by the cleanup function. Common usage would be:

tempdir, cleanup := testutil.TempDir(t, "", "scandb-state-") defer testutil.NoCleanupOnError(t, cleanup, "tempdir:", tempdir)

func TempDir

func TempDir(t Testing, dir, prefix string) (name string, cleanup func())

TempDir is like ioutil.TempDir but intended for use from within tests. In particular, it will t.Fatal if it fails and returns a function that can be defer'ed by the caller to remove the newly created directory.

Types

type ByteContent

type ByteContent struct {
	Data []byte
}

ByteContent stores data for content storage tests.

func (*ByteContent) Checksum

func (bc *ByteContent) Checksum() string

Checksum implements ContentAt.

func (*ByteContent) ReadAt

func (bc *ByteContent) ReadAt(p []byte, off int64) (int, error)

ReadAt reads from the specified offset

func (*ByteContent) Size

func (bc *ByteContent) Size() int64

Size returns the size of the contents

func (*ByteContent) WriteAt

func (bc *ByteContent) WriteAt(p []byte, off int64) (int, error)

WriteAt writes at the specified offset

type ContentAt

type ContentAt interface {
	io.ReaderAt
	io.WriterAt

	// Size returns the total byte count of the contents.
	Size() int64

	// Checksum returns the checksum of the contents.  It is typically an MD5 hex
	// string, following the S3 convention.
	Checksum() string
}

ContentAt allows users of test clients to implement their own content storage. This is useful when mocking very large files.

type FakeContentAt

type FakeContentAt struct {
	T interface {
		Fatal(...interface{})
	}
	SizeInBytes int64
	Current     int64
	FailureRate float64
}

FakeContentAt implements io.[Reader|ReaderAt|Seeker|Writer] using a virtual file with a predictable pattern. The Read* interfaces will data for the slice based on the virtual file containing a repeating pattern containing the lowercase alphabet. The WriteAt function will verify that the pattern is maintained. This enables unittests with large files without paying the performance penalty of disk writes.

func (*FakeContentAt) Checksum

func (fca *FakeContentAt) Checksum() string

Checksum implements ContentAt.

func (*FakeContentAt) Read

func (fca *FakeContentAt) Read(p []byte) (int, error)

Read implements the io.Reader.

func (*FakeContentAt) ReadAt

func (fca *FakeContentAt) ReadAt(p []byte, off int64) (int, error)

ReadAt implements io.ReaderAt.

func (*FakeContentAt) Seek

func (fca *FakeContentAt) Seek(offset int64, whence int) (int64, error)

Seek implements io.Seeker.

func (*FakeContentAt) Size

func (fca *FakeContentAt) Size() int64

Size returns the size of the fake content.

func (*FakeContentAt) Write

func (fca *FakeContentAt) Write(p []byte) (int, error)

Write implements io.Writer.

func (*FakeContentAt) WriteAt

func (fca *FakeContentAt) WriteAt(p []byte, off int64) (int, error)

WriteAt implements io.WriterAt.

type MockTB

type MockTB struct {
	Failed bool
	Result string
}

MockTB is a mock implementation of gosh.TB. FailNow and Fatalf will set Failed to true. Logf and Fatalf write their log message to Result. MockTB is intended for building negatived tests.

func (*MockTB) FailNow

func (m *MockTB) FailNow()

FailNow implements TB.

func (*MockTB) Fatalf

func (m *MockTB) Fatalf(format string, args ...interface{})

Fatalf implements TB.

func (*MockTB) Logf

func (m *MockTB) Logf(format string, args ...interface{})

Logf implements TB.

type Testing

type Testing interface {
	FailNow()
	Logf(format string, args ...interface{})
	Fatalf(format string, args ...interface{})
}

Testing is a subset of testing.TB that allows an instance of testing.T to be passed without having to import testing into this non-test package.