Skip to content

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.

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"
fn new(public_base: Url = Url"https://storage.test/") -> Memory

type function on Memory

An empty store whose URLs start with public_base.

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"]

impl Store for Memory

fn put(memory: Memory, key: String, data: Bytes, content_type: String) -> Result<Unit, Error>

impl Store.put

impl Store for Memory

fn get(memory: Memory, key: String) -> Result<Object, Error>

impl Store.get

impl Store for Memory

fn info(memory: Memory, key: String) -> Result<Maybe<Info>, Error>

impl Store.info

impl Store for Memory

fn delete(memory: Memory, key: String) -> Result<Unit, Error>

impl Store.delete

impl Store for Memory

fn url(memory: Memory, key: String) -> Result<Url, Error>

impl Store.url

impl Store for Memory

fn list(memory: Memory, options: ListOptions) -> Result<Listing, Error>

impl Store.list

impl Debug for Memory

fn inspect(value: Memory) -> String

impl Debug.inspect

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{})

impl Store for Failing

fn put(failing: Failing, key: String, data: Bytes, content_type: String) -> Result<Unit, Error>

impl Store.put

impl Store for Failing

fn get(failing: Failing, key: String) -> Result<Object, Error>

impl Store.get

impl Store for Failing

fn info(failing: Failing, key: String) -> Result<Maybe<Info>, Error>

impl Store.info

impl Store for Failing

fn delete(failing: Failing, key: String) -> Result<Unit, Error>

impl Store.delete

impl Store for Failing

fn url(failing: Failing, key: String) -> Result<Url, Error>

impl Store.url

impl Store for Failing

fn list(failing: Failing, options: ListOptions) -> Result<Listing, Error>

impl Store.list

impl Debug for Failing

fn inspect(value: Failing) -> String

impl Debug.inspect

struct Broken
    rule: String
    message: String
end

A conformance rule a backend broke, and how. Its Display is rule: message.

impl Display for Broken

fn to_string(broken: Broken) -> String

impl Display.to_string

impl Debug for Broken

fn inspect(value: Broken) -> String

impl Debug.inspect

impl Equatable for Broken

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

impl Equatable.equal

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())) == []
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")
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)))
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))