livery.forge.testing._fake¶
livery.forge.testing._fake ¶
An in-memory forge that answers from tables and injects faults on demand.
livery.forge.testing.FakeForge implements livery.forge.Forge without a server: every operation reads and writes plain dictionaries, so a test that would take minutes against a container runs in microseconds. The fake is verified, not trusted: the same conformance suite the real backends must pass runs against it, so behaving like the contract is a tested property.
Beyond the protocol, the fake is the world: driver methods simulate what the git lane and the CI runners would do (a push, a tag, a run finishing), and livery.forge.testing.Faults injects the quirks the real forges have taught, deterministically. Each fault mode has its line in the package's quirks list and a regression test that fails without it.
Classes:
| Name | Description |
|---|---|
Faults |
Deterministic fault injection, one attribute per known forge quirk. |
FakeForge |
A livery.forge.Forge that keeps everything in memory. |
FakeDriver |
The livery.forge.testing.ForgeDriver over a FakeForge. |
Faults
dataclass
¶
Faults(lose_arm_schedule: int = 0, merge_405_window: int = 0, wedge_status_queue: bool = False, slow_status_reads: int = 0, drop_connections: int = 0, rate_limited: int = 0, rate_limit_reset: float | None = None)
Deterministic fault injection, one attribute per known forge quirk.
Counters arm a fault for the next N triggering calls and count down as they fire; a flag holds until cleared. Nothing here is random: a test arms exactly the fault it needs and the fake misbehaves exactly that often.
Attributes:
| Name | Type | Description |
|---|---|---|
lose_arm_schedule |
int
|
The next N calls to livery.forge.PullRequests.arm succeed silently without recording a schedule, so the pull request reads unarmed afterwards. The lost-auto-merge-schedule quirk. |
merge_405_window |
int
|
The next N calls to livery.forge.PullRequests.merge_now or livery.forge.PullRequests.arm raise livery.forge.ForgeError with status 405, as a forge does while a mergeability recompute is in flight; the arm shares the merge endpoint, so the window refuses both. |
wedge_status_queue |
bool
|
While True, runs never leave the queued state: a finished run is not recorded, so the combined status stays pending forever. Cancelling the run is the relief, as it is on a real wedged queue. |
slow_status_reads |
int
|
The next N calls to livery.forge.Checks.status answer as if nothing had reported for the commit, as a forge does in the window after a push before statuses appear. |
drop_connections |
int
|
The next N calls to livery.forge.Checks.status or livery.forge.Checks.runs raise livery.forge.ForgeError with no status, as the client does when the server closes the connection without a response mid-poll. The next call answers. |
rate_limited |
int
|
The next N of those same calls raise
livery.forge.RateLimited, as a forge does once the
caller's API budget is spent; checked before
|
rate_limit_reset |
float | None
|
The reset time a |
Methods:
| Name | Description |
|---|---|
drop |
Raise the armed poll fault: a spent budget first, then a dropped one. |
drop ¶
drop(endpoint: str) -> None
Raise the armed poll fault: a spent budget first, then a dropped one.
Source code in packages/forge/src/livery/forge/testing/_fake.py
FakeForge ¶
FakeForge(*, user: str = 'fake-user', version: str = '1.0.0', capabilities: tuple[Capability, ...] = _ALL_CAPABILITIES, token: str = '', dispatch_names_run: bool = True)
A livery.forge.Forge that keeps everything in memory.
The protocol half behaves as the conformance suite demands. The
driver half simulates the world around the protocol: pushes, tags,
and CI runs finishing. Faults are injected through the faults
attribute; see livery.forge.testing.Faults.
Pull request and issue numbers count in separate spaces, as GitLab keeps them, so code that mixes the two fails here first.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
user
|
str
|
What livery.forge.Forge.whoami answers. |
'fake-user'
|
version
|
str
|
What livery.forge.Forge.server_version answers. |
'1.0.0'
|
capabilities
|
tuple[Capability, ...]
|
What livery.forge.Forge.supports answers True for. Defaults to every known capability; pass a subset to model a forge that declines some by name. |
_ALL_CAPABILITIES
|
dispatch_names_run
|
bool
|
Whether livery.forge.Checks.dispatch returns the id of the run it started, as every backend's answer names it. False answers None, as a GitHub or Gitea server without the run's details does. |
True
|
Build an empty forge for user with capabilities.
Methods:
| Name | Description |
|---|---|
whoami |
The configured user's login name. |
server_version |
The configured version string. |
registry_url |
A deterministic registry root per kind, for tests. |
supports |
Whether capability was granted at construction. |
repository |
The view onto one repository. Cheap, no existence check. |
set_members |
Test helper: what |
set_teams |
Test helper: what |
members |
Configured members; a namespace nobody configured is a user. |
teams |
Configured teams; a namespace nobody configured has none. |
codeowners |
The fake's dialect: a root |
user_url |
The address of login's profile under the |
set_protection |
Test helper: what Repository.protection answers for branch. |
review |
Test helper: record a submitted review on a pull request. |
create_repo |
Create the repository with an initialised default branch. |
get_repo |
The repository's settings, or None when it does not exist. |
delete_repo |
Delete the repository; a repository already gone is success. |
push |
Simulate a git push: a new head sha on branch, CI starting. |
branch_sha |
What branch points at, empty when there is no such branch. |
create_tag |
Simulate a tag push: tag at the default branch's head. |
start_runs |
Simulate a runner taking every queued run for sha; none settles. |
set_outcome |
Change what CI will do with every run for sha that has not settled. |
settle |
Simulate CI settling: every run for sha reaches its outcome. |
comment_bodies |
The comments posted on one pull request or issue, oldest first. |
Attributes:
| Name | Type | Description |
|---|---|---|
faults |
Faults
|
|
dispatch_names_run |
bool
|
|
budget |
RateBudget | None
|
|
token |
str
|
The credential this connection authenticates with; empty when anonymous. |
Source code in packages/forge/src/livery/forge/testing/_fake.py
token
property
¶
token: str
The credential this connection authenticates with; empty when anonymous.
registry_url ¶
registry_url(kind: RegistryKind, owner: str) -> str
A deterministic registry root per kind, for tests.
Source code in packages/forge/src/livery/forge/testing/_fake.py
supports ¶
supports(capability: Capability) -> bool
repository ¶
repository(owner: str, name: str) -> Repository
set_members ¶
set_teams ¶
members ¶
teams ¶
codeowners ¶
codeowners(entries: tuple[CodeownersEntry, ...]) -> Codeowners
The fake's dialect: a root CODEOWNERS, GitHub-shaped.
Source code in packages/forge/src/livery/forge/testing/_fake.py
user_url ¶
set_protection ¶
set_protection(owner: str, name: str, branch: str, protection: Protection) -> None
Test helper: what Repository.protection answers for branch.
Source code in packages/forge/src/livery/forge/testing/_fake.py
review ¶
review(owner: str, name: str, number: int, author: str, state: ReviewState) -> None
Test helper: record a submitted review on a pull request.
Source code in packages/forge/src/livery/forge/testing/_fake.py
create_repo ¶
create_repo(owner: str, name: str, *, private: bool = True, description: str = '') -> Repository
Create the repository with an initialised default branch.
Source code in packages/forge/src/livery/forge/testing/_fake.py
get_repo ¶
The repository's settings, or None when it does not exist.
Source code in packages/forge/src/livery/forge/testing/_fake.py
delete_repo ¶
push ¶
Simulate a git push: a new head sha on branch, CI starting.
Creates the branch when it is new, moves its head to sha
(a rig pairing the fake with a real repository passes the
real commit, so sha-keyed reads agree across the seam) or a
fresh deterministic one, and queues one run for that sha, as
a push trigger would. The run stays queued until
livery.forge.testing.FakeForge.settle applies outcome (a
hang outcome is released to success there, or cancelled
through the protocol). Returns the new head sha.
Source code in packages/forge/src/livery/forge/testing/_fake.py
branch_sha ¶
What branch points at, empty when there is no such branch.
The counterpart of livery.forge.testing.FakeForge.push, for a test that has to name a head it did not push: what a merge left on the base, which is the sha the base's own runs are filed under.
Source code in packages/forge/src/livery/forge/testing/_fake.py
create_tag ¶
Simulate a tag push: tag at the default branch's head.
start_runs ¶
Simulate a runner taking every queued run for sha; none settles.
Source code in packages/forge/src/livery/forge/testing/_fake.py
set_outcome ¶
Change what CI will do with every run for sha that has not settled.
A re-run reaches the outcome set here when it settles, so a rig can make the second attempt of a red run pass, as a flaky runner would.
Source code in packages/forge/src/livery/forge/testing/_fake.py
settle ¶
Simulate CI settling: every run for sha reaches its outcome.
A held (hang) run is released and concludes success, per
the driver contract. While
livery.forge.testing.Faults.wedge_status_queue holds, the
results are silently dropped and the runs stay queued, which
is what a wedged queue does to finished jobs. Settle again
after clearing the fault.
Source code in packages/forge/src/livery/forge/testing/_fake.py
comment_bodies ¶
comment_bodies(owner: str, name: str, number: int, *, kind: Literal['pr', 'issue']) -> tuple[str, ...]
The comments posted on one pull request or issue, oldest first.
Source code in packages/forge/src/livery/forge/testing/_fake.py
FakeDriver ¶
FakeDriver(fake: FakeForge | None = None)
The livery.forge.testing.ForgeDriver over a FakeForge.
The reference driver: it makes the conformance scenarios runnable with no server at all, and shows a real backend's test rig what it must supply.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fake
|
FakeForge | None
|
The forge to drive. A fresh full-capability one when omitted. |
None
|
Bind the driver to fake, creating one when omitted.
Methods:
| Name | Description |
|---|---|
unused_repo_name |
An owner and name no repository has yet. |
fresh_repo |
A new repository with an initialised default branch. |
push |
Push branch with outcome and return its new head sha. |
create_tag |
Create tag at the default branch's head. |
settle |
Apply every pushed outcome for sha; immediate on the fake. |
await_run |
The one run matching the filters; the fake never waits. |
comment_bodies |
The comments on one pull request or issue, oldest first. |
await_mergeable |
The fake computes mergeability synchronously: nothing to await. |
await_merged |
The fake merges inside settle: nothing to await. |
await_branch |
The fake is immediately consistent. |
await_issue |
The fake's listings are immediate: only verify the state. |
required_context |
The fake reports checks under the plain job name. |
Attributes:
| Name | Type | Description |
|---|---|---|
fake |
FakeForge
|
|
forge |
FakeForge
|
The forge under test. |
Source code in packages/forge/src/livery/forge/testing/_fake.py
unused_repo_name ¶
fresh_repo ¶
fresh_repo() -> Repository
A new repository with an initialised default branch.
Source code in packages/forge/src/livery/forge/testing/_fake.py
push ¶
Push branch with outcome and return its new head sha.
Source code in packages/forge/src/livery/forge/testing/_fake.py
create_tag ¶
settle ¶
Apply every pushed outcome for sha; immediate on the fake.
await_run ¶
The one run matching the filters; the fake never waits.
Raises AssertionError unless exactly one run matches, which is the driver contract.
Source code in packages/forge/src/livery/forge/testing/_fake.py
comment_bodies ¶
comment_bodies(repo_owner: str, repo_name: str, number: int, *, kind: Literal['pr', 'issue']) -> tuple[str, ...]
The comments on one pull request or issue, oldest first.
Source code in packages/forge/src/livery/forge/testing/_fake.py
await_mergeable ¶
The fake computes mergeability synchronously: nothing to await.
Source code in packages/forge/src/livery/forge/testing/_fake.py
await_merged ¶
The fake merges inside settle: nothing to await.
await_branch ¶
await_issue ¶
The fake's listings are immediate: only verify the state.