More troubleshooting doc

book/documentation/TROUBLESHOTING.html

@@ -179,14 +179,32 @@ <h1 class="menu-title">Phink Book</h1>
 
                 <div id="content" class="content">
                     <main>
-                        <h3 id="debugging-phink"><a class="header" href="#debugging-phink">Debugging Phink</a></h3>
-<p>Use the harness coverage feature for debugging. You should only use this if you want to have a coverage of Phink itself,
-for instance if you are planning to contribute to Phink, or to debug it.</p>
+                        <h1 id="troubleshooting"><a class="header" href="#troubleshooting">Troubleshooting</a></h1>
+<h2 id="debugging-phink"><a class="header" href="#debugging-phink">Debugging Phink</a></h2>
+<h3 id="afl-logs"><a class="header" href="#afl-logs">AFL++ Logs</a></h3>
+<p>If you encounter unexpected behavior, examining the AFL++ logs can provide good insights. In most cases, developers
+will find more information by executing:</p>
+<pre><code class="language-sh">tail -f your_output/phink/logs/afl.log
+</code></pre>
+<p>Replace <code>your_output</code> with the directory defined in your <code>phink.toml</code> under <code>fuzz_output</code>. This will give you a
+real-time view of the log output, helping you identify any issues during the fuzzing process.</p>
+<h3 id="executing-a-single-seed"><a class="header" href="#executing-a-single-seed">Executing a Single Seed</a></h3>
+<p>To debug specific cases where a contract crashes, you can execute a single seed. This method allows you to instantiate a
+contract and identify crash points more easily:</p>
+<pre><code class="language-sh">phink execute output/phink/corpus/selector_1.bin
+</code></pre>
+<p>This command runs a single fuzzing input, making it easier to pinpoint problems.</p>
+<h3 id="harness-coverage"><a class="header" href="#harness-coverage">Harness Coverage</a></h3>
+<p>Use the harness coverage feature if you need insights into Phink’s functionality, particularly if you plan to contribute
+or debug the tool itself:</p>
 <pre><code class="language-sh">phink harness-cover
 </code></pre>
+<p>Be aware that this is primarily for those who want to dive deeper into the coverage of Phink and is not generally
+necessary for regular debugging.</p>
 <h3 id="support-channels"><a class="header" href="#support-channels">Support Channels</a></h3>
-<p>You can find us on <a href="https://discord.gg/4MakDGwFEK">Discord</a>. Alternatively, you can message me
-on <a href="kevin%5B%F0%9F%8E%A9%5Dsrlabs.de">kevin[🎩]srlabs.de</a>.</p>
+<p>For additional help, you can join us on <a href="https://discord.gg/4MakDGwFEK">Discord</a> where our community and team are
+active. Alternatively, feel free to message me at <a href="mailto:kevin%5B%F0%9F%8E%A9%5Dsrlabs.de">kevin[🎩]srlabs.de</a>.</p>
+<p>Happy fuzzing!</p>
 
                     </main>
 

book/documentation/print.html

@@ -684,14 +684,32 @@ <h2 id="contract-instrumentation"><a class="header" href="#contract-instrumentat
 <p>Phink instruments contracts using the <code>syn</code> crate, allowing for precise modification and analysis of the smart contract
 code. This instrumentation is crucial for identifying potential vulnerabilities and ensuring the integrity of the fuzz
 testing process.</p>
-<div style="break-before: page; page-break-before: always;"></div><h3 id="debugging-phink"><a class="header" href="#debugging-phink">Debugging Phink</a></h3>
-<p>Use the harness coverage feature for debugging. You should only use this if you want to have a coverage of Phink itself,
-for instance if you are planning to contribute to Phink, or to debug it.</p>
+<div style="break-before: page; page-break-before: always;"></div><h1 id="troubleshooting"><a class="header" href="#troubleshooting">Troubleshooting</a></h1>
+<h2 id="debugging-phink"><a class="header" href="#debugging-phink">Debugging Phink</a></h2>
+<h3 id="afl-logs"><a class="header" href="#afl-logs">AFL++ Logs</a></h3>
+<p>If you encounter unexpected behavior, examining the AFL++ logs can provide good insights. In most cases, developers
+will find more information by executing:</p>
+<pre><code class="language-sh">tail -f your_output/phink/logs/afl.log
+</code></pre>
+<p>Replace <code>your_output</code> with the directory defined in your <code>phink.toml</code> under <code>fuzz_output</code>. This will give you a
+real-time view of the log output, helping you identify any issues during the fuzzing process.</p>
+<h3 id="executing-a-single-seed"><a class="header" href="#executing-a-single-seed">Executing a Single Seed</a></h3>
+<p>To debug specific cases where a contract crashes, you can execute a single seed. This method allows you to instantiate a
+contract and identify crash points more easily:</p>
+<pre><code class="language-sh">phink execute output/phink/corpus/selector_1.bin
+</code></pre>
+<p>This command runs a single fuzzing input, making it easier to pinpoint problems.</p>
+<h3 id="harness-coverage"><a class="header" href="#harness-coverage">Harness Coverage</a></h3>
+<p>Use the harness coverage feature if you need insights into Phink’s functionality, particularly if you plan to contribute
+or debug the tool itself:</p>
 <pre><code class="language-sh">phink harness-cover
 </code></pre>
+<p>Be aware that this is primarily for those who want to dive deeper into the coverage of Phink and is not generally
+necessary for regular debugging.</p>
 <h3 id="support-channels"><a class="header" href="#support-channels">Support Channels</a></h3>
-<p>You can find us on <a href="https://discord.gg/4MakDGwFEK">Discord</a>. Alternatively, you can message me
-on <a href="kevin%5B%F0%9F%8E%A9%5Dsrlabs.de">kevin[🎩]srlabs.de</a>.</p>
+<p>For additional help, you can join us on <a href="https://discord.gg/4MakDGwFEK">Discord</a> where our community and team are
+active. Alternatively, feel free to message me at <a href="mailto:kevin%5B%F0%9F%8E%A9%5Dsrlabs.de">kevin[🎩]srlabs.de</a>.</p>
+<p>Happy fuzzing!</p>
 
                     </main>
 

book/src/TROUBLESHOTING.md

@@ -1,13 +1,45 @@
-### Debugging Phink
+# Troubleshooting
 
-Use the harness coverage feature for debugging. You should only use this if you want to have a coverage of Phink itself,
-for instance if you are planning to contribute to Phink, or to debug it.
+## Debugging Phink
+
+### AFL++ Logs
+
+If you encounter unexpected behavior, examining the AFL++ logs can provide good insights. In most cases, developers
+will find more information by executing:
+
+```sh
+tail -f your_output/phink/logs/afl.log
+```
+
+Replace `your_output` with the directory defined in your `phink.toml` under `fuzz_output`. This will give you a
+real-time view of the log output, helping you identify any issues during the fuzzing process.
+
+### Executing a Single Seed
+
+To debug specific cases where a contract crashes, you can execute a single seed. This method allows you to instantiate a
+contract and identify crash points more easily:
+
+```sh
+phink execute output/phink/corpus/selector_1.bin
+```
+
+This command runs a single fuzzing input, making it easier to pinpoint problems.
+
+### Harness Coverage
+
+Use the harness coverage feature if you need insights into Phink’s functionality, particularly if you plan to contribute
+or debug the tool itself:
 
 ```sh
 phink harness-cover
 ```
 
+Be aware that this is primarily for those who want to dive deeper into the coverage of Phink and is not generally
+necessary for regular debugging.
+
 ### Support Channels
 
-You can find us on [Discord](https://discord.gg/4MakDGwFEK). Alternatively, you can message me
-on [kevin[🎩]srlabs.de](kevin[🎩]srlabs.de).
+For additional help, you can join us on [Discord](https://discord.gg/4MakDGwFEK) where our community and team are
+active. Alternatively, feel free to message me at [kevin[🎩]srlabs.de](mailto:kevin[🎩]srlabs.de).
+
+Happy fuzzing!

src/instrumenter/instrumentation.rs

@@ -133,9 +133,9 @@ impl Instrumenter {
             );
         } else {
             bail!(
-                "{stderr} - {stdout} It seems that your instrumented smart contract did not compile properly. \
+                "{stderr} - {stdout}\n\n\nIt seems that your instrumented smart contract did not compile properly. \
         Please go to `{p_display}`, edit the source code, and run `cargo contract build --features phink` again. It might be because your contract has a bug inside, or because you haven't created any invariants for instance. \
-        Also, make sur that your Cargo.toml contains the `phink` feature. Sometimes it's because you need to recompile the contract, as you've changed the toolchain.\
+        \nAlso, make sur that your `Cargo.toml` contains the `phink` feature. It can also be that you need to recompile the contract, as you've changed the toolchain.\
         \nMore informations in the stacktrace above.",
             )
         }
@@ -152,7 +152,7 @@ impl Instrumenter {
     /// Create a temporary `clippy.toml` file and return its full path.
     ///
     /// # Returns
-    /// A `Result` containing the canonicalized path of the temporary file as a `String`.
+    /// `Result<String>` containing the canonicalized path of the temporary file as a `String`.
     fn create_temp_clippy() -> anyhow::Result<String> {
         let temp_dir = tempfile::TempDir::new().context("Failed to create temporary directory")?;
         let clippy_toml_path = temp_dir.path().join("clippy.toml");

tests/cli_fuzz_integration_test.rs

@@ -131,7 +131,10 @@ mod tests {
                     );
 
                     let selector = phink_output.join("selectors.dict");
-                    ensure!(selector.exists(), "selectors.dict doesn't exist");
+                    ensure!(
+                        selector.exists(),
+                        "selectors.dict doesn't exist ({selector:?})"
+                    );
 
                     ensure!(
                         fs::read_to_string(selector).unwrap().lines().count() > 1,