package fs

import "gotest.tools/v3/fs"

Package fs provides tools for creating temporary files, and testing the contents and structure of a directory.

Index

Examples

Functions

func Apply 

func Apply(t assert.TestingT, path Path, ops ...PathOp)

Apply the PathOps to the File

Example

Add a file to an existing directory

Code:play  

package main

import (
	"testing"

	"gotest.tools/v3/fs"
)

var t = &testing.T{}

func main() {
	dir := fs.NewDir(t, "test-name")
	defer dir.Remove()

	fs.Apply(t, dir, fs.WithFile("file1", "content\n"))
}

func Equal 

func Equal(path string, expected Manifest) cmp.Comparison

Equal compares a directory to the expected structured described by a manifest and returns success if they match. If they do not match the failure message will contain all the differences between the directory structure and the expected structure defined by the Manifest.

Equal is a cmp.Comparison which can be used with gotest.tools/v3/assert.Assert.

Example

Test that a directory contains the expected files, and all the files have the expected properties.

Code:play  

package main

import (
	"testing"

	"gotest.tools/v3/assert"
	"gotest.tools/v3/fs"
	"gotest.tools/v3/golden"
)

var t = &testing.T{}

func main() {
	path := operationWhichCreatesFiles()
	expected := fs.Expected(t,
		fs.WithFile("one", "",
			fs.WithBytes(golden.Get(t, "one.golden")),
			fs.WithMode(0600)),
		fs.WithDir("data",
			fs.WithFile("config", "", fs.MatchAnyFileContent)))

	assert.Assert(t, fs.Equal(path, expected))
}

func operationWhichCreatesFiles() string {
	return "example-path"
}

func MatchAnyFileContent 

func MatchAnyFileContent(path Path) error

MatchAnyFileContent is a PathOp that updates a Manifest so that the file at path may contain any content.

func MatchAnyFileMode 

func MatchAnyFileMode(path Path) error

MatchAnyFileMode is a PathOp that updates a Manifest so that the resource at path will match any file mode.

func MatchContentIgnoreCarriageReturn 

func MatchContentIgnoreCarriageReturn(path Path) error

MatchContentIgnoreCarriageReturn is a PathOp that ignores cariage return discrepancies.

func MatchExtraFiles 

func MatchExtraFiles(path Path) error

MatchExtraFiles is a PathOp that updates a Manifest to allow a directory to contain unspecified files.

Types

type CompareResult 

type CompareResult interface {
	Success() bool
	FailureMessage() string
}

CompareResult is the result of comparison.

See gotest.tools/v3/assert/cmp.StringResult for a convenient implementation of this interface.

type Dir 

type Dir struct {
	// contains filtered or unexported fields
}

Dir is a temporary directory

func DirFromPath 

func DirFromPath(t assert.TestingT, path string, ops ...PathOp) *Dir

DirFromPath returns a Dir for a path that already exists. No directory is created. Unlike NewDir the directory will not be removed automatically when the test exits, it is the callers responsibly to remove the directory. DirFromPath can be used with Apply to modify an existing directory.

If the path does not already exist, use NewDir instead.

func NewDir 

func NewDir(t assert.TestingT, prefix string, ops ...PathOp) *Dir

NewDir returns a new temporary directory using prefix as part of the directory name. The PathOps are applied before returning the Dir.

When used with Go 1.14+ the directory will be automatically removed when the test ends, unless the TEST_NOCLEANUP env var is set to true.

Example

Create a temporary directory which contains a single file

Code:play  

package main

import (
	"os"
	"testing"

	"gotest.tools/v3/assert"
	"gotest.tools/v3/assert/cmp"
	"gotest.tools/v3/fs"
)

var t = &testing.T{}

func main() {
	dir := fs.NewDir(t, "test-name", fs.WithFile("file1", "content\n"))
	defer dir.Remove()

	files, err := os.ReadDir(dir.Path())
	assert.NilError(t, err)
	assert.Assert(t, cmp.Len(files, 0))
}

func (*Dir) Join 

func (d *Dir) Join(parts ...string) string

Join returns a new path with this directory as the base of the path

func (*Dir) Path 

func (d *Dir) Path() string

Path returns the full path to the directory

func (*Dir) Remove 

func (d *Dir) Remove()

Remove the directory

type File 

type File struct {
	// contains filtered or unexported fields
}

File is a temporary file on the filesystem

func NewFile 

func NewFile(t assert.TestingT, prefix string, ops ...PathOp) *File

NewFile creates a new file in a temporary directory using prefix as part of the filename. The PathOps are applied to the before returning the File.

When used with Go 1.14+ the file will be automatically removed when the test ends, unless the TEST_NOCLEANUP env var is set to true.

Example

Create a new file with some content

Code:play  

package main

import (
	"os"
	"testing"

	"gotest.tools/v3/assert"
	"gotest.tools/v3/fs"
)

var t = &testing.T{}

func main() {
	file := fs.NewFile(t, "test-name", fs.WithContent("content\n"), fs.AsUser(0, 0))
	defer file.Remove()

	content, err := os.ReadFile(file.Path())
	assert.NilError(t, err)
	assert.Equal(t, "content\n", content)
}

func (*File) Path 

func (f *File) Path() string

Path returns the full path to the file

func (*File) Remove 

func (f *File) Remove()

Remove the file

type Manifest 

type Manifest struct {
	// contains filtered or unexported fields
}

Manifest stores the expected structure and properties of files and directories in a filesystem.

func Expected 

func Expected(t assert.TestingT, ops ...PathOp) Manifest

Expected returns a Manifest with a directory structured created by ops. The PathOp operations are applied to the manifest as expectations of the filesystem structure and properties.

func ManifestFromDir 

func ManifestFromDir(t assert.TestingT, path string) Manifest

ManifestFromDir creates a Manifest by reading the directory at path. The manifest stores the structure and properties of files in the directory. ManifestFromDir can be used with Equal to compare two directories.

type Path 

type Path interface {
	Path() string
	Remove()
}

Path objects return their filesystem path. Path may be implemented by a real filesystem object (such as File and Dir) or by a type which updates entries in a Manifest.

type PathOp 

type PathOp func(path Path) error

PathOp is a function which accepts a Path and performs an operation on that path. When called with real filesystem objects (File or Dir) a PathOp modifies the filesystem at the path. When used with a Manifest object a PathOp updates the manifest to expect a value.

func AsUser 

func AsUser(uid, gid int) PathOp

AsUser changes ownership of the file system object at Path

func FromDir 

func FromDir(source string) PathOp

FromDir copies the directory tree from the source path into the new Dir

func MatchFileContent 

func MatchFileContent(f func([]byte) CompareResult) PathOp

MatchFileContent is a PathOp that updates a Manifest to use the provided function to determine if a file's content matches the expectation.

func MatchFilesWithGlob 

func MatchFilesWithGlob(glob string, ops ...PathOp) PathOp

MatchFilesWithGlob is a PathOp that updates a Manifest to match files using glob pattern, and check them using the ops.

func WithBytes 

func WithBytes(raw []byte) PathOp

WithBytes write bytes to a file at Path

func WithContent 

func WithContent(content string) PathOp

WithContent writes content to a file at Path

func WithDir 

func WithDir(name string, ops ...PathOp) PathOp

WithDir creates a subdirectory in the directory at path. Additional PathOp can be used to modify the subdirectory

Example

Create a directory and subdirectory with files

Code:play  

package main

import (
	"os"
	"testing"

	"gotest.tools/v3/fs"
)

var t = &testing.T{}

func main() {
	dir := fs.NewDir(t, "test-name",
		fs.WithDir("subdir",
			fs.WithMode(os.FileMode(0700)),
			fs.WithFile("file1", "content\n")),
	)
	defer dir.Remove()
}

func WithFile 

func WithFile(filename, content string, ops ...PathOp) PathOp

WithFile creates a file in the directory at path with content

func WithFiles 

func WithFiles(files map[string]string) PathOp

WithFiles creates all the files in the directory at path with their content 

func WithHardlink(path, target string) PathOp

WithHardlink creates a link in the directory which links to target. Target must be a path relative to the directory.

Note: the argument order is the inverse of os.Link to be consistent with the other functions in this package.

func WithMode 

func WithMode(mode os.FileMode) PathOp

WithMode sets the file mode on the directory or file at Path

func WithReaderContent 

func WithReaderContent(r io.Reader) PathOp

WithReaderContent copies the reader contents to the file at Path 

func WithSymlink(path, target string) PathOp

WithSymlink creates a symlink in the directory which links to target. Target must be a path relative to the directory.

Note: the argument order is the inverse of os.Symlink to be consistent with the other functions in this package.

func WithTimestamps 

func WithTimestamps(atime, mtime time.Time) PathOp

WithTimestamps sets the access and modification times of the file system object at path.

Source Files

file.go manifest.go manifest_unix.go ops.go path.go report.go

Version
v3.5.2 (latest)
Published
Sep 5, 2024
Platform
linux/amd64
Imports
14 packages
Last checked
2 weeks ago –

Tools for package owners.