LTX2.5-Studio / tests /test_errors_fork_boundary.py
techfreakworm's picture
feat: every result carries a structured run record and every failure a category, so the UI renders facts instead of parsing sentences
c08d3e8 unverified
Raw History Blame Contribute Delete
13.7 kB
"""The fork-boundary contract: our errors must survive a ZeroGPU worker.
docs/SPACE_MODE_MATRIX.md Β§4 measured what happens without this. On ZeroGPU
every ``@spaces.GPU`` call runs in a forked worker, and ``spaces`` transmits
the raised exception *object* back to the parent only when ``isinstance(exc,
gr.Error)`` β€” everything else is reduced to its class name, so a fully
diagnosed ``DecodeError(reason=...)`` reached a live user as the eleven
characters ``'DecodeError'``. And the object travels over a
``multiprocessing.Queue``, so eligibility without picklability is *worse* than
nothing: the worker catches the ``PicklingError`` and ships that instead, and
the user loses even the class name.
So the fix is a pair, and this file pins both halves independently:
* every class in the hierarchy IS a ``gr.Error`` (eligibility);
* every class round-trips pickle preserving class, message and attributes
(survival). Losing either half re-fails a test here by name.
It also pins what the pair must NOT change: ``str(exc)`` stays byte-identical
to the pre-gr.Error hierarchy (gr.Error's own ``__str__`` repr-quotes the
message β€” the single quotes around ``'DecodeError'`` on the Space were exactly
that), and ``ui.render.failure`` shows the message verbatim, before *and after* a
round trip β€” the after case being precisely what the parent process renders.
Discovery is programmatic. The classes are walked out of the module, split
into grouping bases and concrete leaves *structurally* (a base is a class
another discovered class subclasses), and construction recipes come from
``test_errors.ERROR_SPECS`` β€” whose own coverage test already refuses any new
class that lacks a recipe. A 28th error class therefore lands in this suite
automatically; it cannot dodge by not being hand-listed here.
Everything in this file is offline and costs zero GPU (PLAN Β§9.1).
"""
from __future__ import annotations
import html
import inspect
import pickle
import gradio as gr
import pytest
from test_errors import ERROR_SPECS
from ltx25_studio import errors
from ltx25_studio.ui import render
# --------------------------------------------------------------------------
# programmatic discovery β€” no hand-list for a new class to dodge
# --------------------------------------------------------------------------
DISCOVERED = {
name: obj
for name, obj in inspect.getmembers(errors, inspect.isclass)
if obj.__module__ == errors.__name__
and issubclass(obj, errors.LTXStudioError)
and not name.startswith("_")
}
#: A grouping base is structural, not declared: some *other* discovered class
#: subclasses it. Concrete leaves are everything else, and every leaf must
#: have a construction recipe in ERROR_SPECS or ``_construct`` fails loudly.
GROUPING_BASES = {
name
for name, cls in DISCOVERED.items()
if any(other is not cls and issubclass(other, cls) for other in DISCOVERED.values())
}
def _construct(name):
cls = DISCOVERED[name]
spec = ERROR_SPECS.get(name)
if spec is not None:
return cls(**spec[0])
assert name in GROUPING_BASES, (
f"{name} is a concrete error with no construction recipe β€” add it to "
f"test_errors.ERROR_SPECS so the fork-boundary contract covers it"
)
# Bases carry no keyword contract; a plain message exercises the same
# __init__/__str__/__reduce__ path the leaves inherit.
return cls(f"synthetic {name} message for the fork-boundary suite")
def test_discovery_found_the_whole_exported_hierarchy():
"""The walk and ``__all__`` must agree in both directions: an exported name
that is not in the hierarchy, or a hierarchy class that is not exported,
is a class this suite would silently miss. The failure-category API is the
only non-error export."""
category_api = {*(name.upper() for name in errors.CATEGORIES), "CATEGORIES", "Failure"}
category_api |= {"categorise", "is_out_of_memory"}
assert set(DISCOVERED) == set(errors.__all__) - category_api
# --------------------------------------------------------------------------
# half one β€” eligibility: the object is only transmitted if it IS a gr.Error
# --------------------------------------------------------------------------
@pytest.mark.parametrize("name", sorted(DISCOVERED))
def test_every_error_is_a_gradio_error(name):
"""``spaces`` populates ``ExceptionResult.gradio_error`` only for
``isinstance(exc, gr.Error)``; any class that loses this property is
reduced to its bare name in transit again."""
assert issubclass(DISCOVERED[name], gr.Error)
assert isinstance(_construct(name), gr.Error)
def test_the_hierarchy_still_roots_at_ltxstudioerror():
"""``ui/render.py`` branches on ``isinstance(exc, LTXStudioError)`` β€” the
gr.Error graft must not loosen the family the UI catches."""
for name in sorted(DISCOVERED):
assert issubclass(DISCOVERED[name], errors.LTXStudioError)
def test_the_valueerror_widening_is_known_and_audited():
"""gr.Error derives from gradio's ``AppError``, which derives from
``ValueError`` β€” so this inheritance makes every error here a ValueError.
That widening was audited (every ``except ValueError`` in the package
guards stdlib parsing or ``inspect.signature``; ``lora/apply.py``
re-raises ``LoRAError`` first). This test pins the fact so a future
gradio bump that moves gr.Error's base is noticed, not discovered."""
assert issubclass(errors.LTXStudioError, ValueError)
# --------------------------------------------------------------------------
# half two β€” survival: the transmitted object must cross a pickle boundary
# --------------------------------------------------------------------------
@pytest.mark.parametrize("name", sorted(DISCOVERED))
def test_pickle_round_trip_preserves_class_message_and_every_attribute(name):
"""22 of 27 classes were measured unpicklable before ``__reduce__``:
keyword-only constructors versus a one-tuple ``args`` that pickle feeds
back positionally. Class identity, ``args``, and the full instance dict
(mode, reason, message, print_exception β€” all of it) must survive."""
exc = _construct(name)
back = pickle.loads(pickle.dumps(exc))
assert type(back) is type(exc)
assert str(back) == str(exc)
assert back.args == exc.args
assert vars(back) == vars(exc)
@pytest.mark.parametrize("name", sorted(GROUPING_BASES))
def test_bases_round_trip_bare_too(name):
"""The five grouping bases were the only picklable classes before; raised
bare they must stay picklable β€” with ``args == ()`` intact, not swapped
for gr.Error's ``"Error raised."`` default."""
back = pickle.loads(pickle.dumps(DISCOVERED[name]()))
assert type(back) is DISCOVERED[name]
assert back.args == ()
assert str(back) == ""
# --------------------------------------------------------------------------
# what the pair must NOT change: the words
# --------------------------------------------------------------------------
#: str() snapshots taken from the hierarchy BEFORE it inherited gr.Error, at
#: the exact kwargs ERROR_SPECS uses. Byte-identical means byte-identical: a
#: leading quote here is gr.Error's repr-``__str__`` leaking through, and it
#: would repr-quote every rendered error detail across the whole UI.
PRE_CHANGE_STR = {
"DecodeError": "decoding failed for mode 'text_to_video': pipeline returned no frames.",
"ConfigError": (
"LTX25_TRANSFORMER_PRECISION='fp4' is not a recognised value. Legal values are: "
"bf16, fp8. Refusing to fall back to a default silently -- set the variable "
"correctly or unset it."
),
"DimensionError": (
"width=700 is not divisible by 32. LTX-2.5 requires every spatial dimension to be "
"a multiple of 32. Use 672 or 704 instead."
),
"ModelLoadError": "failed to load pipeline component 'transformer': connection reset by peer.",
"EmptyOutputError": (
"generation for mode 'text_to_video' finished without producing "
"/tmp/run-abc/video.mp4. Reporting this rather than returning an empty result."
),
"LoRANotAttachedError": (
"LoRA /tmp/adapter.safetensors loaded as adapter 'user_lora' but attached to zero "
"modules of transformer, connectors. The adapter is almost certainly built for a "
"different architecture; applying it would silently produce base-model output."
),
}
@pytest.mark.parametrize("name", sorted(PRE_CHANGE_STR))
def test_str_is_byte_identical_to_the_pre_gradio_hierarchy(name):
assert str(_construct(name)) == PRE_CHANGE_STR[name]
@pytest.mark.parametrize("name", sorted(DISCOVERED))
def test_no_error_str_is_repr_quoted(name):
"""The class-wide version of the snapshot check: no message may pick up
gr.Error's quoting, before or after crossing the boundary."""
exc = _construct(name)
for obj in (exc, pickle.loads(pickle.dumps(exc))):
assert not str(obj).startswith(("'", '"'))
def test_root_arity_semantics_match_plain_exception_exactly():
"""gr.Error would absorb a second positional into ``duration`` and turn
zero args into ``"Error raised."``; the root suppresses both so str/args
behave as the plain-Exception hierarchy always did."""
assert str(errors.LTXStudioError()) == ""
assert errors.LTXStudioError().args == ()
assert str(errors.LTXStudioError("boom")) == "boom"
assert str(errors.LTXStudioError("a", "b")) == "('a', 'b')"
assert errors.LTXStudioError("a", "b").args == ("a", "b")
def shows(message: str, rendered: str) -> bool:
"""The message reaches the user as written: verbatim, or HTML-escaped (the
browser shows the same text either way)."""
return message in rendered or html.escape(message) in rendered
@pytest.mark.parametrize("name", sorted(PRE_CHANGE_STR))
def test_render_failure_carries_the_message_and_survives_the_round_trip(name):
"""``ui/render.py::failure`` must show the error's own message verbatim, and
-- the point of the whole fix -- must render the *same* card for the object
the parent process unpickles as for the object the worker raised.
Format-agnostic on purpose: the card's headline and layout belong to the UI
and are pinned in its own tests."""
exc = _construct(name)
rendered = render.failure(exc)
assert shows(PRE_CHANGE_STR[name], rendered), rendered
assert render.failure(pickle.loads(pickle.dumps(exc))) == rendered
def test_a_foreign_gradio_error_renders_its_own_text():
"""The platform's own errors (``'GPU task aborted'`` and friends) are
gr.Error instances that are NOT LTXStudioError. Whatever card they get, the
platform's text must reach the user verbatim, before and after a round trip."""
exc = gr.Error("GPU task aborted")
rendered = render.failure(exc)
assert shows("GPU task aborted", rendered), rendered
assert render.failure(pickle.loads(pickle.dumps(exc))) == rendered
# --------------------------------------------------------------------------
# the spaces contract, simulated end to end β€” zero GPU
# --------------------------------------------------------------------------
def test_the_spaces_marshalling_contract_end_to_end():
"""Replays ``spaces/zero/wrappers.py`` step by step (read at 0.48.3):
``exception_result`` gates on ``isinstance(exc, gr.Error)`` and normalises
``print_exception``; the queue crossing is a pickle round trip (a
``multiprocessing.Queue`` serialises with pickle β€” an in-process dumps/
loads exercises the identical path deterministically); the parent reads
``print_exception``, prints the worker traceback while it is truthy, sets
it False and raises the object. Every step must hold or the user is back
to ``'DecodeError'`` β€” or worse, ``'PicklingError'``."""
exc = errors.DecodeError(
mode="video_to_video",
reason="the pipeline raised ValueError('bad frames')",
)
# worker: exception_result() β€” the eligibility gate
assert isinstance(exc, gr.Error), "gradio_error would be None; only the class name travels"
gradio_error = exc
gradio_error.print_exception = getattr(gradio_error, "print_exception", True)
# worker β†’ parent: res_queue.put(res) β€” the survival gate
reconstructed = pickle.loads(pickle.dumps(gradio_error))
# parent: print the traceback (print_exception is True β€” deliberately, so
# the Space log keeps the channel Β§3's diagnosis actually came through),
# then flip it and raise the real object
assert isinstance(reconstructed, gr.Error)
assert reconstructed.print_exception is True
reconstructed.print_exception = False # the parent's own mutation must work
# what arrives is our object, saying our words
assert type(reconstructed) is errors.DecodeError
assert isinstance(reconstructed, errors.LTXStudioError)
assert reconstructed.mode == "video_to_video"
assert reconstructed.reason == "the pipeline raised ValueError('bad frames')"
assert str(reconstructed) == (
"decoding failed for mode 'video_to_video': the pipeline raised ValueError('bad frames')."
)
def test_print_exception_defaults_true_for_the_whole_hierarchy():
"""Deliberate, not inherited by accident: the spaces parent prints the
worker's full traceback to the Space log only while the transmitted
error's ``print_exception`` is truthy. That log line is how the one real
generation defect this Space has had was diagnosed; suppressing it would
re-close the channel."""
for name in sorted(DISCOVERED):
assert _construct(name).print_exception is True, name