Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-image

Source of release 0.45.1

0.45.1 / docs / TESTING.md

# 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.