livery.toolroom.tools.testing¶
livery.toolroom.tools.testing ¶
Canned answers for bridge calls — toolroom's own test double.
The handles under test stay real. answers() swaps nothing above the
seam, so chaining, flag translation, the off sentinel, secrets
redaction, colour switches and input= consumption are all the
bridge's own, exercised exactly as a live call would exercise them.
Only execution is replaced: every call leaves through _host.run and
every version read through _host.probe, and for the span of the block
those two doors answer from a table instead of spawning.
from livery.toolroom.tools.testing import answers
with answers({
("uv", "tool", "list"): "hse-devkit v0.0.18\n- hse\n",
("git", "push"): 1,
}) as calls:
release() # code under test, real handles
assert calls[0].argv[:3] == ["uv", "tool", "list"]
Keys are argv prefixes, matched against the name-led spelling of each
call (git …, python … — never the resolved interpreter path); the
longest matching prefix wins, and a string key is split on whitespace
as a convenience. Values are the answer: a str is stdout with exit 0,
an int is an exit code, a Result sets the code and both streams. An
unmatched call succeeds silently — exit 0, empty streams — so
answers() with no table is a pure call recorder. A non-zero answer
takes the failing lane honestly: returned under nofail, raised
otherwise.
This is a different instrument from footman's recording(): a
recording is a rehearsal inside the real world (nothing executes,
everything succeeds, value reads opted recorded=False still answer
truthfully), where answers() replaces the world — version probes
included, which is why an unmatched probe refuses loudly instead of
answering empty. Nested inside a recording() block, answers() wins:
it intercepts upstream of footman, so its answers stand and the
recording sees nothing.
Classes:
| Name | Description |
|---|---|
UnservedAnswers |
A canned answer matched no call by the end of an |
Call |
One intercepted call: what would have run, and what was handed. |
Functions:
| Name | Description |
|---|---|
answers |
Answer every bridge call in the block from table, spawning nothing. |
UnservedAnswers ¶
Bases: Warning
A canned answer matched no call by the end of an answers() block.
An unmatched call is often incidental — the recorder default
exists for exactly that — but an unmatched table entry is a test
bug in the making: an answer was canned to steer the code under
test and never served, usually because the key was mis-spelt,
path-led where matching is name-led, or split into the wrong
tokens, and the test passes vacuously as if the entry did not
exist. A warning rather than an error so a deliberately shared
table (one fixture serving several tests, each exercising a subset)
can filter it; escalate it to a failure with -W error or a
filterwarnings mark where the table is per-test. A block that
exits on an exception is not warned — it already failed loudly.
Call ¶
Call(*, argv: Argv, raw: Argv, command: str, args: tuple[Any, ...] = (), kwargs: dict[str, Any] | None = None, env: dict[str, str] | None, opts: dict[str, Any], probe: bool = False)
One intercepted call: what would have run, and what was handed.
argv is the name-led spelling — raw tokens, assert-friendly.
raw is what would actually have spawned: resolved interpreter
path, forced colour switch and all (the same pairing footman's
steps keep as .command/.raw). command is the shown line,
values quoted and secrets redacted.
args and kwargs are the call as the caller wrote it,
pre-render: positionals verbatim (a Path stays a Path), and the
call keywords with False values included — the bridge omits a
False flag from the argv, the record must not, because "never
handed" and "handed, as False" are different facts and tests assert
on both. The rule of thumb: assert on kwargs for what the code
decided to pass, on argv for what would have run. .flags()
keywords are part of the handle, rendered into the verb path before
any call exists, so they show only in argv/raw; run policy
stays in opts.
env is the environment the call handed the seam (None
inherits); opts carries the rest of the run policy (nofail,
capture, input, cwd, timeout, …) exactly as it crossed.
probe marks a version read — a probe has no call of its own, so
its args/kwargs are () and {} by construction.
Methods:
| Name | Description |
|---|---|
__repr__ |
|
Attributes:
| Name | Type | Description |
|---|---|---|
__slots__ |
|
|
argv |
Argv
|
|
raw |
Argv
|
|
command |
str
|
|
args |
tuple[Any, ...]
|
|
kwargs |
dict[str, Any]
|
|
env |
dict[str, str] | None
|
|
opts |
dict[str, Any]
|
|
probe |
bool
|
|
Source code in packages/toolroom/src/livery/toolroom/tools/testing.py
__slots__
class-attribute
instance-attribute
¶
answers ¶
answers(table: Mapping[Any, Answer] | None = None, *, hosted: bool = False) -> Generator[list[Call]]
Answer every bridge call in the block from table, spawning nothing.
Yields the live list of Call records — assert on it after (or
during) the block. With hosted=True the block simulates the
hosted lane: _host.hosted answers True (so the bridge takes its
hosted paths — an in-process tool's callable is recorded, never
invoked), successes come back as footman's Result, and failures
raise footman's RunFailed — what code written for a footman task
returns and catches. The default speaks toolroom's own vocabulary:
Result back, ToolError raised.
The per-process installed_version cache is cleared for the block
and restored after it, so a canned version can neither be pre-empted
by a real read earlier in the process nor leak into later tests.
Not thread-safe: the seam is swapped module-wide for the duration.
A canned prefix that matched nothing by a clean block exit warns
(UnservedAnswers): an answer canned but never served is almost
always a mis-keyed prefix, and without the warning the test passes
vacuously. A block that exits on an exception is not warned — it
already failed loudly.
Source code in packages/toolroom/src/livery/toolroom/tools/testing.py
186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 | |