AetherPrismCore / Reference
Testing
What PrismCore's 778-test suite covers, how to run it, the opt-in real-media and benchmark harnesses, fuzzing, and the prismcore-cli tool for reproducing field reports.
The suite
PrismCore 3.5.4 has 778 tests in 111 suites (Swift Testing), in Tests/PrismCoreTests/. 23 of them are parameterized, so a run executes more test cases than that. The suite is hermetic apart from a handful of opt-in harnesses: it drives the real engine end to end against synthetic fixtures and scripted local HTTP origins, with no network access.
| Area | Tests | What it pins |
|---|---|---|
| Routing and probing | 118 | Engine routing rules, AV1 hardware gating, HEVC/AVC/AV1 CODECS strings, master playlist construction, container layout and structure export, open hints, probe reuse, chapters, the FFmpeg build report, the HDR10+ scout |
| Video, HDR and Dolby Vision | 79 | hvcC normalization, HEVC NAL framing, Profile 7 → 8.1 declaration, Dolby Vision and Atmos signalling (CHANNELS="16/JOC", dec3 in the served init), parameter-set harvesting, deinterlacing, master-rejection fallback tiers, display criteria |
| Audio | 102 | The bridge's decode → resample → FIFO → encode chain through whichever encoder the linked FFmpeg has, every standard layout reaching AAC without a PCE, lazy bridged renditions, dialogue boost, runtime audio delay, cached audio, preferred-language matching |
| Subtitles and captions | 122 | Text conversion and placement, WebVTT and forced renditions, bitmap renditions and OCR arming, the cue-tap history bounds, CEA-608 decoding and CLOSED-CAPTIONS signalling |
| Planning, seeking and demand | 116 | Segment plans and their witnesses, the keyframe cache and its identity, late index loads, demand-driven production and re-anchoring, the re-anchor timeline, DTS backfill and timestamp repair, the sliding window, retention, seek previews |
| Serving and network | 77 | The loopback server and its hardening, LAN reachability and the session token, coordinated HTTP (including a memory-growth guard), read interruption, custom inputs, prewarm |
| Sessions and diagnostics | 105 | Remux integration, first-segment readiness, clones, startup checkpoints, the error taxonomy, producer recovery, playback events, the diagnostic report and the version pin, CLI stop handling |
| Software path | 46 | Software decode, the playback pipeline against renderer stand-ins, audio track switching, text subtitle selection, the audio clock |
| Fuzz smoke | 3 | Every fuzz target over random inputs and seed mutations |
| Opt-in harnesses | 10 | Real media, rendered seeking and startup benchmarks (below) |
End-to-end tests serve a remuxed fixture over the loopback server and read it back — re-probing the served master through libavformat's own hls demuxer, decoding served segments, and bringing items to .readyToPlay in a real AVPlayer.
What a test cannot prove. The fixtures are synthetic (testsrc2 video and sine-wave audio generated with ffmpeg, committed under Tests/PrismCoreTests/Fixtures/). They prove the pipeline, never the premium claims: Atmos objects and real Dolby Vision RPUs need real media and a device. Whether a frame reached a display, or an audio switch was inaudible, is a device question.
Running it
git clone https://github.com/Wenzlik/PrismCore.git
cd PrismCore
git checkout 3.5.4
swift testSome tests need Xcode's toolchain rather than the Command Line Tools. A missing
Testing.frameworkat run time means exactly this:DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer swift test
--filtermatches function and type names, not the@Test("…")display titles. Filtering on a title silently runs nothing ("No matching test cases were run"). Filter on a type to run a whole suite file:swift test --filter KeyframeIndexCacheTests.- A few tests are platform-gated: CLI stop handling runs on macOS only, and the OCR tests need Vision.
Opt-in harnesses
Gated on environment variables so the default run stays hermetic:
| Variable | Runs | Needs |
|---|---|---|
PRISMCORE_MEDIA | RealMediaVerificationTests — real-media probe and Dolby Vision verification, including Profile 7 → 8.1 | A real file, e.g. a Dolby Vision MKV |
PRISMCORE_PGS_MEDIA | RealMediaPGSTests — the OCR subtitle pipeline | A file with a PGS track (no FFmpeg build can encode PGS, so there is no committed fixture) |
PRISMCORE_HDR10PLUS_MEDIA | RealMediaHDR10PlusTests — the HDR10+ scout on a real encode | A path or http(s) URL |
PRISMCORE_RENDERED_SEEK=1 | RenderedSeekTests — reads decoded frame numbers after seeks through a throttled, range-capable origin | A Mac with AVFoundation rendering |
PRISMCORE_BENCH | StartupCostBenchmark, StartupCheckpointBenchmark — startup cost | A path or http(s) URL (measure over HTTP, not a mounted share) |
PRISMCORE_MEDIA=/path/to/film.mkv swift test --filter RealMedia
PRISMCORE_RENDERED_SEEK=1 DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer \
swift test --filter pictureMatchesPlayerClockAfterSeeksThe benchmark also reads PRISMCORE_BENCH_COORDINATED_HTTP=1, PRISMCORE_BENCH_PREWARM=1, PRISMCORE_BENCH_KEYFRAME_CACHE=<dir> and PRISMCORE_BENCH_PROBE_BUDGET_SECONDS. Scripts/proxy-model-server.py models a host's local range proxy for it:
python3 Scripts/proxy-model-server.py movie.mkv 8732
PRISMCORE_BENCH=http://127.0.0.1:8732/movie.mkv swift test --filter checkpointLineBenchmark over HTTP with a server that supports Range: a local mount hides exactly the cost a host pays (and python3 -m http.server does not answer ranges).
Fuzzing
Every hand-written bitstream parser is a fuzz target with wrong-answer invariants, not just crash detection: eac3-syncframe, dec3, hevc-nalunits, hvcc-normalize, isobmff-patch, text-subtitles, a53-captions, container-layout and hdr10plus-sei.
FuzzSmokeTestsruns every target in the normal suite — deterministic and sub-second.swift run prismcore-fuzz hunt <target|all> [seconds] [rng-seed]— blind mutation of the seed corpus for a bounded time (60 s by default); it prints its seed so any crash reproduces.swift run prismcore-fuzz run <target> <files…>— replays saved inputs.
Coverage-guided fuzzing with libFuzzer needs a swift.org toolchain (Xcode's has no fuzzer runtime):
swift build --product prismcore-fuzz \
-Xswiftc -DLIBFUZZER -Xswiftc -parse-as-library \
-Xswiftc -sanitize=fuzzer,address
PRISMCORE_FUZZ_TARGET=dec3 .build/debug/prismcore-fuzz corpus/The command-line tool
prismcore-cli runs the engine on one source on a Mac:
swift run prismcore-cli probe <url-or-path> # SourceInfo, structure, routing verdict and reason (--json: the diagnostic report)
swift run prismcore-cli serve <url-or-path> # a loopback playlist URL for Safari or QuickTime
swift run prismcore-cli bench <url-or-path> # the startup checkpoint line a host logs
swift run prismcore-cli segverify <url-or-path> # decode every served segment on its own
swift run prismcore-cli validate <url-or-path> # Apple's mediastreamvalidator, if installedCommon options: -H "Name: value" (repeatable request headers), --coordinated-http, --budget SECONDS, --display sdr|hdr|dv and -v. serve and segverify take --report FILE and write the session's diagnostic report on exit, a failed start included. validate needs Apple's HTTP Live Streaming Tools and exits 0 with a notice without them (unless --require-validator). --help lists everything.
The CLI does not replace a device run: the tvOS display handshake, Dolby Vision on a real panel and Atmos passthrough can only be checked on hardware.
How these docs are tested
This site builds every Swift snippet in these pages against PrismCore 3.5.4 — the install snippet's Package.swift is the manifest — for macOS, and the tvOS-only ones for the tvOS Simulator. It also checks that every PrismCore symbol a snippet names exists in the 3.5.4 API.