uufuzz: add examples and them in the CI

Author: sylvestre

.github/workflows/fuzzing.yml

@@ -17,6 +17,40 @@ concurrency:
   cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
 
 jobs:
+  uufuzz-examples:
+    name: Build and test uufuzz examples
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v5
+      with:
+        persist-credentials: false
+    - uses: dtolnay/rust-toolchain@stable
+    - uses: Swatinem/rust-cache@v2
+      with:
+        shared-key: "uufuzz-cache-key"
+        cache-directories: "fuzz/target"
+    - name: Build uufuzz library
+      run: |
+        cd fuzz/uufuzz
+        cargo build --release
+    - name: Run uufuzz tests
+      run: |
+        cd fuzz/uufuzz
+        cargo test --lib
+    - name: Build and run uufuzz examples
+      run: |
+        cd fuzz/uufuzz
+        echo "Building all examples..."
+        cargo build --examples --release
+
+        # Run all examples except integration_testing (which has FD issues in CI)
+        for example in examples/*.rs; do
+          example_name=$(basename "$example" .rs)
+          if [ "$example_name" != "integration_testing" ]; then
+            cargo run --example "$example_name" --release
+          fi
+        done
+
   fuzz-build:
     name: Build the fuzzers
     runs-on: ubuntu-latest

fuzz/uufuzz/examples/basic_echo.rs

@@ -0,0 +1,61 @@
+// This file is part of the uutils coreutils package.
+//
+// For the full copyright and license information, please view the LICENSE
+// file that was distributed with this source code.
+
+use std::ffi::OsString;
+use uufuzz::{compare_result, generate_and_run_uumain, run_gnu_cmd};
+
+// Mock echo implementation for demonstration
+fn mock_echo_main(args: std::vec::IntoIter<OsString>) -> i32 {
+    let args: Vec<OsString> = args.collect();
+
+    // Skip the program name (first argument)
+    for (i, arg) in args.iter().skip(1).enumerate() {
+        if i > 0 {
+            print!(" ");
+        }
+        print!("{}", arg.to_string_lossy());
+    }
+    println!();
+    0
+}
+
+fn main() {
+    println!("=== Basic uufuzz Example ===");
+
+    // Test against GNU implementation
+    let args = vec![
+        OsString::from("echo"),
+        OsString::from("hello"),
+        OsString::from("world"),
+    ];
+
+    println!("Running mock echo implementation...");
+    let rust_result = generate_and_run_uumain(&args, mock_echo_main, None);
+
+    println!("Running GNU echo...");
+    match run_gnu_cmd("echo", &args[1..], false, None) {
+        Ok(gnu_result) => {
+            println!("Comparing results...");
+            compare_result(
+                "echo",
+                "hello world",
+                None,
+                &rust_result,
+                &gnu_result,
+                false,
+            );
+        }
+        Err(error_result) => {
+            println!("Failed to run GNU echo: {}", error_result.stderr);
+            println!("This is expected if GNU coreutils is not installed");
+
+            // Show what our implementation produced
+            println!("\nOur implementation result:");
+            println!("Stdout: '{}'", rust_result.stdout);
+            println!("Stderr: '{}'", rust_result.stderr);
+            println!("Exit code: {}", rust_result.exit_code);
+        }
+    }
+}

fuzz/uufuzz/examples/fuzzing_simulation.rs

@@ -0,0 +1,163 @@
+// This file is part of the uutils coreutils package.
+//
+// For the full copyright and license information, please view the LICENSE
+// file that was distributed with this source code.
+
+use rand::Rng;
+use std::ffi::OsString;
+use uufuzz::{generate_and_run_uumain, generate_random_string, run_gnu_cmd};
+
+// Mock echo implementation with some bugs for demonstration
+fn mock_buggy_echo_main(args: std::vec::IntoIter<OsString>) -> i32 {
+    let args: Vec<OsString> = args.collect();
+
+    let mut should_add_newline = true;
+    let mut enable_escapes = false;
+    let mut start_index = 1;
+
+    // Parse arguments (simplified)
+    for arg in args.iter().skip(1) {
+        let arg_str = arg.to_string_lossy();
+        if arg_str == "-n" {
+            should_add_newline = false;
+            start_index += 1;
+        } else if arg_str == "-e" {
+            enable_escapes = true;
+            start_index += 1;
+        } else {
+            break;
+        }
+    }
+
+    // Print arguments
+    for (i, arg) in args.iter().skip(start_index).enumerate() {
+        if i > 0 {
+            print!(" ");
+        }
+        let arg_str = arg.to_string_lossy();
+
+        if enable_escapes {
+            // Simulate a bug: incomplete escape sequence handling
+            let processed = arg_str.replace("\\n", "\n").replace("\\t", "\t");
+            print!("{}", processed);
+        } else {
+            print!("{}", arg_str);
+        }
+    }
+
+    if should_add_newline {
+        println!();
+    }
+
+    0
+}
+
+// Generate test arguments for echo command
+fn generate_echo_args() -> Vec<OsString> {
+    let mut rng = rand::rng();
+    let mut args = vec![OsString::from("echo")];
+
+    // Randomly add flags
+    if rng.random_bool(0.3) {
+        // 30% chance
+        args.push(OsString::from("-n"));
+    }
+    if rng.random_bool(0.2) {
+        // 20% chance
+        args.push(OsString::from("-e"));
+    }
+
+    // Add 1-3 random string arguments
+    let num_args = rng.random_range(1..=3);
+    for _ in 0..num_args {
+        let arg = generate_random_string(rng.random_range(1..=15));
+        args.push(OsString::from(arg));
+    }
+
+    args
+}
+
+fn main() {
+    println!("=== Fuzzing Simulation uufuzz Example ===");
+    println!("This simulates how libFuzzer would test our echo implementation");
+    println!("against GNU echo with random inputs.\n");
+
+    let num_tests = 10;
+    let mut passed = 0;
+    let mut failed = 0;
+
+    for i in 1..=num_tests {
+        println!("--- Fuzz Test {} ---", i);
+
+        let args = generate_echo_args();
+        println!(
+            "Testing with args: {:?}",
+            args.iter().map(|s| s.to_string_lossy()).collect::<Vec<_>>()
+        );
+
+        // Run our implementation
+        let rust_result = generate_and_run_uumain(&args, mock_buggy_echo_main, None);
+
+        // Run GNU implementation
+        match run_gnu_cmd("echo", &args[1..], false, None) {
+            Ok(gnu_result) => {
+                // Check if results match
+                let stdout_match = rust_result.stdout.trim() == gnu_result.stdout.trim();
+                let exit_code_match = rust_result.exit_code == gnu_result.exit_code;
+
+                if stdout_match && exit_code_match {
+                    println!("✓ PASS: Implementations match");
+                    passed += 1;
+                } else {
+                    println!("✗ FAIL: Implementations differ");
+                    failed += 1;
+
+                    // Show the difference in a controlled way (not panicking like compare_result)
+                    if !stdout_match {
+                        println!("  Stdout difference:");
+                        println!(
+                            "    Ours: '{}'",
+                            rust_result.stdout.trim().replace('\n', "\\n")
+                        );
+                        println!(
+                            "    GNU:  '{}'",
+                            gnu_result.stdout.trim().replace('\n', "\\n")
+                        );
+                    }
+                    if !exit_code_match {
+                        println!(
+                            "  Exit code difference: {} vs {}",
+                            rust_result.exit_code, gnu_result.exit_code
+                        );
+                    }
+                }
+            }
+            Err(error_result) => {
+                println!("⚠ GNU echo not available: {}", error_result.stderr);
+                println!("  Our result: '{}'", rust_result.stdout.trim());
+                // Don't count this as pass or fail
+                continue;
+            }
+        }
+
+        println!();
+    }
+
+    println!("=== Fuzzing Results ===");
+    println!("Total tests: {}", num_tests);
+    println!("Passed: {}", passed);
+    println!("Failed: {}", failed);
+
+    if failed > 0 {
+        println!(
+            "\n⚠ Found {} discrepancies! In real fuzzing, these would be investigated.",
+            failed
+        );
+        println!("This demonstrates how differential fuzzing can find bugs in implementations.");
+    } else {
+        println!("\n✓ All tests passed! The implementations appear compatible.");
+    }
+
+    println!("\nIn a real libfuzzer setup, this would run thousands of iterations");
+    println!("automatically with more sophisticated input generation.");
+}