From 7fdb437ea36100ab6dc26a45a404fb54170f3f89 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vin=C3=ADcius=20Ferr=C3=A3o?=
 <2031761+viniciusferrao@users.noreply.github.com>
Date: Fri, 9 Oct 2026 22:24:21 -0300
Subject: [PATCH] docs(test): describe the shared command runner

---
 xCAT-test/lib/XCAT/Test/Process.pm | 19 +++++++++++++++++++
 xCAT-test/unit/README.md           | 25 +++++++++++++++++++++++++
 2 files changed, 44 insertions(+)

diff --git a/xCAT-test/lib/XCAT/Test/Process.pm b/xCAT-test/lib/XCAT/Test/Process.pm
index 3852b2f3f..12e4d30c5 100644
--- a/xCAT-test/lib/XCAT/Test/Process.pm
+++ b/xCAT-test/lib/XCAT/Test/Process.pm
@@ -27,3 +27,22 @@ sub run_command {
 }
 
 1;
+
+__END__
+
+=head1 NAME
+
+XCAT::Test::Process - command execution for source-tree tests
+
+=head1 FUNCTIONS
+
+=head2 run_command
+
+Runs a literal argument list and returns the normal exit code and combined
+stdout/stderr output. Requires list context. Execution failures and signal
+termination raise errors.
+
+Inherits the caller's environment and directory. Capture::Tiny applies the
+caller's STDOUT PerlIO layers; use raw STDOUT for byte comparisons.
+
+=cut
diff --git a/xCAT-test/unit/README.md b/xCAT-test/unit/README.md
index 2677e3369..e26231886 100644
--- a/xCAT-test/unit/README.md
+++ b/xCAT-test/unit/README.md
@@ -36,6 +36,31 @@ installed under `/opt/xcat/share/xcat/tools/autotest/unit` is not a substitute -
 skip. The CI takes a copy of the checkout before the build for this reason; see
 `preserve_source_tree()`.
 
+## Running commands from Perl tests
+
+Use `XCAT::Test::Process` when a test needs a command's exit code and combined
+standard output and standard error:
+
+```perl
+use FindBin;
+use lib "$FindBin::Bin/../lib";
+use XCAT::Test::Process qw(run_command);
+
+my ($status, $output) = run_command('/bin/sh', $script, '--check');
+```
+
+Call `run_command` in list context. It passes arguments without shell expansion
+and returns the normal exit code with the captured output. A command that cannot
+execute or terminates on a signal raises an error. Scalar and void contexts also
+raise errors, so they cannot discard the exit code.
+
+The helper uses `Capture::Tiny`, which the unit suite already requires. Captured
+output follows the caller's STDOUT PerlIO layers. Use `binmode STDOUT, ':raw'`
+before capture when comparing raw bytes.
+
+The command inherits the caller's environment and working directory. Keep
+fixture-specific environment changes and directory selection in the test.
+
 ## What does not belong here
 
 Tests that build RPMs, create Linux namespaces or start service binaries belong