lardon3d/docs/development/testing.md

Testing

Status

DOCUMENTATION_LANGUAGE=ENGLISH
TEST_POLICY=HOST_AWARE
REPEATED_UNCHANGED_EXPENSIVE_VALIDATION=AVOID
TSAN_OPEN_CV_TBB_QUALIFICATION=REQUIRED
VULKAN_CONCURRENCY_VALIDATION=SEPARATE

Lardon3D uses Meson's test runner. Tests live under tests/ and combine unit, integration, persistence, restart, resource and real-path validation.

Normal commands

Run the configured suite:

meson test -C build --print-errorlogs

Run one named test:

meson test -C build <test-name> --print-errorlogs

Verbose execution:

meson test -C build -v --print-errorlogs

Re-run failures only:

meson test -C build --reprint=failed

Use the names registered by the current meson.build; this document does not maintain a second authoritative list of every test target.

Validation policy

Validation must match the change.

A documentation-only change normally requires:

git diff --check
targeted content checks
targeted link/authority review

It does not justify wiping and rebuilding unchanged code.

A code change normally requires, in increasing scope:

targeted build
targeted tests
broader affected suite
sanitizer or concurrency validation when relevant
full suite when the change or release boundary justifies it

Do not repeatedly rerun an unchanged expensive suite between documentation edits merely to create activity.

Host-aware parallelism

Build and test parallelism are host-aware.

Do not encode a project-wide fixed -j8, --num-processes 1, or equivalent constant as canonical policy.

The correct width depends on the current machine, interactive reserve, memory, toolchain and workload. Use all safe useful host capacity while preserving the defined interactive reserve.

RESOURCE_UTILIZATION_POLICY=MAXIMUM_SAFE_USEFUL_THROUGHPUT
SERIALISM_REQUIRES_PROOF=CANONICAL

If a temporary validation must be serialized for determinism, diagnosis or a known tool limitation, label that serialization as test-specific evidence rather than a global default.

Fresh build policy

Do not use meson setup --wipe by default.

Prefer:

meson setup --reconfigure build
meson compile -C build

Create or wipe a build directory when the configuration genuinely needs a fresh environment, for example:

different sanitizer set
portable Vulkan-off proof
Vulkan-on proof
compiler-family change
known stale/corrupt build directory
release-grade clean proof

Repeated wipes of the same unchanged configuration waste time and invalidate incremental-build advantages.

Sanitizers

ASan / UBSan

For memory, lifetime, ownership or undefined-behavior changes, use a dedicated sanitizer build.

Example configuration:

CC=clang CXX=clang++ meson setup build-asan -Db_sanitize=address,undefined
meson compile -C build-asan
meson test -C build-asan --print-errorlogs

Reconfigure or wipe only when the existing sanitizer directory does not match the requested configuration.

LeakSanitizer qualification

The retained global maintenance evidence must not be summarized as LSan 64/64.

The full first leak-enabled run exposed an externally attributed OpenCL loader leak and two timeout anomalies. The retained qualified result is:

ASan/UBSan full suite: PASS with detect_leaks=0
proved subset without the external loader: LSan PASS
full leak-enabled suite: not an unqualified PASS

Preserve that distinction in future reports unless new evidence supersedes it.

ThreadSanitizer

Concurrency changes require TSan where the instrumented boundary is meaningful.

The retained global maintenance TSan proof used GCC/G++ with Vulkan disabled and covered the selected concurrent targets plus deterministic repetitions.

The only retained suppression file is:

tests/tsan-opencv.supp

Its purpose is limited to external OpenCV/TBB objects. It must not suppress Lardon3D frames.

Therefore never report a blanket statement such as:

TSan proves the entire Vulkan build race-free

The valid qualification is:

project concurrent paths covered by the retained portable TSan matrix
external OpenCV/TBB reports qualified by the narrow suppression boundary
Vulkan concurrency validated separately

Vulkan validation

ORB Vulkan uses a separate validation boundary.

The retained global maintenance evidence includes a Vulkan-on build and suite on the real Radeon 780M/RADV host, plus dedicated backend/handle/publication tests.

That evidence is not interchangeable with TSan.

SIFT/RootSIFT feasibility results did not establish a production GPU backend; do not turn feasibility checks into production validation claims.

Determinism and repetition

Repeat tests when repetition proves something specific:

deterministic restart
race sensitivity
resource adaptation
ordering stability
flaky regression reproduction

Do not repeat unchanged tests without a stated purpose.

When repetition is the evidence, record:

exact test/corpus
run count
relevant configuration
success/failure count
digest or invariant when applicable

Test isolation

Tests should:

• own and clean up their temporary resources;
• avoid depending on another test's execution order;
• avoid network state unless the test explicitly owns that dependency;
• use synthetic/private Resource snapshots where the test is about deterministic policy rather than live host telemetry;
• avoid changing global process state without restoring it.

OpenCV thread configuration is process-wide and must be restored on every exit path in tests that change it.

Public-header validation

When a public C header changes, run a standalone C17 syntax probe in addition to normal build coverage.

Conceptually:

cc -x c -std=c17 -fsyntax-only -Iinclude -include lardon3d/<header>.h /dev/null

Use the current supported compiler matrix when the change affects ABI or C/C++ interoperability.

Source comments

Source comments explain non-obvious contracts:

invariants
ownership and lifetime
persistence ordering
resource boundaries
recovery behavior
scientific constraints

They should not paraphrase obvious code line by line.

Repository source comments are English.

Current retained global maintenance evidence

The canonical detailed record is:

docs/architecture/global_maintenance_audit.md
GLOBAL_MAINTENANCE_AUDIT=PASS/FROZEN

That historical checkpoint includes fresh portable/Vulkan builds, full suites, sanitizer work, TSan work, public-header probes, ABI/application-link checks and independent review.

It remains historical evidence. New changes require only the validation appropriate to the changed surface unless a new global checkpoint is being created.

Ticket closure checklist

Before closing a code ticket:

• confirm the requested scope only was changed;
• run git diff --check;
• run targeted tests for changed behavior;
• run the affected broader suite when justified;
• run ASan/UBSan for memory/lifetime-sensitive changes;
• run TSan for concurrency-sensitive project code when applicable;
• keep Vulkan validation separate from portable TSan claims;
• preserve exact external-library qualifications;
• avoid fixed host-parallelism constants;
• avoid repeated unchanged clean builds or suites;
• report what actually ran, not a stronger claim.

For documentation-only remediation, use documentation checks rather than rebuilding unchanged production code.