=======
Testing
=======

Running Tests
-------------

.. code-block:: bash

   make test          # all tests (needs libcfitsio-dev)
   make test-cal      # calibration tests only (no cfitsio)
   make test-zarr     # FITS conversion tests only

Test Categories
---------------

Unit Tests (cal-core)
~~~~~~~~~~~~~~~~~~~~~

Pure math functions with known inputs/outputs:

- Rayleigh-Jeans correction at various frequencies and temperatures
- Gamma computation from synthetic HOT/COLD counts
- Receiver temperature Y-factor
- Bad channel detection edge cases
- Flag bit operations
- Atmospheric transmission at known PWV
- Dump averaging with NaN padding

Integration Tests (cal-io)
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 25 40 35

   * - Test
     - Purpose
     - Data source
   * - ``parity_hfav``
     - Single-pixel HFAV OTF parity
     - Pre-converted Zarr v3
   * - ``parity_multi``
     - 7-dataset multi-mode parity
     - Pre-converted Zarr v3
   * - ``roundtrip``
     - L0 read → calibrate → L1 write → L1 read
     - Synthetic
   * - ``generate_l1_test_store``
     - Generate synthetic L1 for downstream tests
     - Synthetic
   * - ``concurrent_write``
     - Parallel Zarr write safety
     - Synthetic
   * - ``vectorize_crosscheck``
     - Per-pixel vs vectorized path agreement
     - Pre-converted Zarr v3
   * - ``dump_parity_data``
     - Export per-channel stats for analysis
     - Pre-converted Zarr v3

Conversion Tests (zarr-fits-core)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- Filename parsing regex (standard, relative, simple patterns)
- FITS value parsing (bool, int, float, string)
- Profile auto-detection

Parity Methodology
------------------

The parity tests compare the engine's output against golden reference
CSVs produced by the legacy kalibrate C++/Fortran code. For each
dataset:

1. Load L0 Zarr store (pre-converted from test FITS data)
2. Calibrate with ``KalibrateCompat`` physics constants
3. Compare mean :math:`T_{rec}` per pixel against reference CSV
4. Assert deviation < 1% (acceptance threshold)

The ``KalibrateCompat`` physics mode reproduces the exact
``h/k = 0.047995`` K/GHz constant and f32 truncation behaviour of the
legacy code.

Test Data
---------

Test data lives in ``kalibrate_test_lib/`` (sibling directory):

- ``data_fits/`` — 18 original FITS observation files
- ``data_zarr_v3/`` — 10 pre-converted Zarr v3 stores
- ``reference_data/`` — 33 golden CSVs + ATM table