Create a Python 3.11 or newer environment and install the exact development dependency set:
python -m pip install -r requirements-dev.txt
python check.pycheck.py runs Ruff formatting, Ruff lint, strict Mypy, Pytest with statement and
branch coverage, and lightweight repository consistency checks. Coverage must be
at least 95% for the glitchcraft package.
Focused suites can be run with:
python -m pytest tests/test_effects.py tests/test_randomness.py
python -m pytest tests/test_contracts.py
python -m pytest tests/test_routes.py
python -m pytest tests/test_media.py
python -m pytest tests/test_image_assets.py tests/test_image_workflow.py
python -m pytest tests/test_storage_manifest.py tests/test_service_contract.py
python -m pytest tests/test_video_workflow.py
python -m pytest tests/test_telemetry.pyTests use synthetic NumPy frames and temporary directories. The narrowly marked FFmpeg integration test is skipped with an explicit reason when FFmpeg is not available. Pure engine tests never require FFmpeg, Node, Docker, or a browser.
Install the locked Node dependencies and Chromium once, then run the separate Playwright workflow:
npm ci
npx playwright install chromium
npm run test:browser
npm run review:ui-screensThe browser suite starts the Flask application and generates its image fixture in memory. It checks inline original/result rendering, no preview navigation, debounced newest-result behavior, explicit export/download, reset, keyboard operation, responsive containment at 320/768/1024/desktop widths, and axe results with no serious or critical violations. GitHub Actions keeps this browser job separate from the fast Python quality job.
Storage and video tests cover strict path and manifest validation, v1-to-v2 migration, atomic replacement, backup recovery, dual-manifest failure, concurrent thread mutations, restart-safe IDs, reconciliation, deletion rollback, cleanup, and public response redaction. Every application fixture overrides the data root, manifest, temporary folder, and legacy media locations with test-owned temporary directories. The video suite also covers FFprobe translation, finalizer cancellation, persistent job transitions/recovery, queue bounds, timestamp previews, and full, closed, open-ended, suffix, HEAD, and unsatisfiable byte-range responses.
Telemetry tests use an injectable fake monotonic/UTC clock—never real sleeps—to cover rolling and average FPS, ETA gating, unknown totals, stalled/stale work, progress clamping, queue repositioning, restart reconstruction, terminal summaries, and invalid/nonfinite inputs. A 1,000-callback test confirms runtime publication remains near four Hz and the rolling sample deque stays bounded. FFmpeg fixtures cover progress blocks, CRLF/LF, malformed fields, time fallbacks, interleaved progress/diagnostics, bounded stderr, cancellation, failure, and reader shutdown.
A local 10,000-callback microbenchmark on the development machine measured approximately 0.66 microseconds of telemetry-store overhead per frame callback. This is diagnostic rather than a cross-platform performance guarantee; the bounded/throttled behavior is the enforced contract.
The Playwright video fixture walks through queued, processing, stale, finalizing, verifying, saving, completed, cancel-pending, and canceled states. It checks concise formatting, keyboard-accessible details, ordered effects, previous-result retention, responsive containment, and Axe results without requiring a long render.
Focused-workspace browser coverage also checks metadata loading/failure/retry, preview retention during metadata failure, one isolated resolver failure, slow and stale resolver responses, disabled-effect selection, custom state across effect switches and reset, selection/request-count invariants, duplicate IDs, inert hidden panels, range geometry, six required viewport sizes, horizontal containment, performance marks, and Axe with no serious or critical findings.
npm run review:ui-screens generates 14 deterministic Chromium captures in
.tmp/ui-review/: six desktop states at 1440 x 900, one medium state at 1024 x 768, three
tablet views at 768 x 1024, and four mobile views at 390 x 844. The fixtures have stable
metadata, source identity, seed, schedule, preview artwork, telemetry, and output state.
The .tmp directory is ignored and screenshots must be inspected manually during UI review.
Recipe v1 golden regressions hash representative frames at indexes 0, 1, and 17 to prove the legacy RNG namespace and pixels remain exact. Temporal tests cover strict Recipe v2 parsing, rational conversion, every timing mode, event sorting and overlap rejection, clipping, event limits, schedule seed/ID isolation, restart recompilation, every envelope curve, intensity scaling for all eight effects, and random-access per-frame/per-event/smooth variation.
Pre-encode arrays prove Recipe v2 preview and sequential processing equivalence. The real FFmpeg/FFprobe test runs a Recipe v2 job through processing, H.264 finalization, AAC preservation, telemetry, and persisted timing metadata; its second Recipe v1 job verifies audio removal and legacy video compatibility. Playwright verifies video mode sends Recipe v2 while image mode sends Recipe v1, natural horizontal-glitch defaults, timing disclosure keyboard behavior, schedule summaries, active-preview feedback, responsive controls, existing job telemetry/cancellation, and no serious or critical Axe findings.
On the development machine, 200-iteration temporal benchmarks measured an eight-effect continuous compile at 0.32 ms and an eight-effect sporadic compile at 11.81 ms for 978 events. Ten thousand randomized timestamp probes across those eight sporadic plans averaged 1.91 microseconds per effect lookup. A one-hour 60 fps synthetic schedule containing 5,810 events compiled in 60.33 ms. These are diagnostic measurements, not platform guarantees; bounded event counts, one compile per job, binary-search lookup, and inactive-operation skipping are the enforced properties.
Resolver matrices cover all eight effects at Basic Intensity 0, 25, 50, 75, and 100. Round-trip inference, custom fields, duration bounds, strict APIs, metadata, accessibility, responsive layout, seed regeneration, schedule refresh, and existing Recipe v1/v2 regressions are covered. Benchmarks resolve and infer all eight profiles 10,000 times.
On the PR development machine, 80,000 individual resolutions completed in 4.454 seconds (55.676 µs per effect; 0.445 ms per batch of eight). After bounded candidate-cache warmup, 80,000 inferences completed in 20.133 seconds (251.658 µs per effect; 2.013 ms per batch of eight). Resolution performs no media decoding, FFmpeg work, or schedule compilation, and resolved recipes add no render-time overhead.
Run the focused Python and browser coverage with:
python -m pytest tests/test_motion_preview.py
npm run test:browser
npm run review:ui-screensMotion-preview tests cover strict v1 validation, fractional frame boundaries, verified exact seek, absolute source-frame execution, no-upscale geometry, active/ready deduplication, queue capacity, cancellation, TTL, count/byte LRU eviction, streaming leases, source invalidation, startup/shutdown cleanup, no-manifest mutation, API redaction, byte ranges, capability metadata, and all required interface states. Marked real-media coverage verifies the bounded silent H.264 profile with FFmpeg and FFprobe when installed.
The deterministic UI review now generates 24 captures, adding motion empty, queued, processing, ready, stale, failed, and canceled states across desktop, medium, tablet, and mobile layouts. Every capture is manually inspected for containment, hierarchy, readable status, and stable previous-media retention.
On the PR development machine, a representative no-effect three-second window from a 1280 × 720, 30 fps source completed in 1.340 seconds; the first processed frame was observed at 0.069 seconds. Ten thousand canonical cache-key builds averaged 23.81 microseconds, ready lookups 18.80 microseconds, initial admission 337.10 microseconds, and a ready-cache submission 112.10 microseconds. One actual ready-entry eviction took 218.90 microseconds. The redacted ready snapshot serialized to 932 bytes and the test clip to 34,297 bytes. These are representative diagnostics, not cross-platform timing guarantees. Bounds on queue, workers, clip duration, dimensions, FPS, stderr, snapshots, terminal history, cache entries, cache bytes, TTL, and media leases are the enforced requirements.