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.
Exports
Section titled “Exports”struct Sandbox
Section titled “struct Sandbox”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.
Sandbox.inspect
Section titled “Sandbox.inspect”impl Debug for Sandbox
fn inspect(value: Sandbox) -> String
impl Debug.inspect
struct Failure
Section titled “struct Failure”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")
Failure.inspect
Section titled “Failure.inspect”impl Debug for Failure
fn inspect(value: Failure) -> String
impl Debug.inspect
enum Operation
Section titled “enum Operation”enum Operation Read Write Create Remove Rename List Metadata Close end
What a Failure matches.
Variants
-
ReadOpening a file to read it:
fs.read,fs.read_text,fs.open, each run offs.linesandfs.chunks,fs.copy’s source, andfs.open_filewithAccess.Read. -
WriteEach write of data to a file opened for writing, and each
File.write,File.write_atandFile.truncate. -
CreateOpening a file to write it (
fs.write,fs.create,fs.copy’s target,fs.open_filewith another access), making a directory, and making a symlink. -
Removefs.removeandfs.remove_all. -
Renamefs.rename, matched on the path renamed from. -
Listfs.list. -
Metadatafs.metadata,fs.exists,fs.link_metadata,fs.read_linkandfs.set_mode. -
CloseClosing a file opened to read or write.
Operation.inspect
Section titled “Operation.inspect”impl Debug for Operation
fn inspect(value: Operation) -> String
impl Debug.inspect
Operation.equal
Section titled “Operation.equal”impl Equatable for Operation
fn equal(a: Operation, b: Operation) -> Bool
impl Equatable.equal
struct Ran
Section titled “struct Ran”struct Ran<T> value: T files: Map<String, Bytes> log: List<String> open: List<String> end
What run returns.
Ran.inspect
Section titled “Ran.inspect”impl Debug for Ran<T>
fn inspect<T>(value: Ran<T>) -> String where T: Debug
impl Debug.inspect
testing.run
Section titled “testing.run”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 == []
testing.text
Section titled “testing.text”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
Section titled “struct ConformanceFailure”struct ConformanceFailure rule: String reason: String end
A rule of std::fs that a file system broke, from conformance.
ConformanceFailure.inspect
Section titled “ConformanceFailure.inspect”impl Debug for ConformanceFailure
fn inspect(value: ConformanceFailure) -> String
impl Debug.inspect
testing.conformance
Section titled “testing.conformance”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([])