Crate zencodec_testkit

Expand description

Conformance test harness for zencodec codec implementations.

A codec crate adds this as a dev-dependency and runs the check_* functions against its own EncoderConfig / DecoderConfig to verify it honors the shared contract — especially the parts that are easy to get subtly wrong and expensive to ship wrong:

check_metadata_no_leak — a MetadataPolicy must never leak what it discards. The privacy guarantee.
check_cross_path_pixel_equivalence — every still encode/decode path (one-shot, push_rows + pull encode_from encode; one-shot, push-sink, streaming decode) must produce identical pixels.
check_animation_cross_path_equivalence — every animation decode path (borrowed, owned, push-sink) must yield identical frames, matching the input.
check_orientation_roundtrip — an orientation survives a keeping policy exactly once (no loss, no double-application).
check_color_context_consistency — whatever ColorContext a decoder attaches to its output buffers is class-valid (an ICC only rides a layout its device class describes) and identical across the one-shot, streaming, and animation (borrowed + owned) paths — strip/scratch buffers are where a context silently dies. Lenient about whether one is attached; check_color_context_attached is the strict, opt-in positive direction (a decoder that read colour back must attach it).
check_color_authority_spec — the ColorAuthority a decoder names in source_color is the one its format’s spec assigns for the colour fields it read back (PNG/JXL/HEIC: CICP outranks ICC; AVIF: MIAF order; the rest: ICC). check_source_color_authority is the unit form for a codec’s own fixtures, expected_color_authority the answer key.
check_native_hdr_roundtrip — when both ends declare hdr, BT.2100 PQ and HLG survive a PreserveExact round trip: the CICP, the HDR envelope (content light level + mastering display), 16-bit pixels where both ends are natively 16-bit, and the decoded buffer is labelled PQ/HLG rather than sRGB. Phase 0 of the gain-map/HDR delivery scope.
check_gain_map_roundtrip — the gain-map encode/decode contract: an undeclared encoder rejects with_gain_map_pixels loudly with UnsupportedOperation::GainMapEncode; a declared one embeds 1- and 3-channel maps (forward and backward direction) that a declared decoder reports from probe(), surfaces only on request (Components / with_extract_gain_map), never under the default BaseOnly, falls back honestly on ReconstructHdr without reconstructs_hdr, and that survive a decode → with_gain_map_pixels transcode. Phases 1, 2 (test matrix) and 4 (the testkit cross-path check) of that scope.
check_fidelity_honesty — resolved_target_fidelity() tells the truth: a declared lossless honours a Lossless request byte-exactly, a codec without lossy never reports Lossy (it promotes and says so), a codec with lossy never answers a lossy request with Lossless, and the legacy is_lossless() agrees. The cross-codec Fidelity contract.
check_inventory — a declared structural inventory covers every byte, reports appended junk as unconsumed, and survives every truncation.
check_capability_honesty — every declared capability works and every undeclared optional path cleanly returns UnsupportedOperation. Both directions for the structural paths and (where the decoder can observe them) the metadata channels, so a codec can’t claim a feature it lacks or hide one it has; see the fn docs for the exact per-flag scope.
check_decode_error_envelope / assert_uses_codec_error_envelope — a codec’s ErrorCategory and codec name survive dyn-dispatch type erasure (the At<CodecError> envelope contract). Opt-in, and not in check_all: only for codecs that return the envelope type Error (the testkit’s own reference is a Pattern-A foil that deliberately fails it).
check_decode_truncation_series — a truncated (incomplete) input must categorize as an incomplete-input category (never an Internal 5xx, an OutOfMemory, an Io error, or a caller-fault), and must never panic or silently decode a truncated header. Enforces the one part of the taxonomy that is broadly distinguishable. Opt-in, not in check_all; on the dyn-erased path a Pattern-A codec fails it the same way the envelope check does (the allowed/denied category policy is documented on check_decode_truncation_series).

check_all runs them all with default inputs — the one-call entry point.

The reference module ships a faithful codec (declares and honors every capability) the harness is validated against — it doubles as a worked example; an internal minimal codec (every optional capability declared false) validates the false-direction branches.

Re-exports§

pub use reference::RefError;
pub use reference::ReferenceDecoderConfig;
pub use reference::ReferenceEncoderConfig;
pub use reference::ReferenceZcrDecoderConfig;
pub use reference::ZCR_FORMAT;

Modules§

reference: A faithful in-memory reference codec.

Structs§

Failure: A conformance-check failure, naming the check and a human-readable detail.
PrefixCase: A meaningful prefix boundary, not a fraction of the total file length.
TestImage: A deterministic test image with contiguous (tightly-packed) rows.
TimingCase: One frame submission and its independent encoded result. Accepted frames have an expected native decode representation; this can differ from input for an explicitly lossy encode. Use distinct pixels to expose frame reordering.

Enums§

ExpectedError: A specific error that constitutes an expected refusal.
PrefixOutcome: Caller-specified expected result at a structural prefix boundary.

Functions§

assert_uses_codec_error_envelope: Statically assert a codec returns the shared At<CodecError> envelope from every encode/decode trait boundary — the Pattern-B error contract.
check_all: Run every conformance check with sensible default inputs, returning the first failure. The one-call entry point for a codec’s test suite; for control over image sizes or animation frames, call the individual check_* functions.
check_animation_cases: Strict counterpart to check_animation_timing: requires typed errors and verifies independently specified frame pixels, as well as duration and index. Accepted frames on both sides of a rejection expose timing/state corruption.
check_animation_cross_path_equivalence: Every animation decode path yields identical frames, matching the input.
check_animation_durations: Verify source timing through borrowed, owned and erased animation decoders. expected names every displayed frame; zero-duration compositing helpers belong in the codec fixture’s expected display sequence, not an inferred count. The sink API returns only OutputInfo, so cannot expose frame timing.
check_animation_streaming_output_honesty: Verify the AnimationOutputTiming an animation encoder’s begin reports.
check_animation_timing: Exercise exact or ordinary timing through both generic and erased encoders. Each pair is (requested, expected_encoded); None requires rejection. Include accepted frames before and after rejected inputs to detect state mutation. Expected rounded durations must come from the destination clock, independently of the codec/quantizer under test. At least two must succeed. For exact mode each successful duration must equal its request.
check_animation_timing_unsupported: Verify the conservative compatibility default for an animation adapter that has not adopted rational encoding. Both timing methods must reject with AnimationTiming, leave buffered frames intact, and allow legacy encoding to continue. A false timing capability must not silently quantize requests.
check_capability_honesty: Declared capabilities match real behavior.
check_color_authority_spec: Decoded colour authority follows the format spec on every metadata mix.
check_color_context_attached: A decoder that read colour back attaches it to the output buffer — the strict, positive direction of the decoded-buffer convention.
check_color_context_consistency: Whatever [ColorContext] a decoder attaches to its output pixels is class-valid and the same on every decode path.
check_cross_path_pixel_equivalence: Every advertised feeding mode produces identical pixels.
check_decode_error_envelope: A codec’s ErrorCategory and originating codec name survive dyn-dispatch type erasure — the runtime half of the Pattern-B contract.
check_decode_policy_admission: Verify checked decode-policy admission, typed rejection, and unchanged output after rejection. Supply explicit expected metadata to test supported metadata denials. All paths decode the same caller-provided fixture.
check_decode_prefix_cases: Exercise explicit complete-payload/truncation boundaries through one-shot and sink dispatch. Successful recovery must produce the expected pixels. The caller supplies strict/compatibility configuration separately. No prefix is silently omitted; out-of-range fixture boundaries are errors.
check_decode_truncation_series: A truncated (incomplete) input is categorized as incomplete client data — never mis-attributed as an internal bug, an OOM, an I/O error, or a caller fault — and never panics or silently decodes.
check_encode_policy_admission: Verify checked encode-policy admission and rejection atomicity. initial must be supported; request must match accepted. Decode observations must equal expected metadata, making preservation and denial explicit instead of treating a successful setter as proof of delivery. metadata is the unfiltered input. Color/fidelity observations remain codec-specific.
check_fidelity_honesty: The resolved Fidelity report is honest against the declared capabilities and against the pixels that actually come back.
check_gain_map_roundtrip: The gain-map encode/decode contract (docs/gainmap-pipeline-scope-2026-06-08.md Phases 1, 2 and 4, tracked in zencodec#24), for every declared/undeclared combination of EncodeCapabilities::gain_map and DecodeCapabilities::gain_map:
check_incremental_capability_honesty: Verify the incremental capability flag in both directions, then run check_incremental_contract on a declared incremental decoder.
check_incremental_contract: Exercise a decoder’s IncrementalDecode contract through the erased decoder callers receive (dyn_incremental_decoder), against the one-shot pixels of data:
check_incremental_decoder: check_incremental_contract for any decoder factory, against one_shot, the decoder’s one-shot decode of any bytes: for incremental decoders not reached through a codec’s DecoderConfig, such as one built with zencodec::helpers::WholeFileIncremental.
check_inventory: The structural inventory is honest and complete.
check_inventory_dispatch: Check inventory parity through generic and dynamic dispatch under the same configuration. Unlike check_all, erased config dispatch requires a 'static config. Native error types need no additional bounds.
check_inventory_input_limit: Verify the inventory input-byte boundary and typed errors in both dispatch paths. This is opt-in for inventory-enabled builds; disabled builds use check_inventory_dispatch. It does not equate a part cap with a memory cap.
check_metadata_no_leak: A retention policy never leaks what it discards.
check_metadata_rewrite: Exercise a codec’s metadata-only rewrite entry point with caller-owned fixtures. The observer must independently verify image payloads, timing, rendering metadata and requested retention (prefer a third-party reader). Checks plan materialization, report ranges, deterministic output, typed input, output and carrier limits, and pre-cancellation. Services are retained.
check_native_hdr_roundtrip: Native HDR survives a round trip: for BT.2100 PQ and HLG, the CICP, the HDR envelope (content light level + mastering display), the pixels, and the decoded buffer’s HDR labelling all come back from a PreserveExact encode → decode.
check_orientation_roundtrip: The displayed image is preserved through a policy that keeps orientation.
check_pixel_roundtrip: A round trip through one-shot encode → one-shot decode reproduces the input pixels exactly. The smallest sanity check; a failure here means nothing else is trustworthy.
check_read_at_contract: Verify a DynReadAt driver source against the bytes it claims to serve: length, exact reads at the edges and middle, one batched out-of-order multi-range read, and an error (never a short or zero-filled read) past the end.
check_seekable_capability_honesty: Verify the seekable capability flag in both directions. A decoder declaring it must decode data through push_decoder_from_source over a slice source with the same pixels as the one-shot path; one not declaring it must reject with UnsupportedOperation::SeekableDecode.
check_source_color_authority: A decoded SourceColor names the authority its format’s spec assigns.
check_streaming_output_honesty: Verify the OutputTiming an encoder’s begin reports, and EncodeCapabilities::streaming_output behind it.
expected_color_authority: The [ColorAuthority] a format’s specification assigns, given which colour fields the decoder actually read back.

Type Aliases§

Conformance: The result of a conformance check.