From 3d09f4a0685c868d6c0d88c4692f217df07bfa43 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vin=C3=ADcius=20Ferr=C3=A3o?=
 <2031761+viniciusferrao@users.noreply.github.com>
Date: Tue, 22 Sep 2026 03:08:26 -0300
Subject: [PATCH] docs(test): describe the otherpkgs sandbox prerequisites

---
 xCAT-test/bats/README.md |  3 +++
 xCAT-test/unit/README.md | 13 +++++++++++++
 2 files changed, 16 insertions(+)

diff --git a/xCAT-test/bats/README.md b/xCAT-test/bats/README.md
index ac65379ab..11dce7d9d 100644
--- a/xCAT-test/bats/README.md
+++ b/xCAT-test/bats/README.md
@@ -10,6 +10,9 @@ The GitHub Actions `xcat_test` workflow runs this command after the Perl `.t`
 unit tests. Use BATS for shell behavior that can be exercised from the source
 tree without an installed xCAT, a live management node, or real services.
 
+The existing `otherpkgs_upgrade_scope.t` remains in `unit/` for its structured
+command and repository assertions. See its [sandbox prerequisites](../unit/README.md#postscript-sandbox-prerequisites).
+
 Prefer sourcing an existing shell library or sourceable script and calling the
 function under test. Keep reusable install-template helpers in
 `xCAT-server/share/xcat/install/scripts/scriptlib`, and reusable postscript
diff --git a/xCAT-test/unit/README.md b/xCAT-test/unit/README.md
index daff2691c..ce343b18d 100644
--- a/xCAT-test/unit/README.md
+++ b/xCAT-test/unit/README.md
@@ -10,6 +10,19 @@ which calls `run_unit_tests()` in `github_action_xcat_test.pl`:
 prove -r xCAT-test/unit
 ```
 
+## Postscript sandbox prerequisites
+
+`otherpkgs_upgrade_scope.t` runs the complete postscript in a Linux filesystem
+sandbox. It requires Bubblewrap, Bash, GNU core utilities, and permission to create
+user namespaces. The CI workflow installs Bubblewrap and enables those namespaces.
+Missing prerequisites fail this test without stopping unrelated test files.
+Non-Linux hosts report a skip. Set `TMPDIR` to a writable, executable filesystem
+if the default temporary directory is mounted with `noexec`.
+
+This test is an exception to the shell-test placement rule below. It stays in Perl
+to compare structured command arguments and generated repository records with the
+existing test helpers. It does not read or extract postscript source.
+
 You can run exactly the same thing from a clean checkout:
 
 ```