[#906] DOC updated src/test/dejagnu.tests/README.adoc

src/test/dejagnu.tests/README.adoc

@@ -1,11 +1,11 @@
-= Testing Completion with Expect and DejaGNU
+= Testing Bash Completion with Expect and DejaGNU
 
-The files in this directory allow testing bash TAB completion.
+The files in this directory allow testing the Bash TAB completion scripts generated by picocli.
 The tests use the https://www.gnu.org/software/dejagnu/[DejaGNU] framework,
 which is written in https://www.nist.gov/services-resources/software/expect[Expect].
 Expect in turn uses http://tcl.sourceforge.net/[Tcl] -- Tool command language.
 
-The tests work by starting a bash session with a predictable configuration,
+The tests work by starting a Bash session with a predictable configuration,
 then sourcing some of the completion scripts in `src/test/resources`,
 and sending strings to the shell that trigger the shell to print completion candidates.
 The testing framework then asserts that these completion candidates are the expected ones.
@@ -19,29 +19,44 @@ sudo apt-get install dejagnu
 ----
 
 That will install the following packages:
-dejagnu expect libtcl8.6 tcl-expect tcl8.6.
+dejagnu expect libtcl8.6 tcl-expect tcl8.6. (I verified that tcl 8.5 works also.)
 
-To get the `cmdline` and `textutil` packages used in `dejagnu.tests/lib/library.exp`, get `tcllib`:
+Next, install `tcllib` (to get the `cmdline` and `textutil` packages used in `dejagnu.tests/lib/library.exp`):
 
 [source,bash]
 ----
 sudo apt-get install tcllib
 ----
 
-== Running the Tests
+== Running the Completion Tests
 
-I have not yet investigated how to automate this.
-For now, just `cd` into the `dejagnu.tests` directory and run the `./runCompletions` script:
+=== Running the Tests Manually
+To manually run the tests, `cd` into the `dejagnu.tests` directory and run the `./runCompletions` script:
 
 [source,bash]
 ----
-cd src/tests/dejagnu.tests
-./runCompletion -v # -v gives verbose output into the log directory
+cd src/test/dejagnu.tests
+./runCompletion
 ----
 
-== TODO
+Use the `-v` option (once or multiple times) to increase verbosity of the log output.
+To control where the `completion.log` and `completion.sum` log files are output,
+use the `--log-dir` option:
 
-* Ensure these tests are run automatically as part of the Gradle build
-* Log files should be created in the `build` directory, not in `src/tests/dejagnu.tests/log`
-* Figure out how the tests can be started from any directory
+[source,bash]
+----
+# create completion.log and completion.sum log files in the build/dejagnu-logs directory
+cd src/test/dejagnu.tests
+./runCompletion -v --log-dir ../../../build/dejagnu-logs
+----
+
+=== Running the Tests Automatically as Part of the Build
+
+The `java/picocli/AutoCompleteDejaGnuTest.java` JUnit test is responsible for
+kicking off the DejaGnu tests as part of the test suite that is run during the build.
+
+This JUnit test will be ignored if it detects that the `dejagnu` package is not installed.
+
+The test will succeed if all DejeGnu completion tests complete within 15 seconds
+and the last line of output contains `# of expected passes`.