Testing and Source Checks

Testing and Source Checks

Halo Vision's regression suite is source-only: it needs no game files, signing, device or installation. A single driver, tools/run_source_checks.py, runs the repository hygiene audit, Python unit tests, and then compiles and executes roughly one hundred small C, Objective-C and Swift fixtures directly with clang/swiftc. Most fixtures #include the production translation unit (for example ../d3d9.c or ../metalrenderer.m) so the test cannot drift from the shipped code, replace only the outermost dependencies with fakes, and print PASS ... or abort on an assert. Fixtures that compare native rewrites against the lifted original engine print SKIP when the locally generated engine sources are absent. A macOS GitHub Actions workflow runs the portable subset normally and with AddressSanitizer/UndefinedBehaviorSanitizer. This page lists every check the driver runs, every test file in the repository, how skips and environment overrides work, and how to add a new test.

Source files

File	Role
tools/run_source_checks.py	The suite driver.
.github/workflows/source-checks.yml	CI: strict hygiene, portable suite, portable suite with sanitizers.
tools/check_repository_hygiene.py	Path/content privacy audit (see Release Process and Hygiene).
tools/check_probe_runner_exit.py	Executes the reporting tail of probe_engine_menu_input.py with controlled child outcomes.
tools/check_core_telemetry_xros.py	Compiles and links (never runs) a telemetry probe for xrOS 26.0.
tools/benchmark_x87_rotating_stack.py	Compares translated leaves under the rotating and shifting x87 layouts; --check-only in the suite.
native/EngineHost/tests/, native/EngineVision/Tests/, native/Tests/, tools/test_*.py, tools/engine_reuse/test_*.py	The fixtures catalogued below.

Running

python3 tools/run_source_checks.py                    # everything available on this machine
python3 tools/run_source_checks.py --portable-only    # skip GPU, Objective-C, Swift and Mac-only fixtures
python3 tools/run_source_checks.py --sanitize         # build C fixtures with -O1 -g -fsanitize=address,undefined

Option	Effect
--portable-only	Sets mac = False even on macOS: only the 32 portable C fixtures plus the always-run extras execute. Without it, mac is platform.system() == 'Darwin'.
--sanitize	Replaces -O2 with -O1 -g -fsanitize=address,undefined -fno-omit-frame-pointer for every clang build in the suite (not for swiftc), and passes --sanitize to the x87 benchmark (which then disables timing).

Mechanics (run_source_checks.py:31-33, 92-118):

• Every command is echoed with + and run with cwd at the repository root, check=True, and a 120 s timeout. Any nonzero exit stops the suite with a CalledProcessError.
• Binaries are built in a temporary directory halo-source-checks-* that is removed at the end.
• C fixtures are compiled as $CC [flags] -pthread -DENGINE_FLAT_MEMORY=1 -I native/EngineHost -I native/EngineReuse native/EngineHost/tests/test_<name>.c <extra sources and flags> -lm -o <tmp>/<name>; CC defaults to clang.
• The final line is PASS <N> C checks and more (plus "mock Objective-C, Metal and Swift checks" on a Mac) "; no headset validation implied". N counts only the compile-loop cases: 32 with --portable-only, 59 on a Mac. These are the "32 C targets" and "59 C checks" figures quoted in VALIDATION.md.

flowchart TD
    A["run_source_checks.py [--portable-only] [--sanitize]"] --> P1["Phase 1: hygiene audit + 8 Python test scripts"]
    P1 --> G["generated_engine(): locate local sub_*.c (optional)"]
    G --> P2["Phase 2: 32 portable C fixtures (compile + run each)"]
    P2 --> M{"mac = Darwin and not --portable-only?"}
    M -->|yes| P3["Phase 3: 27 Mac-only C fixtures"]
    M -->|no| P4
    P3 --> P4["Phase 4: runtime contract, x87 layout check, native leaves x2, native gather, gather pipeline"]
    P4 --> M2{"mac?"}
    M2 -->|yes| P5["Phase 5: ObjC / Metal / Swift fixtures, xrOS link check, translated voice reuse"]
    M2 -->|no| E
    P5 --> E["PASS N C checks and more; no headset validation implied"]
    G -.->|"absent: differential fixtures print SKIP and exit 0"| P2

Loading

The docstring notes that "one Metal check draws on the Mac's GPU when it has one (synthetic shaders)"; in practice several Mac-only Metal fixtures render and read back pixels on the local GPU.

Locating the generated engine (skips)

Several fixtures compile the lifted original functions (sub_XXXXXXXX.c) next to a native rewrite and compare every observable byte. Generated code is never in Git, so generated_engine() (run_source_checks.py:15-29) searches, in order:

1. $HALO_GENERATED_ENGINE
2. $HALO_ENGINE_GEN
3. <checkout>/native/build/engine-reuse/desktop-build75-direct, then the same under the main checkout when this is a Git worktree (found through git rev-parse --git-common-dir)
4. <checkout>/native/build/engine-reuse/whole-exe, then the main checkout's

The first candidate containing both engine_functions.h and sub_004CC0D0.c is used and passed as -I <dir> to the fixtures that want it. When none exists, those fixtures compile a stub main behind #if __has_include("sub_....c") that prints SKIP: ... and exits 0, so the suite still passes. VALIDATION.md is explicit that such runs "reported skips for optional original-engine comparisons".

Environment variables

Variable	Read by	Effect
CC	run_source_checks.py	C/Objective-C compiler (default clang).
HALO_GENERATED_ENGINE, HALO_ENGINE_GEN	run_source_checks.py, benchmark_x87_rotating_stack.py	Directory of generated engine sources for differential fixtures.
HALO_RADIAL_FOG_GENERATED_DIR	run_source_checks.py	Overrides the generated directory for test_radial_fog.c only, adding -DRF_HAVE_ENGINE=1.
HALO_ENGINE_TRANSLATION	run_source_checks.py	Directory containing sub_005482E0.c and sub_00547FF0.c for the translated-allocator voice-reuse check; otherwise the newest native/build/engine-reuse/*/sub_005482E0.c is used, else SKIP.
HALO_RADIAL_FOG_VSH, HALO_RADIAL_FOG_RDATA	test_radial_fog.c	Optional owned vsh.bin and engine static data fixtures; SKIP when absent, failure when set but missing.
HALO_RADIAL_FOG_MSL_DIR	test_radial_fog.c, test_radial_fog_renderer.m	Optionally saves emitted Metal sources for offline metal -c.
HALO_TEST_GATHER_MAP, HALO_TEST_B30_MAP	test_gather_pipeline.c	Owned map for the real-level gather comparison; SKIP when absent.
HALO_TEST_TEXTURE_PACK	test_texture_mod_pack.c	Optional real HVTEX001 pack to parse.

Every check run_source_checks.py runs

Phase 1: Python and repository checks (always)

run_source_checks.py:40-48

#	Command	What it checks
1	tools/check_repository_hygiene.py (non-strict)	No forbidden artifacts or secret-like patterns in source paths.
2	tools/test_repository_hygiene.py	The documentation-art exception admits only the exact reviewed PNG.
3	tools/check_probe_runner_exit.py	The desktop probe runner writes run.json, preserves evidence and maps child exit codes (0, 7, 124, and signal -11 to 139).
4	tools/test_setup_halo.py	24 setup regressions (Setup Wizard).
5	tools/test_visual_assets.py	9 visual-pack and content-selection regressions (Visual Mods Pipeline).
6	tools/test_censhine_import.py	4 shader-adapter ABI and malformed-input regressions.
7	tools/test_engine_vision_report_summary.py	Diagnostic summary arithmetic against device telemetry and older report formats.
8	tools/test_watch_engine_vision_telemetry.py	Telemetry watcher rejects stale builds and unsafe paths.
9	native/EngineHost/tests/test_dispatch_interest.py	Every hook address compared in host override code is listed in engine_hooks.h (otherwise translated code would call the original directly and bypass the hook).

Phase 2: portable C fixtures (32)

Built on every platform, including --portable-only and CI (run_source_checks.py:49-75). "FP" below means -frounding-math -ffp-contract=off; "gen" means -I <generated engine> when found; "DS" means -ffunction-sections -fdata-sections -Wl,-dead_strip.

#	Fixture (tests/test_<name>.c)	Extra sources	Extra flags
1	frame_pacer
2	panorama_budget
3	pointer_step
4	pointer_input
5	panorama_epoch
6	panorama_gpu_carry
7	panorama_lifecycle
8	panorama_pose_export
9	panorama_camera_cut
10	panorama_motion_budget
11	texture_mips
12	dinput_lifecycle
13	x87_nearest_fast_path
14	engine_direct_calls
15	controller_link_guard
16	panorama_reentry	halo_settings.c
17	panorama_projection_hook	halo_settings.c
18	panorama_letterbox_boundary	halo_settings.c
19	panorama_lod	halo_settings.c	FP, gen
20	panorama_interface_record	halo_settings.c	-DHALO_ARM64_FENV_FAST=1, FP, gen (SKIP without)
21	halo_settings_layer_align	halo_settings.c
22	x87_rotating_stack	tests/x87_stack_shifting.c	-DHALO_ARM64_FENV_FAST=0, FP
23	x87_rotating_stack	tests/x87_stack_shifting.c	-DHALO_ARM64_FENV_FAST=1, FP
24	mixer_quality	directsound_mixer.c, halo_settings.c
25	texture_mod_pack
26	shader_mod_pack
27	d3d9_texture_mod	texture_decode.c	DS
28	visible_surfaces		-DHALO_ARM64_FENV_FAST=1, FP, gen (SKIP without)
29	radial_fog_settings	halo_settings.c
30	radial_fog	metalshader.c + the four MojoShader sources	-w, FP, MojoShader Metal-only defines; -DRF_HAVE_ENGINE=1 -I <dir> when a generated engine or HALO_RADIAL_FOG_GENERATED_DIR exists
31	core_telemetry
32	game_time_telemetry		-DHALO_ARM64_FENV_FAST=1, FP, gen (SKIP without)

Phase 3: Mac-only C fixtures (27)

Added when mac is true (run_source_checks.py:76-91). These use Mach APIs, real pthread scheduling, or AudioToolbox types.

#	Fixture	Extra sources	Extra flags
33	thread_wait_telemetry
34	pass_time_telemetry		DS
35	haptics_mailbox
36	audio_watchdog	directsound_mixer.c	-framework AudioToolbox
37	directsound_lifetime	directsound_mixer.c	-framework AudioToolbox
38	directsound_voice_reuse	directsound_mixer.c	-framework AudioToolbox
39	guest_pages		DS
40	win32_save_flush		DS
41	d3d9_reset		DS
42	vb_resident		DS
43	draw_indices		DS
44	d3d9_radial_fog		DS
45	win32_sleep_accounting		DS
46	frame_pacing_host	halo_settings.c
47	guest_heap		DS
48	win32_heap_reuse		DS
49	d3d9_resource_lifetime		DS
50	d3d9_texture_lifetime		DS
51	thread_cancellation
52	win32_apc_queue		DS
53	win32_tls_lifetime		DS
54	guest_heap_sound_owners	directsound_mixer.c	DS, -framework AudioToolbox
55	guest_thread_qos
56	cache_read_wait		DS
57	haptics_detector	haptics.c, halo_settings.c
58	haptics_onset	haptics.c, halo_settings.c, directsound_mixer.c
59	directsound_mixer	haptics.c, halo_settings.c, directsound_mixer.c

The dead-strip flags let a fixture include a large production translation unit (for example d3d9.c or shims_kernel32.c) while discarding unreferenced host runtime code that would otherwise need more fakes.

Phase 4: always-run extras

run_source_checks.py:119-144

Check	Build	Purpose
runtime-contract-EngineReuse	native/Tests/EngineRuntimeContract.c + native/EngineReuse/engine_runtime.c, -DENGINE_STEP_FULL=1 -DHALO_STAGED_ENGINE=0	The bounded HaloEngineRuntime API: owned regions, read-only and missing memory, budgets, failure reporting; "Runtime ABI remains logical ST(i), regardless of the internal ring."
benchmark_x87_rotating_stack.py --check-only --allow-missing [--generated <dir>] [--sanitize]	builds x87_translated_*.c against four real translated leaves (sub_0050D5B0, sub_004CC0D0, sub_00554260, sub_00553380)	Equivalence of the rotating and shifting x87 layouts on real translated code; explicit SKIP without generated sources.
native_leaves	test_native_leaves.c, gen	Native leaf rewrites vs translated originals with the desktop release flags.
native_leaves_headset_flags	same plus FP and -DHALO_ARM64_FENV_FAST=1	The same comparison with the headset's floating-point flags.
native_gather	test_native_gather.c, -DHALO_ARM64_FENV_FAST=1, FP, gen	Exact leaf/cluster gather loops vs translated code.
gather_pipeline	test_gather_pipeline.c, same flags	Whole light/shadow gather (00553D80 and callees) vs translated code, plus an optional real-map pass.

Phase 5: Mac-only Objective-C, Metal, Swift and tool checks

run_source_checks.py:145-283. Objective-C builds use the same optimisation/sanitizer flags plus -fobjc-arc -fblocks; Swift builds use swiftc with a private module cache.

Check	Sources	Frameworks / notes
gather-diagnostics	EngineGatherDiagnostics.swift + Tests/GatherDiagnosticsValidation.swift, bridging EngineDiagnosticsBridge.h	swiftc
directsound_voice_reuse_translated	test_directsound_voice_reuse.c + directsound_mixer.c, -DHALO_TRANSLATED_ALLOCATOR -I <translation>	AudioToolbox; runs the voice-reuse scenario on the translated allocator 005482E0/00547FF0; otherwise prints SKIP voice reuse on the translated allocator
check_core_telemetry_xros.py	generated probe	xrOS compile/link only; SKIP without the xros SDK
core-telemetry-json	EngineCoreTelemetry.swift + Tests/CoreTelemetryValidation.swift, bridging EngineVisionBridge.h	swiftc
controller-haptics	tests/test_controller_haptics.m	Foundation, CoreHaptics, GameController (mocked hardware)
controller-snapshot	tests/test_controller_snapshot.m	Foundation, CoreHaptics, GameController
metal-overlay-cache	tests/test_metalrenderer_overlay_cache.m + halo_settings.c	Foundation, Metal (fake compiler objects)
metal-draw-fastpaths	tests/test_metalrenderer_fastpaths.m	Foundation, Metal (real GPU, exact framebuffer comparison)
metal-texture-bindings	tests/test_metalrenderer_texture_bindings.m	Foundation, Metal
metal-state-pressure	tests/test_metalrenderer_state_pressure.m	Foundation, Metal
audio-session-recovery	native/EngineVision/Tests/AudioSessionRecoveryValidation.m	Foundation (mocked AVAudioSession)
metal-pipeline-cache	tests/test_metalrenderer_pipeline_cache.m + metalshader.c, halo_settings.c, MojoShader	Foundation, Metal (real MojoShader, synthetic shaders, two processes sharing a temp cache)
radial-fog-renderer	tests/test_radial_fog_renderer.m + metalshader.c, MojoShader, halo_settings.c	Foundation, Metal
immersive-ownership	EngineImmersiveOwnership.swift + Tests/ImmersiveOwnershipValidation.swift	swiftc
panorama-publication	Tests/PanoramaPublicationValidation.m	Foundation, Metal, DS
core-telemetry-collection	Tests/CoreTelemetryCollectionValidation.m	Foundation, Metal, QuartzCore, DS
world-cadence	EngineWorldCadence.swift + Tests/WorldCadenceValidation.swift	swiftc
menu-input	EngineMenuInput.swift + Tests/MenuInputValidation.swift	swiftc
deep-telemetry	EngineDeepTelemetry.swift + Tests/DeepTelemetryValidation.swift	swiftc
diagnostic-history	EngineDiagnosticHistory.swift + Tests/DiagnosticHistoryValidation.swift	swiftc
diagnostic-report-writer	EngineDiagnosticHistory.swift, EngineDiagnosticReportWriter.swift + Tests/DiagnosticReportWriterValidation.swift	swiftc
layer-alignment	EngineImmersiveScreenGeometry.swift, EngineLayerAlignment.swift + Tests/LayerAlignmentValidation.swift	swiftc -O ("the sphere-wide coverage sweeps are too slow unoptimised")
layer-alignment-gpu	same + Tests/LayerAlignmentGPUValidation.swift, run with EngineImmersive.swift as argument	swiftc -O; extracts the shipped shader text from EngineImmersive.swift and runs it on the Mac GPU

Some Metal fixtures return 77 when mr_create() fails ("Metal unavailable"). Because the driver uses check=True, a 77 exit is reported as a failure, not a skip; the Mac-only phase assumes a Metal device is present.

CI workflow

.github/workflows/source-checks.yml:

Setting	Value
Triggers	push, pull_request, workflow_dispatch
Permissions	contents: read
Concurrency	group source-checks-${{ github.ref }}, cancel in progress
Job	portable on macos-15, 15-minute timeout
Checkout	actions/checkout pinned to commit 11d5960a326750d5838078e36cf38b85af677262, persist-credentials: false
Steps	python3 tools/check_repository_hygiene.py --strict; python3 tools/run_source_checks.py --portable-only; python3 tools/run_source_checks.py --portable-only --sanitize

The workflow comment explains why it is macOS even for the portable subset: "The host-backed C fixtures use Mach APIs and Apple's linker even in the subset that skips the GPU/visionOS checks." CI has no generated engine, so all differential fixtures SKIP there. FEATURES.md and VALIDATION.md record that hosted runs were blocked by an account billing restriction, so the recorded results are local runs. (The 1.0.0 section of VALIDATION.md still mentions "the included Ubuntu CI workflow"; the workflow at this commit is macOS-only, per the 1.0.2 changelog.)

Catalogue of all test files

"Suite" indicates whether run_source_checks.py builds and runs the file: P portable phase, M Mac-only phase, X always-run extras, - not wired (manual, needs owned data or captures, or a diagnostic/benchmark).

native/EngineHost/tests/

File	Suite	Purpose
frame_pacer_traces.inc	(data)	Anonymised interval-aggregate frame-pacing traces from Build74/75 used by test_frame_pacer.c.
haptics_from_capture.c	-	Diagnostic (not pass/fail): runs the impact detector over a captured WAV (HALO_AUDIO_CAPTURE_WAV) and prints event times.
test_arm64_fenv_prototype.c	-	Differential check of the ARM64 FPCR/FPSR prototype helpers against libc fenv in all four rounding modes, plus benchmarks.
test_audio_ownership_trace.c	-	The audio ownership trace hook does not claim dispatch and logs the guest call.
test_audio_shim_boundaries.c	-	Offline DirectSound/Vorbis ABI boundaries; takes an owned sounds.map argument; never starts an AudioQueue.
test_audio_source_identity.c	-	halo_audio_source_identity() matches equal inputs, differs on last-byte/length change, and does not mutate input.
test_audio_watchdog.c	M	Mock AudioQueue and clock: watchdog rebuilds, create/enqueue/start failures.
test_cache_read_wait.c	M	Halo's blocking cache-read waits (Sleep(0) returning to 00443EEA/004446D8) block until completion, bounded, never missing one.
test_controller_haptics.m	M	Mock controller and CoreHaptics engine; no hardware or playback.
test_controller_link_guard.c	P	The haptics guard that keeps a DualSense on Bluetooth: pulse pacing to 4/s, connect grace, suspension after pulse-linked drops.
test_controller_snapshot.m	M	One controller capture serves all reads within a frame (mocked hardware).
test_core_telemetry.c	P	Core telemetry measurement arithmetic and atomic publication.
test_d3d9_destalpha_blend.c	-	Fixed-function 3D bridge accepts the observed DESTALPHA/ONE blend with a normal+UV declaration (CPU renderer fakes).
test_d3d9_lighting.c	-	Includes d3d9.c; fixed-function lighting matches a reference, with a speed comparison.
test_d3d9_radial_fog.c	M	Production fixed-3D bridge and programmable fog-mode selection with radial fog on/off.
test_d3d9_reset.c	M	IDirect3DDevice9::Reset implicit-surface and renderer ownership.
test_d3d9_resource_lifetime.c	M	D3D resource ownership with the production heap/page allocators.
test_d3d9_resource_upload.m	-	Real Metal: a pending indexed draw survives overwrite/free of source VB/IB bytes before commit.
test_d3d9_stateblock.c	-	Production state-block setter router, recording, Capture/Apply masks and COM methods.
test_d3d9_stateblock_trace.c	-	Opt-in state-block diagnostics preserve CPU/draw state and rate-limit output.
test_d3d9_texture_cache.c	-	Upload/cache path for 2D and cube textures, CPU writes, per-renderer ownership, GPU aliases, readback failure.
test_d3d9_texture_lifetime.c	M	Texture/surface ownership with real guest allocators and counted Metal context doubles.
test_d3d9_texture_mod.c	P	Real D3D upload boundary with a temporary HVTEX001 pack and content-generation changes.
test_d3d9_texture_upload.m	-	Real Metal: copied uploads and pending sampled resources survive cache removal and target-context destruction.
test_desktop_video_dialog.c	-	USER32/resource shims for Halo's startup video-mode dialog; desktop vs client size distinction.
test_destalpha_blend.m	-	Offline Metal pipeline-descriptor builders for DESTALPHA/ONE blending (fake device, no GPU).
test_dinput_lifecycle.c	P	DirectInput COM object and input transitions with a deterministic controller.
test_directsound_lifetime.c	M	DirectSound object lifecycle without AudioQueue or assets.
test_directsound_mixer.c	M	Mixer ABI: voice setup, resampling values, listener state.
test_directsound_voice_reuse.c	M (+ translated variant)	Halo's voice reuse through the production DirectSound shim (the Build75 b30 silence scenario).
test_dispatch_interest.py	Phase 1	Hook addresses used by host overrides are listed in engine_hooks.h.
test_draw_indices.c	M	Differential: production draw_indices (16-bit fast path) vs a verbatim copy of the previous loop over randomized inputs.
test_draw_reject_trace.c	-	Opt-in draw-reject logger: windows, dedup, caps, unchanged HRESULT/state.
test_engine_direct_calls.c	P	ENGINE_DIRECT calls fixed entries directly but routes hooked entries through engine_dispatch.
test_fixed_modulate_ops.m	-	Direct3D texture-stage modulate/add ops 18/20/21 match GPU pixels.
test_fixed_stage_dependencies.m	-	Unused texture operands need no texture/TEXCOORD; live dependencies retained; GPU pixel matches.
test_fp_vertex_capture.c	-	First-person vertex capture diagnostics: gates, payloads, caps, unchanged live and guest bytes.
test_frame_pacer.c	P	Frame-pacer controller arithmetic and trace-derived cadence simulation (not headset evidence).
test_frame_pacing_host.c	M	Host pacing glue with deterministic clocks, live settings and the bearing budget.
test_framebuffer_upload.m	-	GPU ordering and staging lifetime of framebuffer uploads, odd row pitch, clear.
test_game_time_telemetry.c	P	Runs the translated tick driver 00470BF0 to verify the telemetry's game-time field (SKIP without generated code).
test_gather_pipeline.c	X	Whole-gather differential vs generated 00553D80 and callees; optional real-map pass.
test_guest_heap.c	M	Production guest heap, including native allocation failure.
test_guest_heap_sound_owners.c	M	Production heap plus DirectSound ownership.
test_guest_pages.c	M	Production guest page allocator, including allocation-failure escape.
test_guest_thread_qos.c	M	Guest threads inherit the creator's QoS class or HALO_GUEST_THREAD_QOS.
test_halo_settings_layer_align.c	P	Layer alignment is off unless HALO_LAYER_ALIGN=1; live toggle; each environment checked in a child.
test_halo_vorbis.c	-	Bounded stb_vorbis decode of the first Ogg stream in an owned sounds.map.
test_haptics_detector.c	M	Mixed-signal impact detector fires on impacts and stays quiet on music (48 kHz, 512-frame buffers).
test_haptics_mailbox.c	M	Haptics event mailbox independent of DSP timing.
test_haptics_onset.c	M	Haptics from positional voice onsets near the listener, not from distant, 2D, sustained or swelling sounds.
test_metalrenderer_fastpaths.m	M	Differential GPU test of renderer shortcuts (resident vertex copies, folded clears, encoder reuse) vs original paths.
test_metalrenderer_mips.c	-	Real Metal: NPOT mip accounting, cached lookups, mip filtering reduces aliasing, anisotropic sample validity.
test_metalrenderer_overlay_cache.m	M	Pipeline cache/descriptor reuse between world and HUD with fake compiler objects.
test_metalrenderer_pipeline_cache.m	M	Pipelines built ahead of draws with real Metal and MojoShader; two sessions share a temp cache.
test_metalrenderer_state_pressure.m	M	Real GPU: independent U/V addressing and bounded sampler/depth-stencil caches under pressure.
test_metalrenderer_texture_bindings.m	M	Texture cache pressure on the real Metal path with a 1 KiB cache limit.
test_mixer_quality.c	P	Mixer signal quality: resampling, limiter, head-relative panning, distance factor.
test_model_vertex_capture.c	-	Model vertex capture diagnostics against a synthetic original ABI.
test_native_gather.c	X	Exact leaf/cluster gathers vs translated sub_*.c with guard pages and full state comparison.
test_native_leaves.c	X (twice)	Native leaves in native_leaves.h vs translated functions on random and awkward inputs.
test_panorama_budget.c	P	Panorama bearing budget planner masks for mono/stereo and head pose.
test_panorama_camera_cut.c	P	Camera cuts never publish a mixture of two shots.
test_panorama_epoch.c	P	A rotating frame may begin on any layer (frame-start epoch).
test_panorama_fp_original_history.c	-	Executes lifted original first-person history/cache instructions to expose three-pass yaw contamination (needs an audited generated tree).
test_panorama_gpu_carry.c	P	Panorama producer with an injected GPU sink (GPU-carried layers).
test_panorama_interface_record.c	P	The game's interface record run through the lifted renderer under the panorama hook (SKIP without generated code).
test_panorama_letterbox_boundary.c	P	Cinematic letterbox dispatch filter ABI.
test_panorama_lifecycle.c	P	Producer lifecycle with distinct sentinels per epoch/layer.
test_panorama_lod.c	P	Native LOD pixel-size routine vs translated 0050F740, bit-identical across inputs and rounding modes.
test_panorama_motion_budget.c	P	Motion-fill budget chooses fresh visible joins under timing constraints.
test_panorama_pose_export.c	P	Per-layer camera export and cut epochs through the production producer.
test_panorama_projection_hook.c	P	Opt-in projection-only dense panorama hook option combinations.
test_panorama_reentry.c	P	Eight-bearing mono sphere host ABI/state with an injected original-render escape.
test_pass_time_telemetry.c	M	The D3D pass timer keeps lifetime totals when the interval profiler resets.
test_pointer_input.c	P	Pointer queue and servo with Halo's measured mouse curve.
test_pointer_step.c	P	Gaze pointer servo step converges without ringing, robust to a 20% curve error.
test_process_vertices.c	-	Skinned ProcessVertices against independent bone transforms; needs a captured fixture directory.
test_process_vertices_differential.c	-	Byte-exact differential over captured draws in four rounding modes; needs captures.
test_radial_fog.c	P	Radial fog shader rewrite vs original shader interpretation across bearings; optional engine constants and owned shaders.
test_radial_fog_renderer.m	M	Production renderer plus real MojoShader with radial fog; fake compiler objects by default, --gpu to draw.
test_radial_fog_settings.c	P	Radial fog switch is strict opt-in and immutable across bearings; concurrent first reads.
test_render_capture_selectors.c	-	Frame/pass capture selector diagnostics, budgets and metadata.
test_rhw_declaration.c	-	Recognises the original POSITIONT layouts and excludes ordinary BSP POSITION.
test_rhw_diffuse_alpha.m	-	Real GPU: RHW diffuse alpha, additive blending, border and wrap/clamp behaviour.
test_shader_mod_pack.c	P	HVSHD001 parser bounds, exact lookup, truncation and token validation.
test_stateblock.c	-	stateblock.h recording masks, sparse registers, resource ownership, allocation failure.
test_texture_content_hash.c	-	Texture content hash known vectors, alignment independence and sensitivity; optional FNV vs xxh3 benchmark.
test_texture_mips.c	P	Optimised mip generation matches a reference over 4,225 dimension/pitch cases and a 2048 image.
test_texture_mod_pack.c	P	HVTEX001 parser and native CRC32 vs scalar; optional real pack via HALO_TEST_TEXTURE_PACK.
test_thread_cancellation.c	M	Production waits and cancellation, including pthread_join completion.
test_thread_wait_telemetry.c	M	Guest wait paths with an errno-clobbering clock wrapper, telemetry on and off.
test_vb_resident.c	M	Resident static vertex buffers through the production D3D draw path, byte-checked per draw.
test_visible_surfaces.c	P	Native 00553920 vs the translated routine with randomized clusters and edge cases.
test_win32_apc_queue.c	M	ReadFileEx and alertable APC dispatch against a disposable file.
test_win32_find_profiles.c	-	FindFirstFile/FindNextFile discover extensionless profile directories.
test_win32_heap_reuse.c	M	Win32 heap shims on the production allocator.
test_win32_save_flush.c	M	Truncate/flush shims against disposable files and failed descriptors.
test_win32_sleep_accounting.c	M	Sleep/SleepEx/Sleep(0) accounting matches the Build78 shim with pacing off.
test_win32_tls_lifetime.c	M	TLS slot allocation and reuse across native guest threads.
test_x87_nearest_fast_path.c	P	Round-to-nearest fast path is bit-identical to the FPCR/FPSR path.
test_x87_rotating_stack.c	P (twice)	Rotating x87 register file vs the shifting layout on random helper streams.
x87_shifting_engine_cpu.h	(support)	Frozen copy of the pre-rotation engine_cpu.h, test reference only.
x87_stack_ops.h, x87_stack_ops.inc	(support)	Shared x87 operations compiled once per layout.
x87_stack_shifting.c	(support)	Shifting-layout side of test_x87_rotating_stack.
x87_translated.h, x87_translated_impl.inc, x87_translated_rotating.c, x87_translated_shifting.c, x87_translated_test.c	X (via benchmark)	Real translated leaves compiled against both x87 layouts, checking every writable guest byte after each call.

native/EngineVision/Tests/

File	Suite	Purpose
AssetValidationMain.swift	-	CLI: EngineAssetImporter.preflight on a game folder, prints ASSET_PREFLIGHT_OK.
AudioSessionRecoveryValidation.m	M	Production audio session coordinator under injected activation, rebuild and queue-start failures (mocked framework).
BundledAssetValidationMain.swift	-	Bundled-payload import with progress checks, Apple path aliases and expected rejections.
CoreTelemetryCollectionValidation.m	M	Telemetry collector against deterministic kernel replies, failures and a non-unit Mach timebase.
CoreTelemetryValidation.swift	M	Core telemetry serializer preserves counts, units, availability and fixed-size arrays.
DeepTelemetryValidation.swift	M	Deep telemetry derived rates and flags from synthetic samples.
DiagnosticHistoryValidation.swift	M	Segmented diagnostic history rotation and bounds.
DiagnosticReportWriterValidation.swift	M	Report writer interval (HALO_REPORT_SECONDS, default 30, range 1-600) and output.
ExactFrameSnapshotProbeTests.m	-	Exact frame snapshot probe is default-off, strict, single-shot and read-only.
FrameTextureValidation.swift	-	Frame texture refresh never mutates an in-flight GPU texture; duplicate sequences reuse.
GatherDiagnosticsValidation.swift	M	Gather diagnostics field mapping.
GuestPoseProbeTests.m	-	Diagnostic telemetry distinguishes a unit's origin from its animated bounding centre.
GuestWeaponTelemetryProbeTests.m	-	CPU-only weapon/trigger telemetry probe fixture.
ImmersiveAspectValidation.swift	-	Immersive screen mesh preserves aspect across ratios.
ImmersiveGPUValidation.swift	-	Runs the shipped stereo shader (extracted from EngineImmersive.swift) on the Mac GPU.
ImmersiveOwnershipValidation.swift	M	Immersive session ownership tokens: a failing old session cannot clear a newer one.
LayerAlignmentGPUValidation.swift	M	Layer alignment shader on the Mac GPU: identity, coverage under turns, older-camera reprojection.
LayerAlignmentValidation.swift	M	Layer alignment math against the host's own bearing construction; no holes or weapon movement.
MenuInputProbe.m	-	Diagnostic executable that runs the original engine with fixed input edges (used by tools/probe_engine_menu_input.py).
MenuInputValidation.swift	M	Gaze/pinch menu target selection logic.
MutableAssetPreservationMain.swift	-	Saves preserved across a payload repair; missing immutable files force repair.
PanoramaCompositePreview.swift	-	Tool: renders on a Mac what the headset would show from captured layers.
PanoramaLeaseLayerCountValidation.swift	-	The zero-copy lease unpacks every layer texture (guards the seven-to-ten layer regression).
PanoramaProductionGPUValidation.swift	-	Production panorama shader rasterises the front-half cylinder without clip-plane artifacts.
PanoramaPublicationValidation.m	M	Panorama pool/publication with delayed completions and fake copies.
PanoramaRasterProbe.m	-	Metal: behind-camera clipping, HUD target reset and transparent HUD coverage.
PanoramaSphereCoverageValidation.swift	-	Panels composite to full opacity over the hemisphere (no holes or dim patches).
PanoramaTextureValidation.swift	-	Panorama texture snapshots with per-layer pixels and epochs.
PanoramaViewportValidation.swift	-	CPU coverage of panorama viewports with valid/invalid sentinels.
RuntimeFrameHarness.m	-	Runtime frame-copy bounds and singleton harness against EngineVisionBridge.h.
UseButtonProbe.c	-	GameController snapshot to DirectInput keyboard boundary for the use button.
WorldCadenceValidation.swift	M	World cadence statistics at 90 Hz submission.

native/Tests/

File	Suite	Purpose
EngineRuntimeContract.c	X	Contract test for native/EngineReuse/engine_runtime.c: success, failure, read-only and missing memory, budget exhaustion and x87 push behaviour through the bounded runtime API.

tools/

File	Suite	Purpose
test_setup_halo.py	Phase 1	24 setup regressions (registry, import, workflow).
test_visual_assets.py	Phase 1	9 visual pack and content-selection regressions.
test_censhine_import.py	Phase 1	4 CEnshine adapter regressions.
test_repository_hygiene.py	Phase 1	4 documentation-art exception regressions.
test_engine_vision_report_summary.py	Phase 1	16 summary-arithmetic tests (split clocks, bucket association, Build75/Build78 compatibility, missing/failed counters, zero denominators, resets).
test_watch_engine_vision_telemetry.py	Phase 1	4 watcher tests (candidate paths, build identity, next-build identity, partial summaries).
test_texmod_import.py	-	TexMod decoder: BMP alpha/orientation, PNG channels, DXT2 un-premultiply (needs Pillow).
test_hd_texture_merge.py	-	13 HD merge safety tests (needs Pillow).
check_probe_runner_exit.py	Phase 1	Probe runner reporting tail (see Phase 1).
check_core_telemetry_xros.py	M	xrOS telemetry link check.

tools/engine_reuse/

File	Suite	Purpose
test_decode.py	-	Conditional fallthrough into a shared epilogue at 0x4D0580 becomes a tail call when the epilogue is a known entry; requires the owned halo.exe (HALO_EXE).
test_flags.py	-	Differential tests of the IA-32 integer flags layer against real x86 execution in Unicorn (helpers, conditions, shifts, IMUL forms, aliases, undefined-behaviour-free header).
test_fpu.py	-	Executes x87 snippets in Unicorn and in generated native C and compares results (with a secondary x86 path for instructions Unicorn models differently).

These use package-relative imports (from .upstream import ...); test_flags.py falls back to a direct import when run as a script. They are not part of run_source_checks.py; see XWA Decoder and Lifter.

How to add a test

1. Choose the boundary. Follow the existing pattern: #include the production .c/.m file (or header) under test so the fixture always matches shipped code, and fake only what lies outside it (renderer calls, host_log, guest allocators, clocks). Comments such as "This fixture never destroys a live Metal context" mark fakes that abort() if reached.
2. Write native/EngineHost/tests/test_<name>.c with a main that uses assert and prints one PASS: ... line describing what was proven. Keep it deterministic, small and bounded (each command has a 120 s timeout).
3. Guard generated-code dependencies with #if __has_include("sub_XXXXXXXX.c") and an #else main that prints SKIP: ... and returns 0.
4. Register it in run_source_checks.py: add (name, [extra sources/flags]) to the portable cases list if it builds with plain C and POSIX APIs, or to the if mac: block if it needs Mach, AudioToolbox or Apple-only behaviour. Add -ffunction-sections -fdata-sections -Wl,-dead_strip (via the name lists at lines 112-116) when including a large production unit, and the FP flags when comparing against translated code.
5. Objective-C/Metal or Swift fixtures go into the if mac: section after line 145 as an explicit run([...build...]) followed by run([binary]).
6. Python tests are added to the Phase 1 list near the top of main().
7. Run the suite normally and with --sanitize, and with --portable-only if the test is portable. Report results distinguishing source tests, desktop Metal checks, and headset measurements (CONTRIBUTING.md).

What the suite does not prove

The driver's final message says "no headset validation implied". Source checks do not establish device installation, frame rate, audible output, panorama seams, or campaign completion; VALIDATION.md keeps these as separate gates.

Related pages

• Release Process and Hygiene
• Setup Wizard
• Visual Mods Pipeline
• Build System
• x87 Floating Point
• EngineReuse Runtime
• Metal Renderer
• Panorama System
• Audio System
• Diagnostics and Telemetry
• Contributing Guide