xianyun_testutil/

lib.rs

//! Shared test-support mocks for `xianyun-*` crates.
//!
//! This crate exists because `xianyun_executor::exec::CommandRunner` is a
//! `pub` trait implemented by clients across several crates
//! (`xianyun-backends`, `xianyun-cluster`, `xianyun-deploy`, ...), but
//! `xianyun-executor`'s own hand-rolled mock (`exec::mock::MockCommandRunner`)
//! is `pub(crate)` and cannot be reused outside that crate. Rather than
//! leave every downstream crate to hand-roll (and slowly diverge) its own
//! copy -- as `xianyun-backends`'s `testutil.rs` already had to -- this
//! crate provides one shared, more capable implementation as a
//! workspace-relative dev-dependency.
//!
//! Compared to the hand-rolled mocks it replaces, [`MockCommandRunner`]
//! adds two capabilities several `PORT_NOTES.md` files flagged as
//! missing:
//!
//! - **Predicate matching** (`expect_*_matching`), the equivalent of
//!   testify's `mock.MatchedBy`, for expectations that need to inspect
//!   arguments rather than match them exactly (e.g. a `--timeout=<dur>`
//!   value that shrinks across calls).
//! - **Repeating expectations** (`expect_*_repeating`), the equivalent of
//!   testify's `.Maybe()`, for expectations that may match any number of
//!   times (including zero) rather than exactly once.
//!
//! Every expectation is queued per `CommandRunner` method and matched
//! FIFO: when a call arrives, the first non-exhausted queued expectation
//! for that method whose matcher accepts the call's `(name, args)` wins.
//! Exact-match, one-shot expectations behave exactly like the mocks this
//! crate replaces (queue in the order you expect calls, first in first
//! served). Calling [`MockCommandRunner::verify`] -- or simply letting
//! the mock drop -- panics if any one-shot expectation was never fully
//! consumed; an unexpected call (nothing queued matches) always panics
//! immediately with a diagnostic listing what *was* queued.

mod expectation;

use std::path::PathBuf;
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::{Arc, Mutex};

use xianyun_executor::exec::{CommandRunner, ExecError, ExecResult, ExecStreamedOpts, Options};

use expectation::{Budget, Expectation, Matcher, collect_unmet, resolve};

/// A reusable, hand-rolled mock for `xianyun_executor::exec::CommandRunner`.
///
/// See the module-level documentation for the matching/exhaustion model.
/// Construct with [`MockCommandRunner::new`], queue expectations with the
/// `expect_*` methods, exercise it through the `CommandRunner` trait, and
/// either call [`MockCommandRunner::verify`] explicitly or let it drop at
/// the end of the test.
pub struct MockCommandRunner {
    run: Mutex<Vec<Expectation<ExecResult>>>,
    run_calls: Mutex<Vec<RecordedRunCall>>,
    read_stdout: Mutex<Vec<Expectation<Result<String, ExecError>>>>,
    run_sudo: Mutex<Vec<Expectation<Result<(), ExecError>>>>,
    check: Mutex<Vec<Expectation<Result<bool, ExecError>>>>,
    exec_streamed_command: Mutex<Vec<Expectation<Result<(), ExecError>>>>,
    look_path: Mutex<Vec<Expectation<Result<PathBuf, ExecError>>>>,
    run_in_repository: Mutex<Vec<Expectation<Result<(), ExecError>>>>,
    run_in_repository_calls: Mutex<Vec<RecordedRunInRepositoryCall>>,
    exec_streamed_command_calls: Mutex<Vec<RecordedExecStreamedCommandCall>>,
    verified: AtomicBool,
}

impl Default for MockCommandRunner {
    fn default() -> Self {
        Self {
            run: Mutex::new(Vec::new()),
            run_calls: Mutex::new(Vec::new()),
            read_stdout: Mutex::new(Vec::new()),
            run_sudo: Mutex::new(Vec::new()),
            check: Mutex::new(Vec::new()),
            exec_streamed_command: Mutex::new(Vec::new()),
            look_path: Mutex::new(Vec::new()),
            run_in_repository: Mutex::new(Vec::new()),
            run_in_repository_calls: Mutex::new(Vec::new()),
            exec_streamed_command_calls: Mutex::new(Vec::new()),
            verified: AtomicBool::new(false),
        }
    }
}

fn owned_args(args: &[&str]) -> Vec<String> {
    args.iter().map(|s| (*s).to_string()).collect()
}

/// Wraps a plain value as a one-shot responder: the value is moved out on
/// first (and only, since the expectation's budget is `Finite { remaining:
/// 1 }`) call.
fn once_responder<T: Send + 'static>(value: T) -> Box<dyn Fn() -> T + Send + Sync> {
    let slot = Mutex::new(Some(value));
    Box::new(move || {
        slot.lock()
            .unwrap()
            .take()
            .expect("MockCommandRunner: one-shot expectation invoked more than once")
    })
}

macro_rules! mock_method {
    (
        $queue:ident,
        $method_label:literal,
        $expect_exact:ident,
        $expect_matching:ident,
        $expect_repeating:ident,
        $result:ty
    ) => {
        /// Queues an exact-match, one-shot (called exactly once)
        /// expectation.
        pub fn $expect_exact(&self, name: &str, args: &[&str], result: $result) {
            self.$queue.lock().unwrap().push(Expectation::new(
                name.to_string(),
                Matcher::Exact(owned_args(args)),
                once_responder(result),
                Budget::Finite { remaining: 1 },
            ));
        }

        /// Queues a predicate-matched, one-shot expectation -- the
        /// equivalent of testify's `mock.MatchedBy`. `predicate` is
        /// evaluated against the call's arguments.
        pub fn $expect_matching(
            &self,
            name: &str,
            predicate: impl Fn(&[String]) -> bool + Send + Sync + 'static,
            result: $result,
        ) {
            self.$queue.lock().unwrap().push(Expectation::new(
                name.to_string(),
                Matcher::Predicate(Arc::new(predicate)),
                once_responder(result),
                Budget::Finite { remaining: 1 },
            ));
        }

        /// Queues an exact-match expectation that may match any number
        /// of times (including zero) -- the equivalent of testify's
        /// `.Maybe()`. `responder` is invoked fresh on every matching
        /// call, so it can return a fallible value type with no `Clone`
        /// bound.
        pub fn $expect_repeating(
            &self,
            name: &str,
            args: &[&str],
            responder: impl Fn() -> $result + Send + Sync + 'static,
        ) {
            self.$queue.lock().unwrap().push(Expectation::new(
                name.to_string(),
                Matcher::Exact(owned_args(args)),
                Box::new(responder),
                Budget::Unlimited,
            ));
        }
    };
}

impl MockCommandRunner {
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    mock_method!(
        run,
        "Run",
        expect_run,
        expect_run_matching,
        expect_run_repeating,
        ExecResult
    );
    mock_method!(
        read_stdout,
        "ReadStdout",
        expect_read_stdout,
        expect_read_stdout_matching,
        expect_read_stdout_repeating,
        Result<String, ExecError>
    );
    mock_method!(
        run_sudo,
        "RunSudo",
        expect_run_sudo,
        expect_run_sudo_matching,
        expect_run_sudo_repeating,
        Result<(), ExecError>
    );
    mock_method!(
        check,
        "Check",
        expect_check,
        expect_check_matching,
        expect_check_repeating,
        Result<bool, ExecError>
    );
    mock_method!(
        exec_streamed_command,
        "ExecStreamedCommand",
        expect_exec_streamed_command,
        expect_exec_streamed_command_matching,
        expect_exec_streamed_command_repeating,
        Result<(), ExecError>
    );
    mock_method!(
        run_in_repository,
        "RunInRepository",
        expect_run_in_repository,
        expect_run_in_repository_matching,
        expect_run_in_repository_repeating,
        Result<(), ExecError>
    );

    /// Queues an exact-match, one-shot expectation for `look_path(file)`.
    /// `look_path` has no `args` slice (it takes a single `file`), so it
    /// is not covered by the `mock_method` macro above.
    ///
    /// # Panics
    ///
    /// Panics if another thread poisoned this mock's internal lock by
    /// panicking while holding it.
    pub fn expect_look_path(&self, file: &str, result: Result<PathBuf, ExecError>) {
        self.look_path.lock().unwrap().push(Expectation::new(
            file.to_string(),
            Matcher::Exact(Vec::new()),
            once_responder(result),
            Budget::Finite { remaining: 1 },
        ));
    }

    /// Queues a `look_path(file)` expectation that may match any number
    /// of times.
    ///
    /// # Panics
    ///
    /// Panics if another thread poisoned this mock's internal lock by
    /// panicking while holding it.
    pub fn expect_look_path_repeating(
        &self,
        file: &str,
        responder: impl Fn() -> Result<PathBuf, ExecError> + Send + Sync + 'static,
    ) {
        self.look_path.lock().unwrap().push(Expectation::new(
            file.to_string(),
            Matcher::Exact(Vec::new()),
            Box::new(responder),
            Budget::Unlimited,
        ));
    }

    /// Returns every recorded call to `run`, in call order, regardless of
    /// whether an expectation matched it. Use this to assert on `opts`
    /// (particularly `opts.env`) -- the one thing `expect_run_matching`'s
    /// predicate can't see. This mirrors `run_in_repository`/
    /// `exec_streamed_command`'s own recorded-calls accessors; `run` only
    /// grew one once a real bug (`xianyun-backends::kubectl::Client`
    /// never wiring `KUBECONFIG` into `Options::env`) went undetected
    /// because nothing could assert on `run`'s `opts` -- see
    /// `crates/xianyun-backends/PORT_NOTES.md`.
    ///
    /// # Panics
    ///
    /// Panics if another thread poisoned this mock's internal lock by
    /// panicking while holding it.
    #[must_use]
    pub fn recorded_run_calls(&self) -> Vec<RecordedRunCall> {
        self.run_calls.lock().unwrap().clone()
    }

    /// Returns every recorded call to `run_in_repository`, in call order,
    /// regardless of whether an expectation matched it. Use this to
    /// assert on `opts` (particularly `opts.env`) -- the one thing
    /// `expect_run_in_repository_matching`'s predicate can't see.
    ///
    /// # Panics
    ///
    /// Panics if another thread poisoned this mock's internal lock by
    /// panicking while holding it.
    #[must_use]
    pub fn recorded_run_in_repository_calls(&self) -> Vec<RecordedRunInRepositoryCall> {
        self.run_in_repository_calls.lock().unwrap().clone()
    }

    /// Returns every recorded call to `exec_streamed_command`, in call
    /// order, regardless of whether an expectation matched it. Use this
    /// to assert on `opts` (particularly `opts.env`) -- the one thing
    /// `expect_exec_streamed_command_matching`'s predicate can't see.
    ///
    /// # Panics
    ///
    /// Panics if another thread poisoned this mock's internal lock by
    /// panicking while holding it.
    #[must_use]
    pub fn recorded_exec_streamed_command_calls(&self) -> Vec<RecordedExecStreamedCommandCall> {
        self.exec_streamed_command_calls.lock().unwrap().clone()
    }

    /// Checks every queued expectation across every mocked method and
    /// panics, listing them, if any one-shot (non-repeating) expectation
    /// was never fully consumed. Safe to call multiple times: only the
    /// first call can panic, since matched expectations are removed from
    /// their queues as they're consumed. Also run implicitly on
    /// [`Drop`] if not called explicitly (skipped if the test is already
    /// panicking, to avoid a double panic during unwind).
    ///
    /// # Panics
    ///
    /// Panics if any one-shot expectation across any mocked method was
    /// never fully consumed, or if another thread poisoned this mock's
    /// internal lock by panicking while holding it.
    pub fn verify(&self) {
        self.verified.store(true, Ordering::SeqCst);

        let mut unmet = Vec::new();
        collect_unmet(&self.run.lock().unwrap(), "Run", &mut unmet);
        collect_unmet(&self.read_stdout.lock().unwrap(), "ReadStdout", &mut unmet);
        collect_unmet(&self.run_sudo.lock().unwrap(), "RunSudo", &mut unmet);
        collect_unmet(&self.check.lock().unwrap(), "Check", &mut unmet);
        collect_unmet(
            &self.exec_streamed_command.lock().unwrap(),
            "ExecStreamedCommand",
            &mut unmet,
        );
        collect_unmet(&self.look_path.lock().unwrap(), "LookPath", &mut unmet);
        collect_unmet(
            &self.run_in_repository.lock().unwrap(),
            "RunInRepository",
            &mut unmet,
        );

        assert!(
            unmet.is_empty(),
            "MockCommandRunner::verify: {} expectation(s) never matched:\n{}",
            unmet.len(),
            unmet.join("\n")
        );
    }
}

impl Drop for MockCommandRunner {
    fn drop(&mut self) {
        if self.verified.load(Ordering::SeqCst) || std::thread::panicking() {
            return;
        }
        self.verify();
    }
}

impl CommandRunner for MockCommandRunner {
    fn run(&self, name: &str, args: &[String], opts: Option<Options>) -> ExecResult {
        // `Options::stdin` is `Box<dyn Read + Send>`, which isn't `Clone`,
        // so the recorded call carries the fields a test would plausibly
        // want to assert on (particularly `env`) rather than the whole
        // `Options` -- `opts` is moved here, not borrowed, since `resolve`
        // below never reads it (matching is on `name`/`args` only).
        self.run_calls.lock().unwrap().push(RecordedRunCall {
            name: name.to_string(),
            args: args.to_vec(),
            env: opts.as_ref().and_then(|o| o.env.clone()),
            timeout: opts.as_ref().and_then(|o| o.timeout),
        });
        resolve(&mut self.run.lock().unwrap(), "Run", name, args)
    }

    fn read_stdout(&self, name: &str, args: &[String]) -> Result<String, ExecError> {
        resolve(
            &mut self.read_stdout.lock().unwrap(),
            "ReadStdout",
            name,
            args,
        )
    }

    fn run_sudo(&self, name: &str, args: &[String]) -> Result<(), ExecError> {
        resolve(&mut self.run_sudo.lock().unwrap(), "RunSudo", name, args)
    }

    fn check(&self, name: &str, args: &[String]) -> Result<bool, ExecError> {
        resolve(&mut self.check.lock().unwrap(), "Check", name, args)
    }

    fn exec_streamed_command(
        &self,
        opts: Option<ExecStreamedOpts>,
        name: &str,
        args: &[String],
    ) -> Result<(), ExecError> {
        self.exec_streamed_command_calls
            .lock()
            .unwrap()
            .push(RecordedExecStreamedCommandCall {
                name: name.to_string(),
                args: args.to_vec(),
                opts: opts.clone(),
            });
        resolve(
            &mut self.exec_streamed_command.lock().unwrap(),
            "ExecStreamedCommand",
            name,
            args,
        )
    }

    fn look_path(&self, file: &str) -> Result<PathBuf, ExecError> {
        resolve(&mut self.look_path.lock().unwrap(), "LookPath", file, &[])
    }

    fn run_in_repository(
        &self,
        repo_dir: &str,
        name: &str,
        args: &[String],
        opts: Option<ExecStreamedOpts>,
    ) -> Result<(), ExecError> {
        self.run_in_repository_calls
            .lock()
            .unwrap()
            .push(RecordedRunInRepositoryCall {
                repo_dir: repo_dir.to_string(),
                name: name.to_string(),
                args: args.to_vec(),
                opts: opts.clone(),
            });
        // `run_in_repository` is keyed on `name` (the command), matching
        // every other method; `repo_dir` is folded into the matched
        // arguments so expectations can still distinguish repositories
        // without a dedicated queue shape.
        let mut full_args = vec![repo_dir.to_string()];
        full_args.extend_from_slice(args);
        resolve(
            &mut self.run_in_repository.lock().unwrap(),
            "RunInRepository",
            name,
            &full_args,
        )
    }
}

/// One recorded call to [`MockCommandRunner::run`], captured regardless of
/// whether an expectation matched it. Exists because `Matcher::Predicate`
/// only sees `(name, args)`, not `opts`. Carries `env`/`timeout` rather
/// than the full `Options`, since `Options::stdin` (`Box<dyn Read + Send>`)
/// isn't `Clone` and doesn't need recording for this purpose anyway --
/// see [`MockCommandRunner::recorded_run_calls`].
#[derive(Debug, Clone)]
pub struct RecordedRunCall {
    pub name: String,
    pub args: Vec<String>,
    pub env: Option<Vec<String>>,
    pub timeout: Option<std::time::Duration>,
}

/// One recorded call to [`MockCommandRunner::run_in_repository`], captured
/// regardless of whether an expectation matched it. Exists because
/// `Matcher::Predicate` only sees `(name, args)`, not `opts` -- `Options`
/// and `ExecStreamedOpts` carry fields (`env`, in particular) several
/// `PORT_NOTES.md` files flagged as needing inspection that the
/// expectation-matching system can't offer directly. See
/// [`MockCommandRunner::recorded_run_in_repository_calls`].
#[derive(Debug, Clone)]
pub struct RecordedRunInRepositoryCall {
    pub repo_dir: String,
    pub name: String,
    pub args: Vec<String>,
    pub opts: Option<ExecStreamedOpts>,
}

/// One recorded call to [`MockCommandRunner::exec_streamed_command`],
/// captured regardless of whether an expectation matched it. See
/// [`RecordedRunInRepositoryCall`] for why this exists.
#[derive(Debug, Clone)]
pub struct RecordedExecStreamedCommandCall {
    pub name: String,
    pub args: Vec<String>,
    pub opts: Option<ExecStreamedOpts>,
}

#[cfg(test)]
mod tests;