From 43e690dd1313aa476072ac60142318d5a6180214 Mon Sep 17 00:00:00 2001
From: Eric Huss <eric@huss.org>
Date: Mon, 11 Aug 2025 19:15:53 -0700
Subject: [PATCH] Add debug option to the testsuite

This adds a basic debug method to the testsuite command to help with
diagnosing tests that aren't working as expected.
---
 tests/testsuite/book_test.rs | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/tests/testsuite/book_test.rs b/tests/testsuite/book_test.rs
index e40ca63c..f15faccf 100644
--- a/tests/testsuite/book_test.rs
+++ b/tests/testsuite/book_test.rs
@@ -227,6 +227,7 @@ impl BookTest {
             expect_status: StatusCode::Success,
             expect_stderr_data: None,
             expect_stdout_data: None,
+            debug: None,
         };
         f(&mut cmd);
         cmd.run();
@@ -272,6 +273,7 @@ pub struct BookCommand {
     expect_status: StatusCode,
     expect_stderr_data: Option<snapbox::Data>,
     expect_stdout_data: Option<snapbox::Data>,
+    debug: Option<String>,
 }
 
 impl BookCommand {
@@ -311,6 +313,21 @@ impl BookCommand {
         self
     }
 
+    /// Use this to debug a command.
+    ///
+    /// Pass the value that you would normally pass to `RUST_LOG`, and this
+    /// will enable logging, print the command that runs and its output.
+    ///
+    /// This will fail if you use it in CI.
+    #[allow(unused)]
+    pub fn debug(&mut self, value: &str) -> &mut Self {
+        if std::env::var_os("CI").is_some() {
+            panic!("debug is not allowed on CI");
+        }
+        self.debug = Some(value.into());
+        self
+    }
+
     /// Runs the command, and verifies the output.
     fn run(&mut self) {
         let mut cmd = Command::new(env!("CARGO_BIN_EXE_mdbook"));
@@ -326,6 +343,10 @@ impl BookCommand {
             .env_remove("GIT_COMMITTER_EMAIL")
             .env_remove("GIT_COMMITTER_NAME");
 
+        if let Some(debug) = &self.debug {
+            cmd.env("RUST_LOG", debug);
+        }
+
         for (k, v) in &self.env {
             match v {
                 Some(v) => cmd.env(k, v),
@@ -333,6 +354,9 @@ impl BookCommand {
             };
         }
 
+        if self.debug.is_some() {
+            eprintln!("running {cmd:#?}");
+        }
         let output = cmd.output().expect("mdbook should be runnable");
         let stdout = std::str::from_utf8(&output.stdout).expect("stdout is not utf8");
         let stderr = std::str::from_utf8(&output.stderr).expect("stderr is not utf8");
@@ -353,6 +377,9 @@ impl BookCommand {
             },
             _ => {}
         }
+        if self.debug.is_some() {
+            eprintln!("{}", render_output());
+        }
         self.expect_status = StatusCode::Success; // Reset to default.
         if let Some(expect_stderr_data) = &self.expect_stderr_data {
             if let Err(e) = self.assert.try_eq(