Refactor for testability: extract functions and deduplicate panic_message

- Move panic_message to control.rs, remove duplicates from runner.rs and stateful.rs
- Extract filter_backtrace from format_backtrace in runner.rs
- Extract install_hegel_server from ensure_hegel_installed in runner.rs
- Extract handle_antithesis_reporting from Hegel::run() in runner.rs
- Add RequestErrorKind enum and classify_request_error to test_case.rs
- Change PROTOCOL_DEBUG from LazyLock static to plain function
- Add ENV_TEST_MUTEX to lib.rs for test serialization
- Add lcov.info to .gitignore

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

Author: DRMacIver

.gitignore

@@ -15,6 +15,8 @@ result
 .claude-reliability/
 .claude/reliability-config.yml
 
+lcov.info
+
 # claude-reliability managed
 .claude/bin/
 .claude/*.local.md

RELEASE.md

@@ -0,0 +1,3 @@
+RELEASE_TYPE: patch
+
+Internal refactoring for testability. No user-visible changes.

src/control.rs

@@ -12,6 +12,17 @@ pub(crate) fn with_test_context<R>(f: impl FnOnce() -> R) -> R {
     result
 }
 
+/// Extract a message from a panic payload.
+pub(crate) fn panic_message(payload: &Box<dyn std::any::Any + Send>) -> String {
+    if let Some(s) = payload.downcast_ref::<&str>() {
+        s.to_string()
+    } else if let Some(s) = payload.downcast_ref::<String>() {
+        s.clone()
+    } else {
+        "Unknown panic".to_string()
+    }
+}
+
 /// Returns `true` if we are currently inside a Hegel test context.
 ///
 /// This can be used to conditionally execute code that depends on a

src/lib.rs

@@ -221,3 +221,8 @@ pub use hegel_macros::test;
 #[doc(hidden)]
 pub use runner::hegel;
 pub use runner::{HealthCheck, Hegel, Settings, Verbosity};
+
+/// Mutex for serializing tests that modify environment variables.
+/// Used across runner, antithesis, and integration test modules to prevent races.
+#[doc(hidden)]
+pub static ENV_TEST_MUTEX: std::sync::Mutex<()> = std::sync::Mutex::new(());

src/runner.rs

@@ -1,5 +1,5 @@
 use crate::antithesis::{TestLocation, is_running_in_antithesis};
-use crate::control::{currently_in_test_context, with_test_context};
+use crate::control::{currently_in_test_context, panic_message, with_test_context};
 use crate::protocol::{Channel, Connection, HANDSHAKE_STRING, SERVER_CRASHED_MESSAGE};
 use crate::test_case::{ASSUME_FAIL_STRING, STOP_TEST_STRING, TestCase};
 use ciborium::Value;
@@ -145,11 +145,17 @@ fn take_panic_info() -> Option<(String, String, String, Backtrace)> {
 /// Frame numbers are renumbered to start at 0.
 fn format_backtrace(bt: &Backtrace, full: bool) -> String {
     let backtrace_str = format!("{}", bt);
-
     if full {
         return backtrace_str;
     }
+    filter_backtrace(&backtrace_str)
+}
 
+/// Filter a backtrace string to "short" format.
+///
+/// Keeps only frames between `__rust_end_short_backtrace` and
+/// `__rust_begin_short_backtrace` markers, renumbering from 0.
+fn filter_backtrace(backtrace_str: &str) -> String {
     // Filter to short backtrace: keep lines between the markers
     // Frame groups look like:
     //    N: function::name
@@ -266,20 +272,27 @@ fn init_panic_hook() {
 }
 
 fn ensure_hegel_installed() -> Result<String, String> {
-    let venv_dir = format!("{HEGEL_SERVER_DIR}/venv");
+    install_hegel_server(HEGEL_SERVER_DIR, HEGEL_SERVER_VERSION)
+}
+
+/// Install the hegel server into a directory using `uv`.
+///
+/// Returns the path to the installed `hegel` binary on success.
+fn install_hegel_server(server_dir: &str, version: &str) -> Result<String, String> {
+    let venv_dir = format!("{server_dir}/venv");
     let version_file = format!("{venv_dir}/hegel-version");
     let hegel_bin = format!("{venv_dir}/bin/hegel");
-    let install_log = format!("{HEGEL_SERVER_DIR}/install.log");
+    let install_log = format!("{server_dir}/install.log");
 
     // Check cached version
     if let Ok(cached) = std::fs::read_to_string(&version_file) {
-        if cached.trim() == HEGEL_SERVER_VERSION && std::path::Path::new(&hegel_bin).is_file() {
+        if cached.trim() == version && std::path::Path::new(&hegel_bin).is_file() {
             return Ok(hegel_bin);
         }
     }
 
-    std::fs::create_dir_all(HEGEL_SERVER_DIR)
-        .map_err(|e| format!("Failed to create {HEGEL_SERVER_DIR}: {e}"))?;
+    std::fs::create_dir_all(server_dir)
+        .map_err(|e| format!("Failed to create {server_dir}: {e}"))?;
 
     let log_file = std::fs::File::create(&install_log)
         .map_err(|e| format!("Failed to create install log: {e}"))?;
@@ -310,7 +323,7 @@ fn ensure_hegel_installed() -> Result<String, String> {
             "install",
             "--python",
             &python_path,
-            &format!("hegel-core=={HEGEL_SERVER_VERSION}"),
+            &format!("hegel-core=={version}"),
         ])
         .stderr(log_file.try_clone().unwrap())
         .stdout(log_file)
@@ -319,7 +332,7 @@ fn ensure_hegel_installed() -> Result<String, String> {
     if !status.success() {
         let log = std::fs::read_to_string(&install_log).unwrap_or_default();
         return Err(format!(
-            "Failed to install hegel-core (version: {HEGEL_SERVER_VERSION}). \
+            "Failed to install hegel-core (version: {version}). \
              Set {HEGEL_SERVER_COMMAND_ENV} to a hegel binary path to skip installation.\n\
              Install log:\n{log}"
         ));
@@ -329,7 +342,7 @@ fn ensure_hegel_installed() -> Result<String, String> {
         return Err(format!("hegel not found at {hegel_bin} after installation"));
     }
 
-    std::fs::write(&version_file, HEGEL_SERVER_VERSION)
+    std::fs::write(&version_file, version)
         .map_err(|e| format!("Failed to write version file: {e}"))?;
 
     Ok(hegel_bin)
@@ -793,18 +806,7 @@ where
 
         let test_failed = !passed || got_interesting.load(Ordering::SeqCst);
 
-        if is_running_in_antithesis() {
-            #[cfg(not(feature = "antithesis"))]
-            panic!(
-                "When Hegel is run inside of Antithesis, it requires the `antithesis` feature. \
-                You can add it with {{ features = [\"antithesis\"] }}."
-            );
-
-            #[cfg(feature = "antithesis")]
-            if let Some(ref loc) = self.test_location {
-                crate::antithesis::emit_assertion(loc, !test_failed);
-            }
-        }
+        handle_antithesis_reporting(self.test_location.as_ref(), test_failed);
 
         if test_failed {
             let msg = match &final_result {
@@ -909,14 +911,19 @@ fn run_test_case<F: FnMut(TestCase)>(
     tc_result
 }
 
-/// Extract a message from a panic payload.
-fn panic_message(payload: &Box<dyn std::any::Any + Send>) -> String {
-    if let Some(s) = payload.downcast_ref::<&str>() {
-        s.to_string()
-    } else if let Some(s) = payload.downcast_ref::<String>() {
-        s.clone()
-    } else {
-        "Unknown panic".to_string()
+/// Report test results to Antithesis if running in that environment.
+fn handle_antithesis_reporting(test_location: Option<&TestLocation>, test_failed: bool) {
+    if is_running_in_antithesis() {
+        #[cfg(not(feature = "antithesis"))]
+        panic!(
+            "When Hegel is run inside of Antithesis, it requires the `antithesis` feature. \
+            You can add it with {{ features = [\"antithesis\"] }}."
+        );
+
+        #[cfg(feature = "antithesis")]
+        if let Some(loc) = test_location {
+            crate::antithesis::emit_assertion(loc, !test_failed);
+        }
     }
 }
 

src/stateful.rs

@@ -62,6 +62,7 @@
 
 use crate::TestCase;
 use crate::cbor_utils::cbor_map;
+use crate::control::panic_message;
 use crate::generators::integers;
 use crate::test_case::{ASSUME_FAIL_STRING, STOP_TEST_STRING};
 use ciborium::Value;
@@ -179,17 +180,6 @@ pub trait StateMachine {
     fn invariants(&self) -> Vec<Rule<Self>>;
 }
 
-// TODO: factor out (shared with runner.rs)
-fn panic_message(payload: &Box<dyn std::any::Any + Send>) -> String {
-    if let Some(s) = payload.downcast_ref::<&str>() {
-        s.to_string()
-    } else if let Some(s) = payload.downcast_ref::<String>() {
-        s.clone()
-    } else {
-        "Unknown panic".to_string()
-    }
-}
-
 fn check_invariants(m: &mut impl StateMachine, tc: &TestCase) {
     let invariants = m.invariants();
     for invariant in invariants {

src/test_case.rs

@@ -5,7 +5,7 @@ use crate::runner::Verbosity;
 use ciborium::Value;
 use std::cell::RefCell;
 use std::rc::Rc;
-use std::sync::{Arc, LazyLock};
+use std::sync::Arc;
 
 use crate::generators::value;
 
@@ -35,15 +35,38 @@ impl std::fmt::Display for StopTestError {
 }
 impl std::error::Error for StopTestError {}
 
-static PROTOCOL_DEBUG: LazyLock<bool> = LazyLock::new(|| {
+fn protocol_debug() -> bool {
     matches!(
         std::env::var("HEGEL_PROTOCOL_DEBUG")
             .unwrap_or_default()
             .to_lowercase()
             .as_str(),
         "1" | "true"
     )
-});
+}
+
+#[derive(Debug, PartialEq)]
+pub(crate) enum RequestErrorKind {
+    StopTest,
+    FlakyReplay,
+    ServerCrashed,
+    CommunicationError,
+}
+
+pub(crate) fn classify_request_error(error_msg: &str, server_exited: bool) -> RequestErrorKind {
+    if error_msg.contains("overflow")
+        || error_msg.contains("StopTest")
+        || error_msg.contains("channel is closed")
+    {
+        RequestErrorKind::StopTest
+    } else if error_msg.contains("FlakyStrategyDefinition") || error_msg.contains("FlakyReplay") {
+        RequestErrorKind::FlakyReplay
+    } else if server_exited {
+        RequestErrorKind::ServerCrashed
+    } else {
+        RequestErrorKind::CommunicationError
+    }
+}
 
 pub(crate) const ASSUME_FAIL_STRING: &str = "__HEGEL_ASSUME_FAIL";
 
@@ -269,7 +292,7 @@ impl TestCase {
         if global.test_aborted {
             return Err(StopTestError);
         }
-        let debug = *PROTOCOL_DEBUG || global.verbosity == Verbosity::Debug;
+        let debug = protocol_debug() || global.verbosity == Verbosity::Debug;
 
         let mut entries = vec![(
             Value::Text("command".to_string()),
@@ -300,32 +323,31 @@ impl TestCase {
             }
             Err(e) => {
                 let error_msg = e.to_string();
-                if error_msg.contains("overflow")
-                    || error_msg.contains("StopTest")
-                    || error_msg.contains("channel is closed")
-                {
-                    if debug {
-                        eprintln!("RESPONSE: StopTest/overflow");
+                let server_exited = self.global.borrow().connection.server_has_exited();
+                match classify_request_error(&error_msg, server_exited) {
+                    RequestErrorKind::StopTest => {
+                        if debug {
+                            eprintln!("RESPONSE: StopTest/overflow");
+                        }
+                        let mut global = self.global.borrow_mut();
+                        global.channel.mark_closed();
+                        global.test_aborted = true;
+                        drop(global);
+                        Err(StopTestError)
+                    }
+                    RequestErrorKind::FlakyReplay => {
+                        let mut global = self.global.borrow_mut();
+                        global.channel.mark_closed();
+                        global.test_aborted = true;
+                        drop(global);
+                        Err(StopTestError)
+                    }
+                    RequestErrorKind::ServerCrashed => {
+                        panic!("{}", SERVER_CRASHED_MESSAGE);
+                    }
+                    RequestErrorKind::CommunicationError => {
+                        panic!("Failed to communicate with Hegel: {}", e);
                     }
-                    let mut global = self.global.borrow_mut();
-                    global.channel.mark_closed();
-                    global.test_aborted = true;
-                    drop(global);
-                    Err(StopTestError)
-                } else if error_msg.contains("FlakyStrategyDefinition")
-                    || error_msg.contains("FlakyReplay")
-                {
-                    // Abort the test case; the server will report the flaky
-                    // error in the test_done results, which runner.rs handles.
-                    let mut global = self.global.borrow_mut();
-                    global.channel.mark_closed();
-                    global.test_aborted = true;
-                    drop(global);
-                    Err(StopTestError)
-                } else if self.global.borrow().connection.server_has_exited() {
-                    panic!("{}", SERVER_CRASHED_MESSAGE);
-                } else {
-                    panic!("Failed to communicate with Hegel: {}", e);
                 }
             }
         }