dymokomi/luce-image
Source of release 0.45.1
# Tests and toolchains
Prerequisites: the development toolchain (`luc`, `luce`, `luce-base` from luce-base's
`tools/toolchain.py`), Python with venv/pip, and the test-only packages in
`tests/requirements.txt`.
```sh
python3 -m venv build/test-env
build/test-env/bin/python -m pip install -r tests/requirements.txt
luc test
```
`luc test` runs every module's test blocks and the program `tests/oracles`, which runs
`gate.py` with the Python of `build/test-env` (or `python3`): it builds the drivers once,
natively, and compares them with the oracles. Without the oracle packages it skips.
## Gates
- Base unit tests: official hash vectors, exponent remapping, malformed JSON,
Unicode/surrogate pairs, all finite HALF encodings and infinities, rounding ties,
bounded-buffer failure. The Base `test` CLI supports backend but not optimization
flags; these run once per backend.
- Both Base codec drivers and real Luce consumers rebuild for every selected
compiler mode. Tests use fresh temporary input/output directories.
- 40 independent DEFLATE cases against Python zlib.
- 100 PNG/TIFF cross-reader/writer cases, including Base re-reading its own output.
- 150 PNG bit-depth/color/filter/Adam7/transparency cases against libpng.
- 296 TIFF sample type/byte order/planar/tile/compression/predictor cases against
tifffile/imagecodecs, plus 16 orientation/layout cases.
- 83 JPEG sequential/progressive/subsampling/restart/CMYK/YCCK cases against Pillow.
Pixel tolerance accounts for different legal IDCT/upsampling rounding.
- 131 EXR upstream cases including every offered output compression, forced
compressed PIZ (not just raw fallback), PXR24, HALF/FLOAT/
UINT, mixed-type multipart/tiled files and nonzero data windows.
- Real Luce `Image` ownership, operations and four-format I/O tests; transactional
TIFF page/EXR part seek and retained limits.
- 605 truncated/random/mutated assets: subprocess timeout, bounded decoding,
recoverable errors instead of crashes/traps. A mutation that remains valid may
succeed. This is deterministic regression fuzzing, not exhaustive fuzz coverage.
The libpng oracle currently prints an interlace-handling warning on Adam7 cases;
its resulting pixels are still checked. It is not a warning from luce-image.
## Sanitizers
The same Base implementation can be emitted as C and instrumented with Clang;
this is not a native codec backend. For example, from the repository root:
```sh
LUCE_BASE="$PWD/build/toolchain/luce-base" build/toolchain/luce build tests/validate.luc --emit=c -o build/validate-sanitized.c
cc -std=gnu11 -O1 -w -fno-strict-aliasing -fsanitize=address,undefined -fno-omit-frame-pointer -I ../luce-base/runtime build/validate-sanitized.c ../luce-base/runtime/lucb_rt.c -lm -pthread -o build/validate-sanitized
ASAN_OPTIONS=detect_leaks=0:halt_on_error=1 UBSAN_OPTIONS=halt_on_error=1 build/test-env/bin/python tests/check_malformed.py --validator build/validate-sanitized
```
This checks memory access and undefined behavior on the mutation corpus. Leak
detection is disabled in this macOS recipe; it is not a leak-cleanliness claim.
## Performance
```sh
build/test-env/bin/python tools/benchmark.py --size 1024
```
The script creates deterministic float32 RGB TIFF/EXR fixtures using independent
writers, compiles the Base benchmark with native opt 3, and reports median open
and decode times from three fresh processes each at 1/2/4 threads. File I/O and
decoding are reported separately. Run with no concurrent test/compiler jobs.
`workers_used` reports how many threads the decode was spread over. Results are host/workload
observations, not promises of a fixed speedup.
See [recorded measurements](BENCHMARK.md).
## CI
The GitHub workflow runs on Apple Silicon macOS and x86_64 Linux, bootstraps the
pinned sibling languages, and executes the full matrix. If language repositories
are private, configure `LUCE_READ_TOKEN` with read-only Contents access to both;
the default workflow token cannot read unrelated private repositories.
`tests/regressions/` contains intentionally failing compiler reproducers and is
not part of the package's green gate. Run these separately when auditing/fixing
the language; package-local workarounds keep the image library usable meanwhile.