vfs

package module

v5.0.4 Latest Latest Go to latest Published: Mar 31, 2024 License: MIT Imports: 9 Imported by: 16

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/twpayne/go-vfs

Links

Open Source Insights

README ¶

go-vfs

Package vfs provides an abstraction of the os and io packages that is easy to test.

Key features

File system abstraction layer for commonly-used os and io functions from the standard library.
Powerful and easy-to-use declarative testing framework, vfst. You declare the desired state of the filesystem after your code has run, and vfst tests that the filesystem matches that state. For a quick tour of vfst's features, see the examples in the documentation.
Compatibility with github.com/spf13/afero and github.com/src-d/go-billy.

Quick start

vfs provides implementations of the FS interface:

// An FS is an abstraction over commonly-used functions in the os and io
// packages.
type FS interface {
    Chmod(name string, mode fs.FileMode) error
    Chown(name string, uid, git int) error
    Chtimes(name string, atime, mtime time.Time) error
    Create(name string) (*os.File, error)
    Glob(pattern string) ([]string, error)
    Lchown(name string, uid, git int) error
    Link(oldname, newname string) error
    Lstat(name string) (fs.FileInfo, error)
    Mkdir(name string, perm fs.FileMode) error
    Open(name string) (fs.File, error)
    OpenFile(name string, flag int, perm fs.FileMode) (*os.File, error)
    PathSeparator() rune
    RawPath(name string) (string, error)
    ReadDir(dirname string) ([]fs.DirEntry, error)
    ReadFile(filename string) ([]byte, error)
    Readlink(name string) (string, error)
    Remove(name string) error
    RemoveAll(name string) error
    Rename(oldpath, newpath string) error
    Stat(name string) (fs.FileInfo, error)
    Symlink(oldname, newname string) error
    Truncate(name string, size int64) error
    WriteFile(filename string, data []byte, perm fs.FileMode) error
}

To use vfs, you write your code to use the FS interface, and then use vfst to test it.

vfs also provides functions MkdirAll (equivalent to os.MkdirAll), Contains (an improved filepath.HasPrefix), and Walk (equivalent to filepath.Walk) that operate on an FS.

The implementations of FS provided are:

OSFS which calls the underlying os and io functions directly.
PathFS which transforms all paths to provide a poor-man's chroot.
ReadOnlyFS which prevents modification of the underlying FS.
TestFS which assists running tests on a real filesystem but in a temporary directory that is easily cleaned up. It uses OSFS under the hood.

Example usage:

// writeConfigFile is the function we're going to test. It can make arbitrary
// changes to the filesystem through fileSystem.
func writeConfigFile(fileSystem vfs.FS) error {
    return fileSystem.WriteFile("/home/user/app.conf", []byte(`app config`), 0644)
}

// TestWriteConfigFile is our test function.
func TestWriteConfigFile(t *testing.T) {
    // Create and populate an temporary directory with a home directory.
    fileSystem, cleanup, err := vfst.NewTestFS(map[string]any{
        "/home/user/.bashrc": "# contents of user's .bashrc\n",
    })

    // Check that the directory was populated successfully.
    if err != nil {
        t.Fatalf("vfsTest.NewTestFS(_) == _, _, %v, want _, _, <nil>", err)
    }

    // Ensure that the temporary directory is removed.
    defer cleanup()

    // Call the function we want to test.
    if err := writeConfigFile(fileSystem); err != nil {
        t.Error(err)
    }

    // Check properties of the filesystem after our function has modified it.
    vfst.RunTests(t, fileSystem, "app_conf",
        vfst.TestPath("/home/user/app.conf",
            vfst.TestModeIsRegular(),
            vfst.TestModePerm(0644),
            vfst.TestContentsString("app config"),
        ),
    )
}

`github.com/spf13/afero` compatibility

There is a compatibility shim for github.com/spf13/afero in github.com/twpayne/go-vfsafero. This allows you to use vfst to test existing code that uses afero.FS. See the documentation for an example.

`github.com/src-d/go-billy` compatibility

There is a compatibility shim for github.com/src-d/go-billy in github.com/twpayne/go-vfsbilly. This allows you to use vfst to test existing code that uses billy.Filesystem. See the documentation for an example.

Motivation

vfs was inspired by github.com/spf13/afero. So, why not use afero?

afero has several critical bugs in its in-memory mock filesystem implementation MemMapFs, to the point that it is unusable for non-trivial test cases. vfs does not attempt to implement an in-memory mock filesystem, and instead only provides a thin layer around the standard library's os and io packages, and as such should have fewer bugs.
afero does not support creating or reading symbolic links, and its LstatIfPossible interface is clumsy to use as it is not part of the afero.Fs interface. vfs provides out-of-the-box support for symbolic links with all methods in the FS interface.
afero has been effectively abandoned by its author, and a "friendly fork" (github.com/absfs/afero) has not seen much activity. vfs, by providing much less functionality than afero, should be smaller and easier to maintain.

License

MIT

Documentation ¶

Rendered for

Overview ¶

Package vfs provides an abstraction of the os and io packages that is easy to test.

Index ¶

Variables
func Contains(fileSystem Stater, p, prefix string) (bool, error)
func MkdirAll(fileSystem MkdirStater, path string, perm fs.FileMode) error
func Walk(fileSystem LstatReadDirer, path string, walkFn filepath.WalkFunc) error
func WalkSlash(fileSystem LstatReadDirer, path string, walkFn filepath.WalkFunc) error
type EmptyFS
type FS
type LstatReadDirer
type MkdirStater
type PathFS
- func NewPathFS(fileSystem FS, path string) *PathFS
type ReadOnlyFS
- func NewReadOnlyFS(fileSystem FS) *ReadOnlyFS
type Stater

Constants ¶

This section is empty.

Variables ¶

View Source

var OSFS = &osfs{}

OSFS is the FS that calls os and io functions directly.

View Source

var SkipDir = fs.SkipDir

SkipDir is fs.SkipDir.

Functions ¶

func Contains ¶

func Contains(fileSystem Stater, p, prefix string) (bool, error)

Contains returns true if p is reachable by traversing through prefix. prefix must exist, but p may not. It is an expensive but accurate alternative to the deprecated filepath.HasPrefix.

func MkdirAll ¶

func MkdirAll(fileSystem MkdirStater, path string, perm fs.FileMode) error

MkdirAll is equivalent to os.MkdirAll but operates on fileSystem.

func Walk ¶

func Walk(fileSystem LstatReadDirer, path string, walkFn filepath.WalkFunc) error

Walk is the equivalent of filepath.Walk but operates on fileSystem. Entries are returned in lexicographical order.

func WalkSlash ¶

func WalkSlash(fileSystem LstatReadDirer, path string, walkFn filepath.WalkFunc) error

WalkSlash is the equivalent of Walk but all paths are converted to use forward slashes with filepath.ToSlash.

Types ¶

type EmptyFS ¶

type EmptyFS struct{}

An EmptyFS is a VFS that does not contain any files.

func (EmptyFS) Chmod ¶

func (EmptyFS) Chmod(name string, mode fs.FileMode) error

func (EmptyFS) Chown ¶

func (EmptyFS) Chown(name string, uid, git int) error

func (EmptyFS) Chtimes ¶

func (EmptyFS) Chtimes(name string, atime, mtime time.Time) error

func (EmptyFS) Create ¶

func (EmptyFS) Create(name string) (*os.File, error)

func (EmptyFS) Glob ¶

func (EmptyFS) Glob(pattern string) ([]string, error)

func (EmptyFS) Lchown ¶

func (EmptyFS) Lchown(name string, uid, git int) error

func (EmptyFS) Link ¶

func (EmptyFS) Link(oldname, newname string) error

func (EmptyFS) Lstat ¶

func (EmptyFS) Lstat(name string) (fs.FileInfo, error)

func (EmptyFS) Mkdir ¶

func (EmptyFS) Mkdir(name string, perm fs.FileMode) error

func (EmptyFS) Open ¶

func (EmptyFS) Open(name string) (fs.File, error)

func (EmptyFS) OpenFile ¶

func (EmptyFS) OpenFile(name string, flag int, perm fs.FileMode) (*os.File, error)

func (EmptyFS) PathSeparator ¶

func (EmptyFS) PathSeparator() rune

func (EmptyFS) RawPath ¶

func (EmptyFS) RawPath(name string) (string, error)

func (EmptyFS) ReadDir ¶

func (EmptyFS) ReadDir(dirname string) ([]fs.DirEntry, error)

func (EmptyFS) ReadFile ¶

func (EmptyFS) ReadFile(filename string) ([]byte, error)

func (EmptyFS) Readlink ¶

func (EmptyFS) Readlink(name string) (string, error)

func (EmptyFS) Remove ¶

func (EmptyFS) Remove(name string) error

func (EmptyFS) RemoveAll ¶

func (EmptyFS) RemoveAll(name string) error

func (EmptyFS) Rename ¶

func (EmptyFS) Rename(oldpath, newpath string) error

func (EmptyFS) Stat ¶

func (EmptyFS) Stat(name string) (fs.FileInfo, error)

func (EmptyFS) Symlink ¶

func (EmptyFS) Symlink(oldname, newname string) error

func (EmptyFS) Truncate ¶

func (EmptyFS) Truncate(name string, size int64) error

func (EmptyFS) WriteFile ¶

func (EmptyFS) WriteFile(filename string, data []byte, perm fs.FileMode) error

type FS ¶

type FS interface {
	Chmod(name string, mode fs.FileMode) error
	Chown(name string, uid, git int) error
	Chtimes(name string, atime, mtime time.Time) error
	Create(name string) (*os.File, error)
	Glob(pattern string) ([]string, error)
	Lchown(name string, uid, git int) error
	Link(oldname, newname string) error
	Lstat(name string) (fs.FileInfo, error)
	Mkdir(name string, perm fs.FileMode) error
	Open(name string) (fs.File, error)
	OpenFile(name string, flag int, perm fs.FileMode) (*os.File, error)
	PathSeparator() rune
	RawPath(name string) (string, error)
	ReadDir(dirname string) ([]fs.DirEntry, error)
	ReadFile(filename string) ([]byte, error)
	Readlink(name string) (string, error)
	Remove(name string) error
	RemoveAll(name string) error
	Rename(oldpath, newpath string) error
	Stat(name string) (fs.FileInfo, error)
	Symlink(oldname, newname string) error
	Truncate(name string, size int64) error
	WriteFile(filename string, data []byte, perm fs.FileMode) error
}

An FS is an abstraction over commonly-used functions in the os and io packages.

type LstatReadDirer ¶

type LstatReadDirer interface {
	Lstat(name string) (fs.FileInfo, error)
	ReadDir(name string) ([]fs.DirEntry, error)
}

A LstatReadDirer implements all the functionality needed by Walk.

type MkdirStater ¶

type MkdirStater interface {
	Mkdir(name string, perm fs.FileMode) error
	Stat(name string) (fs.FileInfo, error)
}

A MkdirStater implements all the functionality needed by MkdirAll.

type PathFS ¶

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

A PathFS operates on an existing FS, but prefixes all names with a path. All names must be absolute paths, with the exception of symlinks, which may be relative.

func NewPathFS ¶

func NewPathFS(fileSystem FS, path string) *PathFS

NewPathFS returns a new *PathFS operating on fileSystem and prefixing all names with path.

func (*PathFS) Chmod ¶

func (p *PathFS) Chmod(name string, mode fs.FileMode) error

Chmod implements os.Chmod.

func (*PathFS) Chown ¶

func (p *PathFS) Chown(name string, uid, gid int) error

Chown implements os.Chown.

func (*PathFS) Chtimes ¶

func (p *PathFS) Chtimes(name string, atime, mtime time.Time) error

Chtimes implements os.Chtimes.

func (*PathFS) Create ¶

func (p *PathFS) Create(name string) (*os.File, error)

Create implements os.Create.

func (*PathFS) Glob ¶

func (p *PathFS) Glob(pattern string) ([]string, error)

Glob implements filepath.Glob.

func (*PathFS) Join ¶

func (p *PathFS) Join(op, name string) (string, error)

Join returns p's path joined with name.

func (*PathFS) Lchown ¶

func (p *PathFS) Lchown(name string, uid, gid int) error

Lchown implements os.Lchown.

func (*PathFS) Link ¶

func (p *PathFS) Link(oldname, newname string) error

Link implements os.Link.

func (*PathFS) Lstat ¶

func (p *PathFS) Lstat(name string) (fs.FileInfo, error)

Lstat implements os.Lstat.

func (*PathFS) Mkdir ¶

func (p *PathFS) Mkdir(name string, perm fs.FileMode) error

Mkdir implements os.Mkdir.

func (*PathFS) Open ¶

func (p *PathFS) Open(name string) (fs.File, error)

Open implements os.Open.

func (*PathFS) OpenFile ¶

func (p *PathFS) OpenFile(name string, flag int, perm fs.FileMode) (*os.File, error)

OpenFile implements os.OpenFile.

func (*PathFS) PathSeparator ¶

func (p *PathFS) PathSeparator() rune

PathSeparator implements PathSeparator.

func (*PathFS) RawPath ¶

func (p *PathFS) RawPath(path string) (string, error)

RawPath implements RawPath.

func (*PathFS) ReadDir ¶

func (p *PathFS) ReadDir(dirname string) ([]fs.DirEntry, error)

ReadDir implements os.ReadDir.

func (*PathFS) ReadFile ¶

func (p *PathFS) ReadFile(name string) ([]byte, error)

ReadFile implements os.ReadFile.

func (*PathFS) Readlink ¶

func (p *PathFS) Readlink(name string) (string, error)

Readlink implements os.Readlink.

func (*PathFS) Remove ¶

func (p *PathFS) Remove(name string) error

Remove implements os.Remove.

func (*PathFS) RemoveAll ¶

func (p *PathFS) RemoveAll(name string) error

RemoveAll implements os.RemoveAll.

func (*PathFS) Rename ¶

func (p *PathFS) Rename(oldpath, newpath string) error

Rename implements os.Rename.

func (*PathFS) Stat ¶

func (p *PathFS) Stat(name string) (fs.FileInfo, error)

Stat implements os.Stat.

func (*PathFS) Symlink ¶

func (p *PathFS) Symlink(oldname, newname string) error

Symlink implements os.Symlink.

func (*PathFS) Truncate ¶

func (p *PathFS) Truncate(name string, size int64) error

Truncate implements os.Truncate.

func (*PathFS) WriteFile ¶

func (p *PathFS) WriteFile(filename string, data []byte, perm fs.FileMode) error

WriteFile implements io.WriteFile.

type ReadOnlyFS ¶

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

A ReadOnlyFS operates on an existing FS, but any methods that modify the FS return an error.

func NewReadOnlyFS ¶

func NewReadOnlyFS(fileSystem FS) *ReadOnlyFS

NewReadOnlyFS returns a new *ReadOnlyFS operating on fileSystem.

func (*ReadOnlyFS) Chmod ¶

func (r *ReadOnlyFS) Chmod(name string, mode fs.FileMode) error