From 14ca8048a8539d2b658f1d5ed0269ea19a980d28 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Lecrenier?= <loic.lecrenier@me.com>
Date: Mon, 17 Oct 2022 12:42:12 +0200
Subject: [PATCH] Add some documentation on how to run the facet db fuzzer

---
 milli/src/update/facet/incremental.rs | 29 +++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/milli/src/update/facet/incremental.rs b/milli/src/update/facet/incremental.rs
index a4c756aec..2558c81a3 100644
--- a/milli/src/update/facet/incremental.rs
+++ b/milli/src/update/facet/incremental.rs
@@ -1022,6 +1022,35 @@ mod tests {
 
 // fuzz tests
 #[cfg(all(test, fuzzing))]
+/**
+Fuzz test for the incremental indxer.
+
+The fuzz test uses fuzzcheck, a coverage-guided fuzzer.
+See https://github.com/loiclec/fuzzcheck-rs and https://fuzzcheck.neocities.org
+for more information.
+
+It is only run when using the `cargo fuzzcheck` command line tool, which can be installed with:
+```sh
+cargo install cargo-fuzzcheck
+```
+To start the fuzz test, run (from the base folder or from milli/):
+```sh
+cargo fuzzcheck update::facet::incremental::fuzz::fuzz
+```
+and wait a couple minutes to make sure the code was thoroughly tested, then
+hit `Ctrl-C` to stop the fuzzer. The corpus generated by the fuzzer is located in milli/fuzz.
+
+To work on this module with rust-analyzer working properly, add the following to your .cargo/config.toml file:
+```toml
+[build]
+rustflags = ["--cfg",  "fuzzing"]
+```
+
+The fuzz test generates sequences of additions and deletions to the facet database and
+ensures that:
+1. its structure is still internally valid
+2. its content is the same as a trivially correct implementation of the same database
+*/
 mod fuzz {
     use std::borrow::Cow;
     use std::collections::{BTreeMap, HashMap};