blob: 0fd7d4806f72017a9c740b693196a3c503fd16ee [file] [log] [blame]
// Copyright 2020 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
// Package fstest implements support for testing implementations and users of file systems.
package fstest
import (
"errors"
"fmt"
"io"
"io/fs"
"path"
"reflect"
"sort"
"strings"
"testing/iotest"
)
// TestFS tests a file system implementation.
// It walks the entire tree of files in fsys,
// opening and checking that each file behaves correctly.
// It also checks that the file system contains at least the expected files.
// As a special case, if no expected files are listed, fsys must be empty.
// Otherwise, fsys must contain at least the listed files; it can also contain others.
// The contents of fsys must not change concurrently with TestFS.
//
// If TestFS finds any misbehaviors, it returns either the first error or a
// list of errors. Use [errors.Is] or [errors.As] to inspect.
//
// Typical usage inside a test is:
//
// if err := fstest.TestFS(myFS, "file/that/should/be/present"); err != nil {
// t.Fatal(err)
// }
func TestFS(fsys fs.FS, expected ...string) error {
if err := testFS(fsys, expected...); err != nil {
return err
}
for _, name := range expected {
if i := strings.Index(name, "/"); i >= 0 {
dir, dirSlash := name[:i], name[:i+1]
var subExpected []string
for _, name := range expected {
if strings.HasPrefix(name, dirSlash) {
subExpected = append(subExpected, name[len(dirSlash):])
}
}
sub, err := fs.Sub(fsys, dir)
if err != nil {
return err
}
if err := testFS(sub, subExpected...); err != nil {
return fmt.Errorf("testing fs.Sub(fsys, %s): %w", dir, err)
}
break // one sub-test is enough
}
}
return nil
}
func testFS(fsys fs.FS, expected ...string) error {
t := fsTester{fsys: fsys}
t.checkDir(".")
t.checkOpen(".")
found := make(map[string]bool)
for _, dir := range t.dirs {
found[dir] = true
}
for _, file := range t.files {
found[file] = true
}
delete(found, ".")
if len(expected) == 0 && len(found) > 0 {
var list []string
for k := range found {
if k != "." {
list = append(list, k)
}
}
sort.Strings(list)
if len(list) > 15 {
list = append(list[:10], "...")
}
t.errorf("expected empty file system but found files:\n%s", strings.Join(list, "\n"))
}
for _, name := range expected {
if !found[name] {
t.errorf("expected but not found: %s", name)
}
}
if len(t.errors) == 0 {
return nil
}
return fmt.Errorf("TestFS found errors:\n%w", errors.Join(t.errors...))
}
// An fsTester holds state for running the test.
type fsTester struct {
fsys fs.FS
errors []error
dirs []string
files []string
}
// errorf adds an error to the list of errors.
func (t *fsTester) errorf(format string, args ...any) {
t.errors = append(t.errors, fmt.Errorf(format, args...))
}
func (t *fsTester) openDir(dir string) fs.ReadDirFile {
f, err := t.fsys.Open(dir)
if err != nil {
t.errorf("%s: Open: %w", dir, err)
return nil
}
d, ok := f.(fs.ReadDirFile)
if !ok {
f.Close()
t.errorf("%s: Open returned File type %T, not a fs.ReadDirFile", dir, f)
return nil
}
return d
}
// checkDir checks the directory dir, which is expected to exist
// (it is either the root or was found in a directory listing with IsDir true).
func (t *fsTester) checkDir(dir string) {
// Read entire directory.
t.dirs = append(t.dirs, dir)
d := t.openDir(dir)
if d == nil {
return
}
list, err := d.ReadDir(-1)
if err != nil {
d.Close()
t.errorf("%s: ReadDir(-1): %w", dir, err)
return
}
// Check all children.
var prefix string
if dir == "." {
prefix = ""
} else {
prefix = dir + "/"
}
for _, info := range list {
name := info.Name()
switch {
case name == ".", name == "..", name == "":
t.errorf("%s: ReadDir: child has invalid name: %#q", dir, name)
continue
case strings.Contains(name, "/"):
t.errorf("%s: ReadDir: child name contains slash: %#q", dir, name)
continue
case strings.Contains(name, `\`):
t.errorf("%s: ReadDir: child name contains backslash: %#q", dir, name)
continue
}
path := prefix + name
t.checkStat(path, info)
t.checkOpen(path)
if info.IsDir() {
t.checkDir(path)
} else {
t.checkFile(path)
}
}
// Check ReadDir(-1) at EOF.
list2, err := d.ReadDir(-1)
if len(list2) > 0 || err != nil {
d.Close()
t.errorf("%s: ReadDir(-1) at EOF = %d entries, %w, wanted 0 entries, nil", dir, len(list2), err)
return
}
// Check ReadDir(1) at EOF (different results).
list2, err = d.ReadDir(1)
if len(list2) > 0 || err != io.EOF {
d.Close()
t.errorf("%s: ReadDir(1) at EOF = %d entries, %w, wanted 0 entries, EOF", dir, len(list2), err)
return
}
// Check that close does not report an error.
if err := d.Close(); err != nil {
t.errorf("%s: Close: %w", dir, err)
}
// Check that closing twice doesn't crash.
// The return value doesn't matter.
d.Close()
// Reopen directory, read a second time, make sure contents match.
if d = t.openDir(dir); d == nil {
return
}
defer d.Close()
list2, err = d.ReadDir(-1)
if err != nil {
t.errorf("%s: second Open+ReadDir(-1): %w", dir, err)
return
}
t.checkDirList(dir, "first Open+ReadDir(-1) vs second Open+ReadDir(-1)", list, list2)
// Reopen directory, read a third time in pieces, make sure contents match.
if d = t.openDir(dir); d == nil {
return
}
defer d.Close()
list2 = nil
for {
n := 1
if len(list2) > 0 {
n = 2
}
frag, err := d.ReadDir(n)
if len(frag) > n {
t.errorf("%s: third Open: ReadDir(%d) after %d: %d entries (too many)", dir, n, len(list2), len(frag))
return
}
list2 = append(list2, frag...)
if err == io.EOF {
break
}
if err != nil {
t.errorf("%s: third Open: ReadDir(%d) after %d: %w", dir, n, len(list2), err)
return
}
if n == 0 {
t.errorf("%s: third Open: ReadDir(%d) after %d: 0 entries but nil error", dir, n, len(list2))
return
}
}
t.checkDirList(dir, "first Open+ReadDir(-1) vs third Open+ReadDir(1,2) loop", list, list2)
// If fsys has ReadDir, check that it matches and is sorted.
if fsys, ok := t.fsys.(fs.ReadDirFS); ok {
list2, err := fsys.ReadDir(dir)
if err != nil {
t.errorf("%s: fsys.ReadDir: %w", dir, err)
return
}
t.checkDirList(dir, "first Open+ReadDir(-1) vs fsys.ReadDir", list, list2)
for i := 0; i+1 < len(list2); i++ {
if list2[i].Name() >= list2[i+1].Name() {
t.errorf("%s: fsys.ReadDir: list not sorted: %s before %s", dir, list2[i].Name(), list2[i+1].Name())
}
}
}
// Check fs.ReadDir as well.
list2, err = fs.ReadDir(t.fsys, dir)
if err != nil {
t.errorf("%s: fs.ReadDir: %w", dir, err)
return
}
t.checkDirList(dir, "first Open+ReadDir(-1) vs fs.ReadDir", list, list2)
for i := 0; i+1 < len(list2); i++ {
if list2[i].Name() >= list2[i+1].Name() {
t.errorf("%s: fs.ReadDir: list not sorted: %s before %s", dir, list2[i].Name(), list2[i+1].Name())
}
}
t.checkGlob(dir, list2)
}
// formatEntry formats an fs.DirEntry into a string for error messages and comparison.
func formatEntry(entry fs.DirEntry) string {
return fmt.Sprintf("%s IsDir=%v Type=%v", entry.Name(), entry.IsDir(), entry.Type())
}
// formatInfoEntry formats an fs.FileInfo into a string like the result of formatEntry, for error messages and comparison.
func formatInfoEntry(info fs.FileInfo) string {
return fmt.Sprintf("%s IsDir=%v Type=%v", info.Name(), info.IsDir(), info.Mode().Type())
}
// formatInfo formats an fs.FileInfo into a string for error messages and comparison.
func formatInfo(info fs.FileInfo) string {
return fmt.Sprintf("%s IsDir=%v Mode=%v Size=%d ModTime=%v", info.Name(), info.IsDir(), info.Mode(), info.Size(), info.ModTime())
}
// checkGlob checks that various glob patterns work if the file system implements GlobFS.
func (t *fsTester) checkGlob(dir string, list []fs.DirEntry) {
if _, ok := t.fsys.(fs.GlobFS); !ok {
return
}
// Make a complex glob pattern prefix that only matches dir.
var glob string
if dir != "." {
elem := strings.Split(dir, "/")
for i, e := range elem {
var pattern []rune
for j, r := range e {
if r == '*' || r == '?' || r == '\\' || r == '[' || r == '-' {
pattern = append(pattern, '\\', r)
continue
}
switch (i + j) % 5 {
case 0:
pattern = append(pattern, r)
case 1:
pattern = append(pattern, '[', r, ']')
case 2:
pattern = append(pattern, '[', r, '-', r, ']')
case 3:
pattern = append(pattern, '[', '\\', r, ']')
case 4:
pattern = append(pattern, '[', '\\', r, '-', '\\', r, ']')
}
}
elem[i] = string(pattern)
}
glob = strings.Join(elem, "/") + "/"
}
// Test that malformed patterns are detected.
// The error is likely path.ErrBadPattern but need not be.
if _, err := t.fsys.(fs.GlobFS).Glob(glob + "nonexist/[]"); err == nil {
t.errorf("%s: Glob(%#q): bad pattern not detected", dir, glob+"nonexist/[]")
}
// Try to find a letter that appears in only some of the final names.
c := rune('a')
for ; c <= 'z'; c++ {
have, haveNot := false, false
for _, d := range list {
if strings.ContainsRune(d.Name(), c) {
have = true
} else {
haveNot = true
}
}
if have && haveNot {
break
}
}
if c > 'z' {
c = 'a'
}
glob += "*" + string(c) + "*"
var want []string
for _, d := range list {
if strings.ContainsRune(d.Name(), c) {
want = append(want, path.Join(dir, d.Name()))
}
}
names, err := t.fsys.(fs.GlobFS).Glob(glob)
if err != nil {
t.errorf("%s: Glob(%#q): %w", dir, glob, err)
return
}
if reflect.DeepEqual(want, names) {
return
}
if !sort.StringsAreSorted(names) {
t.errorf("%s: Glob(%#q): unsorted output:\n%s", dir, glob, strings.Join(names, "\n"))
sort.Strings(names)
}
var problems []string
for len(want) > 0 || len(names) > 0 {
switch {
case len(want) > 0 && len(names) > 0 && want[0] == names[0]:
want, names = want[1:], names[1:]
case len(want) > 0 && (len(names) == 0 || want[0] < names[0]):
problems = append(problems, "missing: "+want[0])
want = want[1:]
default:
problems = append(problems, "extra: "+names[0])
names = names[1:]
}
}
t.errorf("%s: Glob(%#q): wrong output:\n%s", dir, glob, strings.Join(problems, "\n"))
}
// checkStat checks that a direct stat of path matches entry,
// which was found in the parent's directory listing.
func (t *fsTester) checkStat(path string, entry fs.DirEntry) {
file, err := t.fsys.Open(path)
if err != nil {
t.errorf("%s: Open: %w", path, err)
return
}
info, err := file.Stat()
file.Close()
if err != nil {
t.errorf("%s: Stat: %w", path, err)
return
}
fentry := formatEntry(entry)
fientry := formatInfoEntry(info)
// Note: mismatch here is OK for symlink, because Open dereferences symlink.
if fentry != fientry && entry.Type()&fs.ModeSymlink == 0 {
t.errorf("%s: mismatch:\n\tentry = %s\n\tfile.Stat() = %s", path, fentry, fientry)
}
einfo, err := entry.Info()
if err != nil {
t.errorf("%s: entry.Info: %w", path, err)
return
}
finfo := formatInfo(info)
if entry.Type()&fs.ModeSymlink != 0 {
// For symlink, just check that entry.Info matches entry on common fields.
// Open deferences symlink, so info itself may differ.
feentry := formatInfoEntry(einfo)
if fentry != feentry {
t.errorf("%s: mismatch\n\tentry = %s\n\tentry.Info() = %s\n", path, fentry, feentry)
}
} else {
feinfo := formatInfo(einfo)
if feinfo != finfo {
t.errorf("%s: mismatch:\n\tentry.Info() = %s\n\tfile.Stat() = %s\n", path, feinfo, finfo)
}
}
// Stat should be the same as Open+Stat, even for symlinks.
info2, err := fs.Stat(t.fsys, path)
if err != nil {
t.errorf("%s: fs.Stat: %w", path, err)
return
}
finfo2 := formatInfo(info2)
if finfo2 != finfo {
t.errorf("%s: fs.Stat(...) = %s\n\twant %s", path, finfo2, finfo)
}
if fsys, ok := t.fsys.(fs.StatFS); ok {
info2, err := fsys.Stat(path)
if err != nil {
t.errorf("%s: fsys.Stat: %w", path, err)
return
}
finfo2 := formatInfo(info2)
if finfo2 != finfo {
t.errorf("%s: fsys.Stat(...) = %s\n\twant %s", path, finfo2, finfo)
}
}
}
// checkDirList checks that two directory lists contain the same files and file info.
// The order of the lists need not match.
func (t *fsTester) checkDirList(dir, desc string, list1, list2 []fs.DirEntry) {
old := make(map[string]fs.DirEntry)
checkMode := func(entry fs.DirEntry) {
if entry.IsDir() != (entry.Type()&fs.ModeDir != 0) {
if entry.IsDir() {
t.errorf("%s: ReadDir returned %s with IsDir() = true, Type() & ModeDir = 0", dir, entry.Name())
} else {
t.errorf("%s: ReadDir returned %s with IsDir() = false, Type() & ModeDir = ModeDir", dir, entry.Name())
}
}
}
for _, entry1 := range list1 {
old[entry1.Name()] = entry1
checkMode(entry1)
}
var diffs []string
for _, entry2 := range list2 {
entry1 := old[entry2.Name()]
if entry1 == nil {
checkMode(entry2)
diffs = append(diffs, "+ "+formatEntry(entry2))
continue
}
if formatEntry(entry1) != formatEntry(entry2) {
diffs = append(diffs, "- "+formatEntry(entry1), "+ "+formatEntry(entry2))
}
delete(old, entry2.Name())
}
for _, entry1 := range old {
diffs = append(diffs, "- "+formatEntry(entry1))
}
if len(diffs) == 0 {
return
}
sort.Slice(diffs, func(i, j int) bool {
fi := strings.Fields(diffs[i])
fj := strings.Fields(diffs[j])
// sort by name (i < j) and then +/- (j < i, because + < -)
return fi[1]+" "+fj[0] < fj[1]+" "+fi[0]
})
t.errorf("%s: diff %s:\n\t%s", dir, desc, strings.Join(diffs, "\n\t"))
}
// checkFile checks that basic file reading works correctly.
func (t *fsTester) checkFile(file string) {
t.files = append(t.files, file)
// Read entire file.
f, err := t.fsys.Open(file)
if err != nil {
t.errorf("%s: Open: %w", file, err)
return
}
data, err := io.ReadAll(f)
if err != nil {
f.Close()
t.errorf("%s: Open+ReadAll: %w", file, err)
return
}
if err := f.Close(); err != nil {
t.errorf("%s: Close: %w", file, err)
}
// Check that closing twice doesn't crash.
// The return value doesn't matter.
f.Close()
// Check that ReadFile works if present.
if fsys, ok := t.fsys.(fs.ReadFileFS); ok {
data2, err := fsys.ReadFile(file)
if err != nil {
t.errorf("%s: fsys.ReadFile: %w", file, err)
return
}
t.checkFileRead(file, "ReadAll vs fsys.ReadFile", data, data2)
// Modify the data and check it again. Modifying the
// returned byte slice should not affect the next call.
for i := range data2 {
data2[i]++
}
data2, err = fsys.ReadFile(file)
if err != nil {
t.errorf("%s: second call to fsys.ReadFile: %w", file, err)
return
}
t.checkFileRead(file, "Readall vs second fsys.ReadFile", data, data2)
t.checkBadPath(file, "ReadFile",
func(name string) error { _, err := fsys.ReadFile(name); return err })
}
// Check that fs.ReadFile works with t.fsys.
data2, err := fs.ReadFile(t.fsys, file)
if err != nil {
t.errorf("%s: fs.ReadFile: %w", file, err)
return
}
t.checkFileRead(file, "ReadAll vs fs.ReadFile", data, data2)
// Use iotest.TestReader to check small reads, Seek, ReadAt.
f, err = t.fsys.Open(file)
if err != nil {
t.errorf("%s: second Open: %w", file, err)
return
}
defer f.Close()
if err := iotest.TestReader(f, data); err != nil {
t.errorf("%s: failed TestReader:\n\t%s", file, strings.ReplaceAll(err.Error(), "\n", "\n\t"))
}
}
func (t *fsTester) checkFileRead(file, desc string, data1, data2 []byte) {
if string(data1) != string(data2) {
t.errorf("%s: %s: different data returned\n\t%q\n\t%q", file, desc, data1, data2)
return
}
}
// checkBadPath checks that various invalid forms of file's name cannot be opened using t.fsys.Open.
func (t *fsTester) checkOpen(file string) {
t.checkBadPath(file, "Open", func(file string) error {
f, err := t.fsys.Open(file)
if err == nil {
f.Close()
}
return err
})
}
// checkBadPath checks that various invalid forms of file's name cannot be opened using open.
func (t *fsTester) checkBadPath(file string, desc string, open func(string) error) {
bad := []string{
"/" + file,
file + "/.",
}
if file == "." {
bad = append(bad, "/")
}
if i := strings.Index(file, "/"); i >= 0 {
bad = append(bad,
file[:i]+"//"+file[i+1:],
file[:i]+"/./"+file[i+1:],
file[:i]+`\`+file[i+1:],
file[:i]+"/../"+file,
)
}
if i := strings.LastIndex(file, "/"); i >= 0 {
bad = append(bad,
file[:i]+"//"+file[i+1:],
file[:i]+"/./"+file[i+1:],
file[:i]+`\`+file[i+1:],
file+"/../"+file[i+1:],
)
}
for _, b := range bad {
if err := open(b); err == nil {
t.errorf("%s: %s(%s) succeeded, want error", file, desc, b)
}
}
}