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 |
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.
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
|
|
put ¶
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
land ¶
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
read ¶
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
state ¶
state(digest: Digest) -> ObjectState
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
path ¶
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
erase ¶
set_ref ¶
ref ¶
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
ref_path ¶
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
drop_ref ¶
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
publish_begin ¶
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
publish_commit ¶
retire ¶
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
pendings ¶
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
begin ¶
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
add ¶
commit ¶
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
groups ¶
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
pin ¶
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
unpin ¶
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
sweep ¶
sweep() -> SweepReport
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
view ¶
view(tree: Digest, at: Path) -> ViewRecord
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
collect ¶
drop_view ¶
drop_view(view_id: str) -> DropReport
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
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
unlock ¶
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
refuse_symlinks ¶
refuse_symlinks() -> Callable[[], None]
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
begin_during_sweep ¶
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
unlock ¶
refuse_symlinks ¶
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
begin_during_sweep ¶
Make the next sweep begin a publish of target mid-way, before deleting.
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
crash_commit_after ¶
Make the next commit stop after applied moves, as a crash would.
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
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 |
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. |
steps
class-attribute
instance-attribute
¶
load_scenarios ¶
Every scenario in every *.json under directory, files sorted.
Source code in packages/strongroom/src/livery/strongroom/testing/_conformance.py
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. |