Skip to content

livery.strongroom.testing

livery.strongroom.testing

The conformance kit: the scenarios under spec/conformance, run against a store.

A scenario is data, so any implementation of the store's API runs the same suite: livery.strongroom.testing.load_scenarios reads the scenarios and livery.strongroom.testing.run_scenario runs one against a store the caller opens. The kit reaches the three seams a scenario needs through livery.strongroom.testing.Hooks, and livery.strongroom.testing.PythonHooks is the Python store's own. A failed step raises livery.strongroom.testing.ConformanceFailure naming the scenario, the step and what was found.

A module of its own, so importing livery.strongroom to use a store never loads the kit.

Classes:

Name Description
ConformanceFailure

A scenario step did not do what the scenario says.

Hooks

The seams a scenario reaches past the API.

PythonHooks

The Python store's seams: its lock file, its rungs module, its sweep hook.

Scenario

One scenario: where it came from, its namespaces, its steps.

StoreLike

What the harness drives: the store's API, as the scenarios use it.

Functions:

Name Description
load_scenarios

Every scenario in every *.json under directory, files sorted.

run_scenario

Run one scenario against a fresh store from open_store.

Attributes:

Name Type Description
REFUSALS dict[str, type[Exception]]

The refusal a scenario may expect, by name, and the class it must raise.

LockHolder

Who a scenario says holds a lock: a live process, an exited one, or one long ago.

REFUSALS module-attribute

REFUSALS: dict[str, type[Exception]] = {'write-once-refused': WriteOnceRefused, 'not-fast-forward': NotFastForward, 'conflict': RefConflict, 'lock-timeout': LockTimeout, 'tampered': RefTampered, 'unknown-namespace': UnknownNamespace, 'missing': MissingObject, 'erased': ErasedObject, 'no-such-pending': NoSuchPending, 'protected': RefProtected, 'not-a-group': NotAGroup, 'half-applied': GroupHalfApplied, 'crashed': CrashedCommit}

The refusal a scenario may expect, by name, and the class it must raise.

LockHolder module-attribute

LockHolder = Literal['live', 'dead', 'expired']

Who a scenario says holds a lock: a live process, an exited one, or one long ago.

__all__ module-attribute

__all__ = ['REFUSALS', 'ConformanceFailure', 'Hooks', 'LockHolder', 'PythonHooks', 'Scenario', 'StoreLike', 'load_scenarios', 'run_scenario']

ConformanceFailure

Bases: AssertionError

A scenario step did not do what the scenario says.

Hooks

Bases: Protocol

The seams a scenario reaches past the API.

Each returns a callable that undoes it, run when the scenario ends whatever happened.

Methods:

Name Description
write_lock
unlock
refuse_symlinks
begin_during_sweep
crash_commit_after

write_lock

write_lock(store: StoreLike, namespace: str, path: str, holder: LockHolder) -> None
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
def write_lock(
    self, store: StoreLike, namespace: str, path: str, holder: LockHolder
) -> None: ...

unlock

unlock(store: StoreLike, namespace: str, path: str) -> None
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
def unlock(self, store: StoreLike, namespace: str, path: str) -> None: ...
refuse_symlinks() -> Callable[[], None]
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
def refuse_symlinks(self) -> Callable[[], None]: ...

begin_during_sweep

begin_during_sweep(store: StoreLike, target: Digest) -> Callable[[], None]
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
def begin_during_sweep(
    self, store: StoreLike, target: Digest
) -> Callable[[], None]: ...

crash_commit_after

crash_commit_after(applied: int) -> Callable[[], None]
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
def crash_commit_after(self, applied: int) -> Callable[[], None]: ...

PythonHooks

The Python store's seams: its lock file, its rungs module, its sweep hook.

Methods:

Name Description
write_lock

Write the ref's lock file as holder would have left it.

unlock

Remove the ref's lock file.

refuse_symlinks

Make the symlink rung refuse until the returned callable runs.

begin_during_sweep

Make the next sweep begin a publish of target mid-way, before deleting.

crash_commit_after

Make the next commit stop after applied moves, as a crash would.

write_lock

write_lock(store: StoreLike, namespace: str, path: str, holder: LockHolder) -> None

Write the ref's lock file as holder would have left it.

Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
def write_lock(
    self, store: StoreLike, namespace: str, path: str, holder: LockHolder
) -> None:
    """Write the ref's lock file as *holder* would have left it."""
    if holder == "live":
        content = {"pid": os.getpid(), "at": time.time()}
    elif holder == "expired":
        content = {"pid": os.getpid(), "at": time.time() - 3600}
    else:
        child = subprocess.Popen([sys.executable, "-c", "pass"])
        child.wait()
        content = {"pid": child.pid, "at": time.time()}
    lock = _lock_path(store, namespace, path)
    lock.parent.mkdir(parents=True, exist_ok=True)
    lock.write_text(json.dumps(content))

unlock

unlock(store: StoreLike, namespace: str, path: str) -> None

Remove the ref's lock file.

Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
def unlock(self, store: StoreLike, namespace: str, path: str) -> None:
    """Remove the ref's lock file."""
    _lock_path(store, namespace, path).unlink()
refuse_symlinks() -> Callable[[], None]

Make the symlink rung refuse until the returned callable runs.

Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
def refuse_symlinks(self) -> Callable[[], None]:
    """Make the symlink rung refuse until the returned callable runs."""
    original = rungs.symlink

    def refuse(
        target: str | Path, destination: Path, *, directory: bool = False
    ) -> None:
        raise RungUnavailable(1, "refused by the conformance harness")

    rungs.symlink = refuse

    def restore() -> None:
        rungs.symlink = original

    return restore

begin_during_sweep

begin_during_sweep(store: StoreLike, target: Digest) -> Callable[[], None]

Make the next sweep begin a publish of target mid-way, before deleting.

Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
def begin_during_sweep(
    self, store: StoreLike, target: Digest
) -> Callable[[], None]:
    """Make the next sweep begin a publish of *target* mid-way, before deleting."""
    original = lifecycle.after_mark

    def begin() -> None:
        store.publish_begin(target, by=_WILLEM)

    lifecycle.after_mark = begin

    def restore() -> None:
        lifecycle.after_mark = original

    return restore

crash_commit_after

crash_commit_after(applied: int) -> Callable[[], None]

Make the next commit stop after applied moves, as a crash would.

Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
def crash_commit_after(self, applied: int) -> Callable[[], None]:
    """Make the next commit stop after *applied* moves, as a crash would."""
    original = groups.after_apply

    def crash(count: int) -> None:
        if count == applied:
            raise CrashedCommit(f"the harness stopped the commit after {count}")

    groups.after_apply = crash

    def restore() -> None:
        groups.after_apply = original

    return restore

Scenario dataclass

Scenario(file: str, id: str, namespaces: tuple[Namespace, ...], steps: tuple[dict[str, Any], ...] = tuple())

One scenario: where it came from, its namespaces, its steps.

Attributes:

Name Type Description
file str

the conformance file's stem, such as refs.

id str

the scenario's id within the file.

namespaces tuple[Namespace, ...]

the namespaces the store is opened with.

steps tuple[dict[str, Any], ...]

the steps, in order.

file instance-attribute

file: str

id instance-attribute

id: str

namespaces instance-attribute

namespaces: tuple[Namespace, ...]

steps class-attribute instance-attribute

steps: tuple[dict[str, Any], ...] = field(default_factory=tuple)

name property

name: str

<file>:<id>, the scenario's name in a report.

StoreLike

Bases: Protocol

What the harness drives: the store's API, as the scenarios use it.

Methods:

Name Description
put
land
read
state
path
erase
set_ref
ref
ref_path
drop_ref
publish_begin
publish_commit
retire
pendings
begin
add
commit
groups
pin
unpin
sweep
view
collect
drop_view

Attributes:

Name Type Description
root Path

root instance-attribute

root: Path

put

put(data: bytes) -> Digest
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
def put(self, data: bytes) -> Digest: ...

land

land(source: bytes, *, expected: Digest | None = None) -> Landed
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
def land(self, source: bytes, *, expected: Digest | None = None) -> Landed: ...

read

read(digest: Digest) -> bytes
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
def read(self, digest: Digest) -> bytes: ...

state

state(digest: Digest) -> ObjectState
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
def state(self, digest: Digest) -> ObjectState: ...

path

path(digest: Digest) -> Path
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
def path(self, digest: Digest) -> Path: ...

erase

erase(digest: Digest, *, by: Subject, reason: str, receipt: Digest | None = None) -> Tombstone
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
def erase(
    self, digest: Digest, *, by: Subject, reason: str, receipt: Digest | None = None
) -> Tombstone: ...

set_ref

set_ref(namespace: str, path: str, digest: Digest, *, previous: Digest | None, by: Subject) -> RefRecord
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
def set_ref(
    self,
    namespace: str,
    path: str,
    digest: Digest,
    *,
    previous: Digest | None,
    by: Subject,
) -> RefRecord: ...

ref

ref(namespace: str, path: str) -> Digest | None
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
def ref(self, namespace: str, path: str) -> Digest | None: ...

ref_path

ref_path(namespace: str, path: str) -> Path
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
def ref_path(self, namespace: str, path: str) -> Path: ...

drop_ref

drop_ref(namespace: str, path: str, *, previous: Digest) -> None
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
def drop_ref(self, namespace: str, path: str, *, previous: Digest) -> None: ...

publish_begin

publish_begin(target: Digest, *, by: Subject) -> Pending
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
def publish_begin(self, target: Digest, *, by: Subject) -> Pending: ...

publish_commit

publish_commit(pending_id: str, namespace: str, path: str, *, previous: Digest | None, by: Subject) -> RefRecord
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
def publish_commit(
    self,
    pending_id: str,
    namespace: str,
    path: str,
    *,
    previous: Digest | None,
    by: Subject,
) -> RefRecord: ...

retire

retire(pending_id: str) -> Digest
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
def retire(self, pending_id: str) -> Digest: ...

pendings

pendings() -> list[str]
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
def pendings(self) -> list[str]: ...

begin

begin(*, by: Subject) -> Group
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
def begin(self, *, by: Subject) -> Group: ...

add

add(group_id: str, namespace: str, path: str, digest: Digest, *, previous: Digest | None) -> Group
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
def add(
    self,
    group_id: str,
    namespace: str,
    path: str,
    digest: Digest,
    *,
    previous: Digest | None,
) -> Group: ...

commit

commit(group_id: str, *, by: Subject) -> tuple[RefRecord, ...]
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
def commit(self, group_id: str, *, by: Subject) -> tuple[RefRecord, ...]: ...

groups

groups() -> list[Group]
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
def groups(self) -> list[Group]: ...

pin

pin(name: str, digest: Digest, *, by: Subject) -> RefRecord
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
def pin(self, name: str, digest: Digest, *, by: Subject) -> RefRecord: ...

unpin

unpin(name: str) -> Digest
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
def unpin(self, name: str) -> Digest: ...

sweep

sweep() -> SweepReport
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
def sweep(self) -> SweepReport: ...

view

view(tree: Digest, at: Path) -> ViewRecord
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
def view(self, tree: Digest, at: Path) -> ViewRecord: ...

collect

collect(at: Path, declared: Iterable[str], *, executable: Iterable[str] = ()) -> Tree
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
def collect(
    self, at: Path, declared: Iterable[str], *, executable: Iterable[str] = ()
) -> Tree: ...

drop_view

drop_view(view_id: str) -> DropReport
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
def drop_view(self, view_id: str) -> DropReport: ...

load_scenarios

load_scenarios(directory: Path) -> list[Scenario]

Every scenario in every *.json under directory, files sorted.

Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
def load_scenarios(directory: Path) -> list[Scenario]:
    """Every scenario in every `*.json` under *directory*, files sorted."""
    found: list[Scenario] = []
    for file in sorted(directory.glob("*.json")):
        loaded = json.loads(file.read_text("utf-8"))
        for scenario in loaded["scenarios"]:
            namespaces = tuple(
                Namespace(ns["name"], ns["mutation"]) for ns in scenario["namespaces"]
            )
            found.append(
                Scenario(
                    file.stem, scenario["id"], namespaces, tuple(scenario["steps"])
                )
            )
    return found

run_scenario

run_scenario(scenario: Scenario, open_store: Callable[[tuple[Namespace, ...]], StoreLike], hooks: Hooks, base: Path) -> None

Run one scenario against a fresh store from open_store.

Parameters:

Name Type Description Default
scenario Scenario

the scenario.

required
open_store Callable[[tuple[Namespace, ...]], StoreLike]

creates the store under test with the scenario's namespaces declared.

required
hooks Hooks

the implementation's seams.

required
base Path

a directory for the views the scenario fills.

required

Raises:

Type Description
ConformanceFailure

naming the scenario, the step and what was found, at the first step that does not do what the scenario says.

Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
def run_scenario(
    scenario: Scenario,
    open_store: Callable[[tuple[Namespace, ...]], StoreLike],
    hooks: Hooks,
    base: Path,
) -> None:
    """Run one scenario against a fresh store from *open_store*.

    Args:
        scenario: the scenario.
        open_store: creates the store under test with the scenario's
            namespaces declared.
        hooks: the implementation's seams.
        base: a directory for the views the scenario fills.

    Raises:
        ConformanceFailure: naming the scenario, the step and what was
            found, at the first step that does not do what the
            scenario says.
    """
    store = open_store(scenario.namespaces)
    run = _Run(scenario, store, hooks, base)
    try:
        for index, step in enumerate(scenario.steps):
            run.step(index, step)
    finally:
        run.restore()