Document foreign ctest and test-install in install/CMake docs

Expand NRN_ENABLE_TESTS (in-tree vs test-install), wheel testing via
test/foreign, and cross-links from install instructions, developer
index, coverage, and GPU testing pages.

Author: nrnhines

docs/cmake_doc/options.rst

@@ -533,27 +533,98 @@ Readline_ROOT_DIR:PATH=/usr
 
 NRN_ENABLE_TESTS:BOOL=OFF
 -------------------------
-  Enable unit tests
-
-  Clones the submodule catch2 from https://github.com/catchorg/Catch2.git and after a build using
-  ``make`` can run the tests with ``make test``.
-  May also need to ``pip install pytest``.
-  ``make test`` is quite terse. To get the same verbose output that is
-  seen with the CI tests, use ``ctest -VV`` (executed in the
-  build folder) or an individual test with ``ctest -VV -R name_of_the_test``.
-  One can also run individual test files
-  with ``python3 -m pytest -s <testfile.py>`` or all the test files in that
-  folder with ``python3 -m pytest -s``. (The ``-s`` shows all output on
-  the terminal.) Note: It is helpful to ``make test``
-  first to ensure any mod files needed are available to the tests. If
-  running a test outside the folder where the test is located, it may be
-  necessary to add the folder to PYTHONPATH. Note: The last python
-  mentioned in the ``-DNRN_PYTHON_DYNAMIC=...`` (if the semicolon separated
-  list is non-empty and ``-DNRN_ENABLE_PYTHON_DYNAMIC=ON``)
-  is the one used for ``make test`` and ``ctest -VV``. Otherwise the
-  value specified by ``PYTHON_EXECUTABLE`` is used.
-
-  Example
+  Enable the NEURON test suite (build-tree and install checks).
+
+  When ``ON``:
+
+  * Clones the Catch2 submodule (https://github.com/catchorg/Catch2.git) for
+    C++ unit tests.
+  * Registers the full in-tree CTest suite under the main CMake binary
+    directory (unit tests, HOC/Python integration, RxD, optional MPI and
+    CoreNEURON paths, and so on).
+  * Adds a convenience target ``test-install`` that runs the **portable**
+    foreign test harness against ``CMAKE_INSTALL_PREFIX`` (see
+    :ref:`cmake-nrn-test-install` below).
+
+  You typically need ``pip install pytest`` (and, for RxD plots, packages
+  such as ``matplotlib`` / ``plotly`` / ``anywidget`` as required by
+  individual tests).
+
+  In-tree tests (build directory)
+  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+  After configuring and building, run tests from the **main build**
+  directory. ``make test`` / ``ninja test`` is terse; prefer ``ctest`` for
+  the same verbose style as CI:
+
+  .. code-block:: shell
+
+    mkdir build && cd build
+    cmake .. -G Ninja -DNRN_ENABLE_TESTS=ON -DCMAKE_INSTALL_PREFIX=install ...
+    ninja          # or: cmake --build . -j
+    ctest --output-on-failure -j8
+    ctest -VV -R parallel_tests
+
+  It is helpful to complete a full ``ctest`` (or at least build the test
+  targets) once so that ``nrnivmodl`` has produced any mod-file libraries
+  the scripts expect.
+
+  One can also run individual Python test files with
+  ``python3 -m pytest -s <testfile.py>`` or all tests in a folder with
+  ``python3 -m pytest -s`` (``-s`` sends output to the terminal). If
+  running a test outside the folder where it lives, you may need that
+  folder on ``PYTHONPATH``.
+
+  Note: the last Python listed in ``-DNRN_PYTHON_DYNAMIC=...`` (when
+  non-empty and ``-DNRN_ENABLE_PYTHON_DYNAMIC=ON``) is used for
+  ``make test`` / default ``ctest``. Otherwise the value of
+  ``PYTHON_EXECUTABLE`` / the default discovered Python is used.
+
+  .. _cmake-nrn-test-install:
+
+  Install check (``test-install`` / foreign ctest)
+  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+  Linked C++ unit tests require the build tree. To validate a **prefix
+  install** (or a pip wheel), NEURON also provides a standalone project
+  under ``test/foreign`` that discovers an installed NEURON and runs the
+  portable subset of the suite (no rebuild of ``libnrniv``).
+
+  With ``NRN_ENABLE_TESTS=ON``, the main build defines a target
+  ``test-install``. After installing into ``CMAKE_INSTALL_PREFIX``:
+
+  .. code-block:: shell
+
+    ninja install                 # or: cmake --build . --target install
+    ninja test-install            # or: cmake --build . --target test-install
+
+  That target:
+
+  1. Configures ``test/foreign`` into ``${CMAKE_BINARY_DIR}/build-ctest``
+     (for example ``build/build-ctest``), using the same CMake generator as
+     the main build (for example Ninja).
+  2. Points foreign discovery at the install prefix
+     (``NRN_FOREIGN_ROOT``) and the build’s default Python.
+  3. Builds mechanisms for the portable tests and runs a default
+     ``ctest -L serial`` install check.
+  4. Prints how to re-run ``ctest`` with other filters against that
+     foreign binary directory.
+
+  Afterwards you can use ordinary CTest options against the foreign dir:
+
+  .. code-block:: shell
+
+    ctest --test-dir build-ctest --output-on-failure
+    ctest --test-dir build-ctest -L mpi -j2
+    ctest --test-dir build-ctest -L coreneuron -j2
+    ctest --test-dir build-ctest -R 'pytest::' --rerun-failed
+
+  You can also configure the foreign project yourself (wheels, custom
+  prefixes, or a different binary dir). See ``test/foreign/README.md``
+  and ``test/foreign/INVENTORY.md`` (what runs under foreign mode vs
+  build-only).
+
+  Example (in-tree tests only, classic workflow)
 
   .. code-block:: shell
 
@@ -562,9 +633,6 @@ NRN_ENABLE_TESTS:BOOL=OFF
     make -j
     make test
     ctest -VV -R parallel_tests
-    cd ../test/pynrn
-    python3 -m pytest
-    python3 -m pytest test_currents.py
 
 NRN_ENABLE_COVERAGE:BOOL=OFF
 ----------------------------

docs/dev/gpu-testing.rst

@@ -57,7 +57,10 @@ If you have configured NEURON with CoreNEURON, CoreNEURON GPU support and tests
 
   $ ctest --output-on-failure
 
-in your CMake build directory will execute a large number of tests, many of them including GPU execution.
+in your **main** CMake build directory will execute a large number of tests, many of them including GPU execution.
+(That is the in-tree suite. The separate ``test-install`` / ``test/foreign`` path
+validates an install or wheel and is CPU-oriented; GPU install checks are not
+the focus of that harness yet.)
 You can filter which tests are run by name using the ``-R`` option to CTest, for example:
 
 .. code-block:: console

docs/install/code_coverage.md

@@ -24,7 +24,9 @@ and ``make cover_html``. See [Simplified Workflow](#simplified-workflow) below.
 
 In addition to the COVERAGE_FLAGS use whatever cmake options you desire.
 But you will generally want ```-DNRN_ENABLE_TESTS=ON``` to see what
-effect your new tests have on coverage.
+effect your new tests have on coverage. Use in-tree `ctest` in the main
+build directory for coverage (not the foreign install/wheel
+`test-install` suite, which exercises an installed tree).
 ```
 COVERAGE_FLAGS="--coverage -O0 -fno-inline -g"
 cmake .. -DCMAKE_INSTALL_PREFIX=install -DCMAKE_C_FLAGS="${COVERAGE_FLAGS}" -DCMAKE_CXX_FLAGS="${COVERAGE_FLAGS}" -DNRN_ENABLE_TESTS=ON

docs/install/developer.rst

@@ -1,9 +1,22 @@
 Developer Builds
-============
+================
 
 Developer builds for creating Binary and Python wheel distributions, tests, documentation, code coverage.
 Each aspect generally has extra dependencies and special instructions.
 
+**Tests overview**
+
+* In-tree CTest (build directory): enable with
+  :ref:`-DNRN_ENABLE_TESTS=ON <cmake-nrn-enable-tests-option>`, then
+  ``ctest`` from the main build directory.
+* Install / wheel portable suite: target ``test-install`` (same option), or
+  configure ``test/foreign`` directly — see that option page and
+  ``test/foreign/README.md``.
+* Wheel smoke script: ``packaging/python/test_wheels.sh`` (documented under
+  :doc:`python_wheels`).
+* Coverage workflow: :doc:`code_coverage`.
+* Sanitizers / debugging: :doc:`debug`.
+
 
 .. toctree::
    :maxdepth: 2

docs/install/install_instructions.md

@@ -330,29 +330,47 @@ step method. You can find detailed instructions [here](../coreneuron/index.rst)
 
 #### Run integrated tests
 
-**NEURON** includes also some unit and integration tests. To enable you need to set the `CMake` flag **-DNRN\_ENABLE\_TESTS=ON**.
-The tests lie in the `test` directory and cover various aspects of **NEURON**:
-* **CoreNEURON** integration (if enabled in build step)
-* Functionality and result regression test for [ringtest](https://github.com/neuronsimulator/ringtest) and [testcorenrn](https://github.com/neuronsimulator/testcorenrn)
-* HOC interpreter tests
-* Python interpreter tests
-* Parallel Context tests
+**NEURON** includes unit and integration tests. Enable them with the CMake
+flag **-DNRN\_ENABLE\_TESTS=ON**. Sources live under `test/` and cover
+(among other areas):
+* **CoreNEURON** integration (if enabled at configure time)
+* Functionality and result regression tests for [ringtest](https://github.com/neuronsimulator/ringtest) and [testcorenrn](https://github.com/neuronsimulator/testcorenrn)
+* HOC and Python interpreter tests
+* Parallel Context / MPI tests
 * Rx3d tests
-* Unit tests
-* GapJunction tests
+* C++ unit tests (Catch2)
+* Gap junction tests
+
+**In-tree tests** (against the build directory; includes linked unit tests):
 
-To run the tests it's needed to:
   ```bash
   cd nrn/build
   cmake .. \
+   -G Ninja \
+   -DNRN_ENABLE_TESTS=ON \
    -DNRN_ENABLE_INTERVIEWS=OFF \
    -DNRN_ENABLE_MPI=OFF \
    -DNRN_ENABLE_RX3D=OFF \
    -DCMAKE_INSTALL_PREFIX=/path/to/install/directory
   cmake --build . --parallel 8
-  ctest # use --parallel for speed, -R to run specific tests
+  ctest --output-on-failure -j8   # -R to select tests by name
+  ```
+
+**Install check** (portable suite against the install prefix; no rebuild of
+`libnrniv`). After the same configure with `-DNRN_ENABLE_TESTS=ON`:
+
+  ```bash
+  cmake --build . --target install
+  cmake --build . --target test-install
+  # creates build/build-ctest and runs a default serial foreign ctest
+  ctest --test-dir build-ctest -L mpi --output-on-failure   # optional filters
   ```
 
+Details, labels (`serial`, `mpi`, `coreneuron`), and wheel testing are
+documented under the CMake option `NRN_ENABLE_TESTS` and in
+`test/foreign/README.md`. For a short smoke test of a built wheel, see
+also `packaging/python/test_wheels.sh` in [Building Python Wheels](python_wheels.md).
+
 ### FAQs
 
 * **I am getting link errors "undefined reference to 'tgoto, tgetent, tputs'".**

docs/install/python_wheels.md

@@ -148,7 +148,13 @@ Change the pretend version to whatever is relevant for your case.
 
 ## Testing the wheels
 
-To test the generated wheels, you can do:
+There are two complementary approaches: a **smoke script** that ships with
+the packaging tree, and the **foreign CTest harness** that reuses a large
+portable subset of the developer suite against an installed wheel.
+
+### Smoke tests (`test_wheels.sh`)
+
+Quick health check after building a wheel (or against TestPyPI):
 
 ```
 # first arg is a python exe and second arg is the corresponding wheel
@@ -158,11 +164,55 @@ bash packaging/python/test_wheels.sh python3.9 wheelhouse/NEURON-7.8.0.236-cp39-
 bash packaging/python/test_wheels.sh python3.9 "-i https://test.pypi.org/simple/NEURON==7.8.11.2"
 ```
 
+This covers import/`neuron.test()`, basic `nrnivmodl`, and a few MPI /
+CoreNEURON paths when available. It is intentionally smaller than a full
+developer `ctest` run.
+
+### Foreign CTest against a wheel (portable suite)
+
+For broader coverage without rebuilding NEURON, configure the standalone
+project under `test/foreign` against a venv that has the wheel installed:
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install -U pip pytest
+# local wheel, or e.g. neuron-nightly from PyPI:
+pip install path/to/NEURON-*.whl
+# pip install neuron-nightly
+
+# From the NEURON source tree (same revision as the wheel when possible):
+cmake -S test/foreign -B build-ctest \
+  -DNRN_FOREIGN_PYTHON="$(which python)" \
+  -DNRN_FOREIGN_ALLOW_SKEW=ON   # only if source tip ≠ wheel revision
+
+cmake --build build-ctest --target test-install -j
+# default: build mechanisms + ctest -L serial
+
+# Full ctest control against the foreign binary dir:
+ctest --test-dir build-ctest -L mpi --output-on-failure -j2
+ctest --test-dir build-ctest -L coreneuron --output-on-failure -j2
+```
+
+Notes:
+
+* Version policy defaults to a hard match between the wheel’s git identity
+  and this source tree; use `-DNRN_FOREIGN_ALLOW_SKEW=ON` for exploratory
+  runs (for example `neuron-nightly` vs a feature branch).
+* MPI tests register only if the wheel was built with MPI **and** `mpiexec`
+  is on `PATH` at foreign configure time.
+* See `test/foreign/README.md` and `test/foreign/INVENTORY.md` for
+  labels, dependencies (e.g. RxD plot packages), and what remains
+  build-only (Catch2 unit tests, NMODL unit binaries, …).
+
+The same foreign harness is used after a **prefix install** via the main
+build target `test-install` when `NRN_ENABLE_TESTS=ON` (see the CMake
+option documentation for `NRN_ENABLE_TESTS`).
+
 ### MacOS considerations
 
 On MacOS, launching `nrniv -python` or `special -python` can fail to load `neuron` module due to security restrictions.
-For this specific purpose, please `export SKIP_EMBEDED_PYTHON_TEST=true` before launching the tests.
-
+For this specific purpose, please `export SKIP_EMBEDED_PYTHON_TEST=true` before launching the tests
+(for `test_wheels.sh`).
 ## Publishing the wheels on Pypi via Azure
 
 ### Variables that drive PyPI upload