a4e667de10
Single-commit clean baseline after security scrub of niche-tells, project codenames, internal jargon, and contributor-email leaks. Contents: - 100 Rust crates (_primitives/_rust/) - 37 agent manifests (_manifests/) + generated specs (_generated/) - 67 user-invocable skills (skills/) - 33 hooks (hooks/) - Composition blocks (_blocks/) - Documentation (docs/, README.md) - TS adapter packages (_ts_packages/) - Assembler (_assembler/) - Roles (_roles/) - Templates (_templates/) - Forgejo CI (.forgejo/) Author: Denis Parfionovich <info@greendragon.info> License: see LICENSE.
32 lines
2.4 KiB
Markdown
32 lines
2.4 KiB
Markdown
# TEST — Fuzzing (input-space exploration)
|
|
|
|
Fuzzing throws semi-random inputs at a target to find crashes, panics, hangs, and undefined behaviour the unit-test author never imagined. Complements `test-gen` (happy/edge/error) — fuzz owns the unknown-unknown surface.
|
|
|
|
**When to fuzz:** parsers, deserializers, protocol handlers, auth/crypto boundaries, any function that accepts untrusted bytes or strings. NOT business logic with well-defined inputs (use property tests instead).
|
|
|
|
**Per-language tool (default):**
|
|
- **Rust:** `cargo-fuzz` (libfuzzer-sys backend) — `cargo fuzz init`, then `fuzz_target!(|data: &[u8]| { my_parser(data); })`. Requires nightly. Harness lives in `fuzz/fuzz_targets/`. [E4, official: https://rust-fuzz.github.io/book/]
|
|
- **Python:** `hypothesis` in fuzz mode (`@given` + `HealthCheck.too_slow` disabled) for structured inputs; `atheris` (Google, libfuzzer bindings) for bytes-in fuzzing. [E4, hypothesis.readthedocs.io / github.com/google/atheris]
|
|
- **JS/TS:** `fast-check` with `fc.assert` using `numRuns: 10_000+` for fuzz-volume runs; `jsfuzz` for libFuzzer-style bytes fuzzing. [E4, fast-check.dev]
|
|
|
|
**Corpus management:**
|
|
- Seed corpus = hand-picked valid inputs (1-10 files). Place under `fuzz/corpus/<target>/`.
|
|
- Fuzzer mutates corpus → keeps inputs that hit new coverage → corpus grows.
|
|
- Commit corpus to git (gitignore `fuzz/artifacts/`). Treat as test fixture.
|
|
|
|
**Crash triage:**
|
|
1. Fuzzer dumps crash input under `fuzz/artifacts/<target>/crash-<hash>`.
|
|
2. Reproduce: `cargo fuzz run <target> fuzz/artifacts/<target>/crash-<hash>`.
|
|
3. Minimize: `cargo fuzz tmin <target> <input>` — shrinks to minimal reproducer.
|
|
4. Write a regression unit test using the minimized input BEFORE fixing the bug. Regression test is permanent; fuzz corpus is ephemeral.
|
|
|
|
**CI integration (budget-aware):**
|
|
- Short CI run: 60s per target on every PR. Catches regressions, not deep bugs.
|
|
- Nightly run: 1-4h per target on schedule. Upload crashes as artifacts.
|
|
- OSS-Fuzz (free for OSS): submit a `project.yaml` + Dockerfile + build script; Google runs fuzzing on their infra. [E4, google.github.io/oss-fuzz]
|
|
|
|
**Forbidden:**
|
|
- Fuzzing without a crash-reproducer harness (crashes become irreproducible).
|
|
- Running fuzzer without `cargo fuzz tmin` / equivalent — full-size crashes waste reviewer time.
|
|
- Committing `fuzz/artifacts/` (binary crash bodies, repo bloat).
|
|
- Treating a fuzz hit as "flaky" — every crash is a bug until minimized + explained.
|