docs/packaging guide: Reference test stage directory (#23707)

1 files changed, 15 insertions, 3 deletions

diff --git a/lib/spack/docs/packaging_guide.rst b/lib/spack/docs/packaging_guide.rst
index 8eab1afa68..24666fc44a 100644
--- a/lib/spack/docs/packaging_guide.rst
+++ b/lib/spack/docs/packaging_guide.rst
@@ -4192,9 +4192,11 @@ outputs can be added for use in these tests.
 Configuring the test stage directory
 """"""""""""""""""""""""""""""""""""
 
-The default stand-alone test stage directory, ``~/.spack/test``, is
-defined in :ref:`etc/spack/defaults/config.yaml <config-yaml>`.
-You can change the location in the high-level ``config`` by adding
+Stand-alone tests rely on a stage directory for building, running,
+and tracking results.
+The default directory, ``~/.spack/test``, is defined in
+:ref:`etc/spack/defaults/config.yaml <config-yaml>`.
+You can configure the location in the high-level ``config`` by adding
 or changing the ``test_stage`` path in the appropriate ``config.yaml``
 file such that:
 
@@ -4203,6 +4205,16 @@ file such that:
    config:
      test_stage: /path/to/stage
 
+The package can access this path **during test processing** using
+`self.test_suite.stage`. 
+
+.. note::
+
+   The test stage path is established for the entire suite. That
+   means it is the root directory for all specs being installed
+   with the same `spack test run` command. Each spec gets its
+   own stage subdirectory.
+
 """""""""""""""""""""""""
 Enabling test compilation
 """""""""""""""""""""""""