std::storage::testing
Testing code that uses std::storage. Memory is a Store kept in
memory, so a test stores, reads and asserts with no directory or
server:
test "an upload stores the avatar" store = Memory.new() with App.store = store url = save_avatar(7, png)? assert Memory.keys(store) == ["avatars/7.png"] assert "${url}" == "https://storage.test/avatars/7.png" end
Failing is a store whose every call fails with an error the test
picks, for testing what a caller does when storage is down.
conformance is the suite every backend passes: a backend’s own tests
run it against stores it opens.
Import with import std::storage::testing.
Exports
Section titled “Exports”struct Memory
Section titled “struct Memory”struct Memory
opaque — construction surface is private to its defining module
A Store kept in memory, shared by every copy of the value. Its url
is public_base joined with the key; the default base is on
storage.test, a name reserved so it never reaches a real host.
store = Memory.new()
assert Store.put(store, "a.txt", String.to_bytes("hi"), "text/plain") == Ok(Unit)
assert Memory.keys(store) == ["a.txt"]
assert "${Store.url(store, "a.txt")!}" == "https://storage.test/a.txt"
Memory.new
Section titled “Memory.new”fn new(public_base: Url = Url"https://storage.test/") -> Memory
type function on Memory
An empty store whose URLs start with public_base.
Memory.keys
Section titled “Memory.keys”fn keys(memory: Memory) -> List<String>
type function on Memory
Every key held, sorted.
store = Memory.new()
_ = Store.put(store, "b", String.to_bytes(""), "text/plain")
_ = Store.put(store, "a", String.to_bytes(""), "text/plain")
assert Memory.keys(store) == ["a", "b"]
Memory.put
Section titled “Memory.put”impl Store for Memory
fn put(memory: Memory, key: String, data: Bytes, content_type: String) -> Result<Unit, Error>
impl Store.put
Memory.get
Section titled “Memory.get”impl Store for Memory
fn get(memory: Memory, key: String) -> Result<Object, Error>
impl Store.get
Memory.info
Section titled “Memory.info”impl Store for Memory
fn info(memory: Memory, key: String) -> Result<Maybe<Info>, Error>
impl Store.info
Memory.delete
Section titled “Memory.delete”impl Store for Memory
fn delete(memory: Memory, key: String) -> Result<Unit, Error>
impl Store.delete
Memory.url
Section titled “Memory.url”impl Store for Memory
fn url(memory: Memory, key: String) -> Result<Url, Error>
impl Store.url
Memory.list
Section titled “Memory.list”impl Store for Memory
fn list(memory: Memory, options: ListOptions) -> Result<Listing, Error>
impl Store.list
Memory.inspect
Section titled “Memory.inspect”impl Debug for Memory
fn inspect(value: Memory) -> String
impl Debug.inspect
struct Failing
Section titled “struct Failing”struct Failing error: Error = Error.Unavailable{message: "the test's store is failing"} end
A Store whose every call fails with error, whatever the key, for
testing what a caller does when storage is down. exists fails with it
too. The default error is an Unavailable one.
store = Failing{error: Error.Unavailable{message: "down"}}
assert Store.get(store, "a") == Err(Error.Unavailable{message: "down"})
assert Store.exists(store, "a") == Err(Error.Unavailable{message: "down"})
assert Store.put(Failing{}, "a", String.to_bytes(""), "text/plain") is Err(.Unavailable{})
Failing.put
Section titled “Failing.put”impl Store for Failing
fn put(failing: Failing, key: String, data: Bytes, content_type: String) -> Result<Unit, Error>
impl Store.put
Failing.get
Section titled “Failing.get”impl Store for Failing
fn get(failing: Failing, key: String) -> Result<Object, Error>
impl Store.get
Failing.info
Section titled “Failing.info”impl Store for Failing
fn info(failing: Failing, key: String) -> Result<Maybe<Info>, Error>
impl Store.info
Failing.delete
Section titled “Failing.delete”impl Store for Failing
fn delete(failing: Failing, key: String) -> Result<Unit, Error>
impl Store.delete
Failing.url
Section titled “Failing.url”impl Store for Failing
fn url(failing: Failing, key: String) -> Result<Url, Error>
impl Store.url
Failing.list
Section titled “Failing.list”impl Store for Failing
fn list(failing: Failing, options: ListOptions) -> Result<Listing, Error>
impl Store.list
Failing.inspect
Section titled “Failing.inspect”impl Debug for Failing
fn inspect(value: Failing) -> String
impl Debug.inspect
struct Broken
Section titled “struct Broken”struct Broken rule: String message: String end
A conformance rule a backend broke, and how. Its Display is rule: message.
Broken.to_string
Section titled “Broken.to_string”impl Display for Broken
fn to_string(broken: Broken) -> String
impl Display.to_string
Broken.inspect
Section titled “Broken.inspect”impl Debug for Broken
fn inspect(value: Broken) -> String
impl Debug.inspect
Broken.equal
Section titled “Broken.equal”impl Equatable for Broken
fn equal(a: Broken, b: Broken) -> Bool
impl Equatable.equal
testing.conformance
Section titled “testing.conformance”fn conformance(open: () -> Result<Store, Error>) -> List<Broken>
Runs every conformance rule against stores from open, and returns the
rules broken: none for a backend that conforms. Each rule opens a fresh
store and puts and reads objects under keys starting with
conformance/, except the rule on invalid keys, which puts b and
reads the valid keys a backend that cleaned an invalid key would have
used. A store open cannot make breaks the rule it was for.
The rules cover a put read back with its bytes, type and size, a put
replacing another, a missing key for each function, a delete, every
invalid key refused by every function with nothing stored, invalid
content types, an empty object, every byte value, an object of 5 MiB,
keys with punctuation, spaces and other scripts (odd_keys), url,
and list under conformance/list/: its order, sizes, common
prefixes and pages. There is no rule that keys a and a/b can both exist:
S3 allows it and storage.local cannot.
assert conformance(fn -> Ok(Memory.new())) == []
testing.rules
Section titled “testing.rules”fn rules() -> List<String>
The names of the conformance rules, in the order conformance runs
them.
assert Iter.contains(rules(), "an object of 5 MiB round-trips")
testing.invalid_keys
Section titled “testing.invalid_keys”fn invalid_keys() -> List<String>
The keys every function of a backend must refuse with InvalidKey.
assert Iter.all_match(invalid_keys(), fn key -> Result.is_err(storage.check_key(key)))
testing.odd_keys
Section titled “testing.odd_keys”fn odd_keys() -> List<String>
Valid keys a backend must store and address as written: each
punctuation character S3 allows, spaces, % escapes that are not
escapes, and letters outside ASCII. The conformance suite puts, reads,
deletes and links each under conformance/.
assert Iter.all_match(odd_keys(), fn key -> storage.check_key("conformance/${key}") == Ok(Unit))