Skip to content

livery.strongroom.testing._conformance

livery.strongroom.testing._conformance

The conformance harness: the scenarios under spec/conformance, run.

A scenario is data: the namespaces a store is opened with and the steps run against it in order. The harness interprets the steps against any implementation that speaks the store's API, through livery.strongroom.testing.StoreLike, and reaches the three seams a scenario needs (a lock written as if held, a platform that refuses symlinks, a publish that begins mid-sweep) through livery.strongroom.testing.Hooks. 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.

Reach for livery.strongroom.testing.load_scenarios and livery.strongroom.testing.run_scenario.

Classes:

Name Description
CrashedCommit

The harness stopped a commit part-way, as a crash would.

ConformanceFailure

A scenario step did not do what the scenario says.

StoreLike

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

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.

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
LockHolder

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

REFUSALS dict[str, type[Exception]]

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.

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.

CrashedCommit

Bases: Exception

The harness stopped a commit part-way, as a crash would.

ConformanceFailure

Bases: AssertionError

A scenario step did not do what the scenario says.

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: ...

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.

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()