Skip to content

std::fs::testing

Testing code that reads and writes files, without the disk. Inside testing.run(sandbox, body), every std::fs call body makes, and every call the tasks it starts make, goes to an in-memory file system built from the sandbox. run returns what body returned together with the files afterwards, each operation in order and the handles left open. As with io.capture, the sandbox lasts for the call and follows its tasks, two tasks running their own testing.run at once never see each other’s files, and a nested run takes over for its own call.

The sandbox is the same in-memory file system the browser build uses, and testing.conformance holds it to the operating system’s: std’s own tests run every rule against a real temporary directory and against a sandbox.

import
    std::fs::testing.{self, Sandbox}
    sort_lines
end

test "sorts the lines into the output file"
    ran = testing.run(Sandbox{files: {"in.txt" => "pear\napple\n"}}, fn ->
        sort_lines.sort_file("in.txt", "out.txt")
    end)

    assert ran.value == Ok(2)
    assert testing.text(ran, "/work/out.txt") == Some("apple\npear\n")
    assert ran.open == []
end

Import with import std::fs::testing.

struct Sandbox
    files: Map<String, String> = {}
    binary: Map<String, Bytes> = {}
    dirs: List<String> = []
    links: Map<String, String> = {}
    failures: List<Failure> = []
    cwd: String = "/work"
end

The files a run starts with. The sandbox keeps permission bits and returns them, and refuses nothing because of them.

impl Debug for Sandbox

fn inspect(value: Sandbox) -> String

impl Debug.inspect

struct Failure
    path: String
    operation: Operation
    error: Error
    nth: Maybe<Int> = None
end

An operation on a path that fails with error instead of happening, every time, or only the nth matching time when nth is Some(n). An atomic write whose Write fails leaves the old file in the sandbox.

full = Failure{path: "out.txt", operation: Operation.Write, error: Error.NoSpace{path: "out.txt"}}

ran = run(Sandbox{files: {"out.txt" => "old"}, failures: [full]}, fn ->
    fs.write_text("out.txt", "new", mode: WriteMode.ReplaceAtomically)
end)

assert ran.value == Err(Error.NoSpace{path: "out.txt"})
assert text(ran, "/work/out.txt") == Some("old")

impl Debug for Failure

fn inspect(value: Failure) -> String

impl Debug.inspect

enum Operation
    Read
    Write
    Create
    Remove
    Rename
    List
    Metadata
    Close
end

What a Failure matches.

Variants

  • Read

    Opening a file to read it: fs.read, fs.read_text, fs.open, each run of fs.lines and fs.chunks, fs.copy’s source, and fs.open_file with Access.Read.

  • Write

    Each write of data to a file opened for writing, and each File.write, File.write_at and File.truncate.

  • Create

    Opening a file to write it (fs.write, fs.create, fs.copy’s target, fs.open_file with another access), making a directory, and making a symlink.

  • Remove

    fs.remove and fs.remove_all.

  • Rename

    fs.rename, matched on the path renamed from.

  • List

    fs.list.

  • Metadata

    fs.metadata, fs.exists, fs.link_metadata, fs.read_link and fs.set_mode.

  • Close

    Closing a file opened to read or write.

impl Debug for Operation

fn inspect(value: Operation) -> String

impl Debug.inspect

impl Equatable for Operation

fn equal(a: Operation, b: Operation) -> Bool

impl Equatable.equal

struct Ran<T>
    value: T
    files: Map<String, Bytes>
    log: List<String>
    open: List<String>
end

What run returns.

impl Debug for Ran<T>

fn inspect<T>(value: Ran<T>) -> String where T: Debug

impl Debug.inspect

fn run<T>(sandbox: Sandbox, body: () -> T) -> Ran<T>

Runs body with an in-memory file system built from sandbox, and returns what it returned with the files afterwards. Nothing touches the disk. If body traps, the trap propagates.

ran = run(Sandbox{files: {"in.txt" => "b\na\n"}}, fn ->
    names = Result.collect(fs.lines("in.txt"))?
    fs.write_text("out.txt", String.join(Iter.sort(names), ","))
end)

assert ran.value == Ok(Unit)
assert text(ran, "/work/out.txt") == Some("a,b")
assert ran.log == ["read /work/in.txt", "write /work/out.txt"]
assert ran.open == []
fn text<T>(ran: Ran<T>, at: String) -> Maybe<String>

The text of the file at the absolute path at when run returned, or None when it is missing or not UTF-8.

ran = run(Sandbox{}, fn -> fs.write_text("a.txt", "hi"))
assert text(ran, "/work/a.txt") == Some("hi")
assert text(ran, "a.txt") == None
struct ConformanceFailure
    rule: String
    reason: String
end

A rule of std::fs that a file system broke, from conformance.

impl Debug for ConformanceFailure

fn inspect(value: ConformanceFailure) -> String

impl Debug.inspect

fn conformance(root: String) -> List<ConformanceFailure>

Runs every rule of std::fs against the directory root, which must exist and be empty, and returns the rules the file system there broke. Each rule works in a directory of its own under root. The rules cover each WriteMode, NotFound for a missing parent, sorted listings, remove of a directory with entries, remove_all of a missing path, rename over a file, an atomic write that fails, line splitting, InvalidText, closed handles, exists, walks and globs, symlinks (followed by reads and metadata, not by link_metadata, remove, rename and walks; a dangling one; a loop), set_mode, a File’s reads and writes at a position, and fs.within’s confinement.

std’s own tests run it twice, against the disk in a directory from fs.make_temp_dir and against a sandbox inside run, so a rule both pass is one the sandbox models as the disk behaves.

assert run(Sandbox{}, fn -> conformance("/work")).value == []

fn on_disk() -> Result<List<ConformanceFailure>, Error>
    dir = fs.make_temp_dir()?
    defer fs.remove_all_quietly(dir)
    Ok(conformance(dir))
end

assert on_disk() == Ok([])