EVEngine/docs/dev/fuzz-testing.md

Fuzz testing

EVEngine uses zeroerr's structured fuzz API with libFuzzer. Fuzz harnesses are small standalone Clang builds under test/fuzz; the normal Linux engine build continues to use GCC.

Run locally

Install Clang (including compiler-rt), CMake and Ninja, initialize submodules, then run:

make fuzz/linux

The default budget is 2,000 executions per harness. Override the deterministic budget and seed when reproducing or running a longer campaign:

EVENGINE_FUZZ_RUNS=50000 EVENGINE_FUZZ_SEED=123 make fuzz/linux

Harnesses run with AddressSanitizer and UndefinedBehaviorSanitizer. CI uses a short budget for pull requests and a longer budget on the weekly schedule. If libFuzzer finds a failure, CI uploads its crash-*, leak-*, oom-* or timeout-* reproducer.

Adding a harness

• Put it in test/fuzz and use FUZZ_TEST_CASE / FUZZ_FUNC from zeroerr.
• Prefer structured domains and include known boundary inputs with WithSeeds.
• Keep the target small: compile only the parser or subsystem boundary under test instead of linking the complete engine.
• Make every run deterministic through EVENGINE_FUZZ_SEED.
• When a defect is found, commit a normal regression test before fixing it; keep compact inputs as permanent seeds when they improve future exploration.