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