What is testing/fstest.MapFS, and how does a test use it to supply files without touching disk?

## The shape `fstest.MapFS` in the standard library's `testing/fstest` package is nothing more than ```go type MapFS map[string]*MapFile ``` with methods hung on it so that it satisfies `fs.FS`. A `MapFile` holds the content and the metadata: ```go type MapFile struct { Data []byte Mode fs.FileMode ModTime time.Time Sys any } ``` A whole test fixture is therefore a composite literal, and because the map's element type is a pointer the `&MapFile` may be elided: ```go fsys := fstest.MapFS{ "reports/2026-03-07.log": {Data: []byte("ok 1\n")}, "reports/2026-03-08.log": {Data: []byte("ok 2\n")}, } ``` ## The naming rules that trip people up Keys are file names as `io/fs` understands them: forward slashes on every platform, no leading slash, no `./` prefix, no drive letters. `"/reports/a.log"` and `"reports\\a.log"` are not paths that resolve to the same file — they are simply different, invalid names, and lookups for `"reports/a.log"` will miss them. The single name `"."` denotes the root. You do not have to list directories. MapFS synthesises the parents implied by the file names, so the fixture above makes `"reports"` a directory you can list. Add an explicit entry only when you need a particular mode or modification time on the directory itself, in which case set `Mode` with `fs.ModeDir`. ## Why it substitutes cleanly MapFS is not only an `fs.FS` with an `Open` method; it also implements the read helpers the standard library reaches for, so package-level functions such as `fs.ReadFile(fsys, name)` and `fs.WalkDir(fsys, ".", fn)` operate on it exactly as they would on a real directory tree. Code written against those helpers does not know or care which implementation it was handed. ## The seam is the parameter, not the fixture MapFS is only usable if the function under test takes a filesystem rather than a location. Compare: ```go func Summarise(dir string) (Report, error) // no seam: it will open real paths func Summarise(fsys fs.FS) (Report, error) // a seam: any fs.FS will do ``` With the second signature, production calls `Summarise(os.DirFS("/var/log/reports"))` and the test calls `Summarise(fsys)` with the map literal. `os.DirFS` is the production twin of MapFS: it turns a real directory into an `fs.FS` rooted there. Changing the parameter type is usually a small edit inside the function — replacing direct file opens with `fs.ReadFile` and `fs.WalkDir` — and it is the whole of the work. If you cannot change the signature (the code shells out, or it is a third component you do not own), MapFS cannot help and a real directory from `t.TempDir` is the fixture. ## What MapFS buys over a testdata directory Both work; they trade different things. - **Visibility.** The fixture is in the test function, three lines above the assertion, instead of in a `testdata` tree a reader has to open in another window. - **Speed and hermeticity.** No file creation, no cleanup, no leftover state from a failed run, no permissions or path-length quirks between operating systems. - **Precision.** Setting `ModTime` or an unusual `Mode` is a struct field rather than a system call, which makes it easy to test code that sorts by modification time or skips entries by mode. A `testdata` directory read through `os.DirFS` still wins when the fixture is genuinely large, binary, or shared between several tests, or when it is a real artefact you want checked into the repository as-is. ## What it cannot do MapFS is **read-only**. `io/fs` has no create, write, rename or remove operation, so any code path that produces files needs a different fixture. Mutating the map between calls is possible in principle, but treat it as fixture setup rather than as a filesystem operation the code under test performs. It is also **not a path**. There is no string you can hand to another process, to `os.Open`, or to a library that insists on a directory name. ## Checking a filesystem you wrote yourself The same package offers `fstest.TestFS(fsys fs.FS, expected ...string) error`, which walks an implementation, exercises its read operations and reports where it deviates from what `io/fs` requires, verifying that the named files are present. That is the tool for the other direction: not faking a filesystem for your code, but proving that a filesystem implementation you wrote behaves like one.