Add test for success path

Adds missing test coverage for rustdoc's `--test-builder` option.

The existing test only covered the error case (non-executable builder). This PR
adds:
- A custom test builder that logs arguments and forwards to rustc
- A test verifying that `--test-builder` successfully invokes the custom
builder with rustc-style arguments
- Improved comments explaining both the error and success test scenarios

The test validates that custom builders can properly intercept and handle
doctest compilation.

Signed-off-by: Osama Abdelkader <osama.abdelkader@gmail.com>

tests/run-make/rustdoc-test-builder/builder.rs

@@ -0,0 +1,23 @@
+use std::ffi::OsString;
+use std::path::PathBuf;
+use std::process::{self, Command};
+use std::{env, fs};
+
+fn main() {
+    let args: Vec<OsString> = env::args_os().collect();
+    let log_path = env::var_os("BUILDER_LOG").map(PathBuf::from).expect("BUILDER_LOG must be set");
+    let real_rustc = env::var_os("REAL_RUSTC").expect("REAL_RUSTC must be set");
+
+    let log_contents =
+        args.iter().skip(1).map(|arg| arg.to_string_lossy()).collect::<Vec<_>>().join("\n");
+    fs::write(&log_path, log_contents).expect("failed to write builder log");
+
+    let status = Command::new(real_rustc)
+        .args(args.iter().skip(1))
+        .status()
+        .expect("failed to invoke real rustc");
+
+    if !status.success() {
+        process::exit(status.code().unwrap_or(1));
+    }
+}

tests/run-make/rustdoc-test-builder/doctest.rs

@@ -0,0 +1,3 @@
+//! ```rust
+//! assert_eq!(2 + 2, 4);
+//! ```

tests/run-make/rustdoc-test-builder/rmake.rs

@@ -1,11 +1,14 @@
-// This test ensures that if the rustdoc test binary is not executable, it will
-// gracefully fail and not panic.
+// This test validates the `--test-builder` rustdoc option.
+// It ensures that:
+// 1. When the test-builder path points to a non-executable file, rustdoc gracefully fails
+// 2. When the test-builder path points to a valid executable, it receives rustc arguments
 
 //@ needs-target-std
 
-use run_make_support::{path, rfs, rustdoc};
+use run_make_support::{path, rfs, rustc, rustc_path, rustdoc};
 
 fn main() {
+    // Test 1: Verify that a non-executable test-builder fails gracefully
     let absolute_path = path("foo.rs").canonicalize().expect("failed to get absolute path");
     let output = rustdoc()
         .input("foo.rs")
@@ -19,4 +22,30 @@ fn main() {
     output.assert_stdout_contains("Failed to spawn ");
     // ... and that we didn't panic.
     output.assert_not_ice();
+
+    // Test 2: Verify that a valid test-builder is invoked with correct arguments
+    // Build a custom test-builder that logs its arguments and forwards to rustc
+    let builder_bin = path("builder-bin");
+    rustc().input("builder.rs").output(&builder_bin).run();
+
+    let log_path = path("builder.log");
+    let _ = std::fs::remove_file(&log_path);
+
+    // Run rustdoc with our custom test-builder
+    rustdoc()
+        .input("doctest.rs")
+        .arg("--test")
+        .arg("-Zunstable-options")
+        .arg("--test-builder")
+        .arg(&builder_bin)
+        .env("REAL_RUSTC", rustc_path())
+        .env("BUILDER_LOG", &log_path)
+        .run();
+
+    // Verify the custom builder was invoked with rustc-style arguments
+    let log_contents = rfs::read_to_string(&log_path);
+    assert!(
+        log_contents.contains("--crate-type"),
+        "expected builder to receive rustc arguments, got:\n{log_contents}"
+    );
 }