Go testing/fstest用 MapFS 构造轻量文件测试的实践示例

我在给读取配置文件的函数补单元测试时，最容易踩的坑是把测试和本机目录绑死：要先创建临时目录，再写文件，最后还要清理。这个场景更适合把函数参数改成 fs.FS，测试里用 testing/fstest.MapFS 描述一棵很小的内存文件树。这样成功内容、缺失文件和目录结构都能在同一个测试中稳定复现。

官方文档：https://pkg.go.dev/testing/fstest

先让读取函数依赖 fs.FS

MapFS 最有价值的地方不是“少写几行临时文件代码”，而是把测试替身放在标准库已经定义好的接口边界上。生产代码可以接收 os.DirFS，单元测试则传入 MapFS，读取逻辑本身不需要知道文件来自磁盘还是内存。

package config

import (
    "io/fs"
    "os"
    "path/filepath"
)

// readConfig 只依赖 fs.FS，生产和测试可以复用同一份读取逻辑。
func readConfig(fsys fs.FS, name string) ([]byte, error) {
    // fs.ReadFile 负责打开、读取并关闭文件，避免测试代码管理文件句柄。
    return fs.ReadFile(fsys, filepath.ToSlash(name))
}

// productionFS 展示真实目录的接入方式，单元测试不会调用它。
func productionFS(root string) fs.FS {
    // DirFS 将绝对目录封装为 fs.FS，业务函数不再拼接磁盘根路径。
    return os.DirFS(root)
}

这里的关键是路径边界。fs.FS 使用斜杠分隔的相对路径，调用方应传入类似 config/app.json 的名字，不要把测试机上的绝对路径直接塞进读取函数。

用 MapFS 描述最小文件树

fstest.MapFS 的底层形态是 map[string]*fstest.MapFile。普通文件只需要填 Data，需要控制目录属性时再设置 Mode: fs.ModeDir。父目录通常可以按需合成，但显式写出目录有助于测试空目录或目录元信息。

package config

import (
    "errors"
    "io/fs"
    "testing"
    "testing/fstest"
)

func TestReadConfigWithMapFS(t *testing.T) {
    files := fstest.MapFS{
        "config/app.json": &fstest.MapFile{
            // Data 是内存文件内容，适合放入最小但有代表性的样本。
            Data: []byte(`{"port":8080,"debug":true}`),
        },
    }

    got, err := readConfig(files, "config/app.json")
    if err != nil {
        t.Fatalf("读取配置失败: %v", err)
    }
    if string(got) != `{"port":8080,"debug":true}` {
        t.Fatalf("配置内容不符: %s", got)
    }

    // 缺失路径要断言标准错误，避免只检查“有错误”而漏掉边界语义。
    _, err = readConfig(files, "config/missing.json")
    if !errors.Is(err, fs.ErrNotExist) {
        t.Fatalf("缺失文件错误不符: %v", err)
    }
}

这种写法把测试数据压缩到一个可读的文件树里。需要多个场景时，可以为每个测试创建自己的 MapFS，不要在测试之间共享并修改同一个 map。

用 TestFS 检查文件系统契约

如果你不仅要验证业务函数的返回值，还想确认文件系统实现本身符合 fs.FS 的基本行为，可以调用 fstest.TestFS。它会遍历文件树并检查文件是否能正确打开、读取；传入的 expected 文件则表示至少应该存在的路径。

func TestMapFSContract(t *testing.T) {
    files := fstest.MapFS{
        "config/app.json": &fstest.MapFile{Data: []byte(`{}`)},
        "config/": &fstest.MapFile{Mode: fs.ModeDir},
    }

    // TestFS 检查文件系统行为；expected 只声明必须存在的文件。
    if err := fstest.TestFS(files, "config/app.json"); err != nil {
        t.Fatalf("MapFS 契约检查失败: %v", err)
    }
}

TestFS 解决的是文件系统契约，业务测试仍然要单独断言 JSON 内容、默认值或错误转换。两者职责不要混在一个模糊的“测试通过”判断里。

MapFS 的适用边界和判断清单

我的判断顺序通常是：先看被测函数是否真的需要磁盘特性；如果不需要，就把参数收敛到 fs.FS，用 MapFS 写出最小文件树；最后用 TestFS 补一层契约检查。这样测试表达的是业务所需的文件关系，而不是某台机器的目录布局。

相关问题

MapFS 一定要手动添加父目录吗？

不一定。普通文件的父目录通常会按需合成；只有要测试空目录或精确控制目录属性时，才显式放入带 fs.ModeDir 的 MapFile。

MapFS 能替代所有临时目录测试吗？

不能。权限、文件锁、真实路径、磁盘空间和操作系统差异仍应使用临时目录或系统级测试验证。

为什么测试中不能边读边修改 MapFS？

MapFS 的文件操作直接读取底层 map；并发修改会形成数据竞态。每个测试独立构造文件树，通常比共享实例更简单。