Add completion testsuite covering bash, zsh, fish and tcsh

.codespellrc

@@ -1,10 +1,12 @@
 [codespell]
-# ignore short names used in tests: ans, oT, ue, fo, haa, varius
+# ignore short names used in tests: ans, oT, ue, fo, haa, varius, ure
 # ignore words joined to \t or \n character: \tThe, \tbe, \nIn
 # ignore variable names used in code: desig, matchin, compre, invers, compileTime, seh
 # ignore words added to spell check dictionary: lod, nd
 # ignore command names used in code: uncomplete
-ignore-words-list = ans,ot,ue,fo,haa,varius,tthe,tbe,nin,desig,matchin,compre,invers,compiletime,seh,lod,nd,uncomplete
+# ignore hyphenated wording already used throughout Tab completion option
+# descriptions: By-pass
+ignore-words-list = ans,ot,ue,fo,haa,varius,ure,tthe,tbe,nin,desig,matchin,compre,invers,compiletime,seh,lod,nd,uncomplete,by-pass
 # skip git repository internal content
 # skip generated content: ChangeLog.gz, doc/build, modulecmd*.tcl, modules.sum
 #   modules.log, lib/config.sub, lib/config.guess, lib/config.status, lib/configure,

.github/workflows/completion_tests.yaml

@@ -0,0 +1,39 @@
+name: completion-tests
+
+on:
+  push:
+    branches-ignore:
+      - c-main
+      - c-3.2
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  completion-all:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - name: Install system packages
+        run: |
+          sudo apt-get -y update
+          sudo apt-get install -y expect-dev dejagnu python3-sphinx gzip bash zsh fish tcsh tcl8.6 python3
+          # libtclenvmodules build requirements
+          sudo apt-get install -y gcc autoconf tcl8.6-dev
+      - name: Build Modules
+        run: |
+          ./configure
+          make
+      - name: Test shell Tab completion
+        run: |
+          script/mt comp
+      - uses: actions/upload-artifact@v7
+        if: failure()
+        with:
+          name: testsuite-logs-${{ github.job }}
+          path: |
+            completion.log
+          retention-days: 5

.gitignore

@@ -11,6 +11,8 @@
 /install.sum
 /lint.log
 /lint.sum
+/completion.log
+/completion.sum
 /icdiff
 /.noicdiff
 /miniconda3
@@ -54,6 +56,8 @@
 /testsuite/example/initrc-1
 /testsuite/example/initrc
 /testsuite/.config
+/testsuite/completion-use-fixture
+/testsuite/completion-home
 /doc/build
 /doc/source/version.py
 /doc/demo/*/*.svg

.hunspell.en.dic

@@ -18,6 +18,7 @@ CET
 CFLAGS
 CLICOLOR
 CMake
+COMPREPLY
 CONFIGLIST
 ChangeLog
 ChemAppA
@@ -258,9 +259,11 @@ autoreconf
 autotools
 availabilities
 avx
+ba
 backticks
 badcommand
 baf
+bar1
 barbin
 basename
 basenames
@@ -297,6 +300,7 @@ chmod
 cleanupAndExit
 cmake
 cmd
+cmdline
 cmdModule
 cmdModuleAliases
 cmdModuleAvail
@@ -314,6 +318,7 @@ cmdModulePath
 cmdModulePaths
 cmdModuleReset
 cmdModuleRestore
+cmdModuleSavelist
 cmdModuleSearch
 cmdModuleStash
 cmdModuleStashclear
@@ -329,11 +334,14 @@ cmdstring
 codecov
 codespell
 collectModuleTag
+comgen
 commandexp
 commandname
 compA
 compB
 compat
+compdef
+completionhome
 compilerTag
 compopt
 config
@@ -357,6 +365,7 @@ dbg
 de
 defaultval
 defs
+dejagnu
 del
 delaruelle
 delim
@@ -431,7 +440,9 @@ findModulesInCacheFile
 findable
 fishcompletiondir
 flavour
+flatlcompat
 flavours
+fo
 fooA
 fooB
 foobin
@@ -441,6 +452,7 @@ formatModuleCacheContent
 formatter
 foss
 fpath
+freeform
 frontend
 fullname
 func
@@ -518,6 +530,7 @@ isdefaultvalue
 ismodlo
 journalctl
 json
+keypress
 kL
 ksh
 lappendConf
@@ -649,6 +662,7 @@ nonpersist
 noop
 nop
 noparse
+nospace
 notavail
 nothreads
 notuasked
@@ -696,6 +710,7 @@ procedure's
 procs
 ps
 pthreads
+pty
 pushenv
 py
 pwsh
@@ -708,6 +723,7 @@ rcp
 reStructuredText
 readCollectionContent
 readModuleContent
+readline
 readlink
 repo
 reportError
@@ -844,6 +860,7 @@ tclxConfig
 tcsh
 tcshrc
 ter
+testcompletion
 testdir
 testfile
 testfiles
@@ -910,6 +927,7 @@ version's
 versionadded
 versionchanged
 versioncmp
+versionless
 vimdatadir
 vimfiles
 virt
@@ -928,6 +946,7 @@ xrdb
 xtrace
 zA
 zipball
+zle
 zlogin
 zsh
 zshcompletiondir

Makefile

@@ -4,7 +4,7 @@
 	install-testmodspath-empty install-testmodspath-wild \
 	install-testmoguicmd uninstall-testconfig uninstall dist dist-tar \
 	dist-gzip dist-bzip2 dist-win srpm rpm clean distclean test-deps test \
-	testinstall testlint
+	testinstall testlint testcompletion
 
 # commands to install files
 INSTALL = install
@@ -1073,6 +1073,13 @@ testlint: initdir modulecmd.tcl $(NAGELFAR) script/add.modules script/modulecmd
 	TESTSUITEDIR=`cd testsuite;pwd -P`; export TESTSUITEDIR; \
 	runtest --srcdir $$TESTSUITEDIR --objdir $$OBJDIR $(RUNTESTFLAGS) --tool lint $(RUNTESTFILES)
 
+testcompletion: initdir $(MODULECMD)
+	TCLSH=$(TCLSH); export TCLSH; \
+	MODULECMD=$(MODULECMD); export MODULECMD; \
+	OBJDIR=`pwd -P`; export OBJDIR; \
+	TESTSUITEDIR=`cd testsuite;pwd -P`; export TESTSUITEDIR; \
+	runtest --srcdir $$TESTSUITEDIR --objdir $$OBJDIR $(RUNTESTFLAGS) --tool completion $(RUNTESTFILES)
+
 
 # install enhanced diff tool (to review test results)
 icdiff:

NEWS.rst

@@ -190,6 +190,23 @@ Modules 5.7.0 (not yet released)
 * Doc: add :ref:`add-new-hook-event` guide describing how to contribute a
   new hook event.
 * Doc: add :ref:`sync-remote-appdir` cookbook recipe.
+* Testsuite: add *completion* testsuite to validate shell Tab completion of
+  this project. This testsuite can be invoked with ``make testcompletion`` or
+  ``script/mt comp``. It drives a real bash, zsh, fish or tcsh session
+  through `Expect <http://expect.sourceforge.net/>`_ to press the Tab key
+  against the built shell completion script and check the resulting
+  candidate list.
+* Init: fix numerous inconsistencies between ``module help``'s usage message
+  and the option flags and positional arguments each sub-command actually
+  accepts, and between that usage message and what bash, fish, tcsh and zsh
+  Tab completion offer for each sub-command. Guarded against regressing with
+  a new ground-truth check in the *completion* testsuite that compares
+  ``module``/``ml`` Tab completion against the sub-commands, switches,
+  options and argument kinds parsed straight out of ``module help``.
+* Init: no longer offer the legacy :subcmd:`initadd`, :subcmd:`initclear`,
+  :subcmd:`initlist`, :subcmd:`initprepend` and :subcmd:`initrm`
+  sub-commands as Tab completion candidates (bash, fish, tcsh, zsh), since
+  ``module help`` does not document them.
 
 
 .. _5.6 release notes:

doc/source/devel/ci.rst

@@ -28,6 +28,8 @@ Overview
     pull request.
 ``lint_tests.yaml``
     Static analysis (Nagelfar, ShellCheck). Runs on push, pull request.
+``completion_tests.yaml``
+    Interactive shell Tab-completion tests. Runs on push, pull request.
 ``differential_shellcheck.yml``
     ShellCheck diff annotations on the changed lines only. Runs on pull
     request (to ``main``).
@@ -129,6 +131,18 @@ sh/bash/ksh scripts) via ``script/mt lint``, i.e. the same static analysis
 described as the ``lint`` tool in :doc:`testsuite`. On failure it uploads
 :file:`lint.log` as a build artifact.
 
+Completion (:file:`completion_tests.yaml`)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Runs the ``completion`` DejaGnu tool (real, Expect-driven Tab-key presses
+against the built :file:`init/bash_completion` script) via
+``script/mt comp``, i.e. the same interactive shell Tab-completion testing
+described as the ``completion`` tool in :doc:`testsuite`. Only needs the
+baseline packages (``bash``, ``expect-dev``, ``dejagnu``) rather than the
+full multi-shell set installed by :file:`linux_tests.yaml`, since the
+``completion.00-init`` layout currently covers bash only. On failure it
+uploads :file:`completion.log` as a build artifact.
+
 Differential ShellCheck (:file:`differential_shellcheck.yml`)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~