= Testing Bash Completion with Expect and DejaGNU

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,
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.

== Setup
First, install DejaGNU:

[source,bash]
----
sudo apt-get install dejagnu
----

That will install the following packages:
dejagnu expect libtcl8.6 tcl-expect tcl8.6. (I verified that tcl 8.5 works also.)

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 Completion Tests

=== Running the Tests Manually
To manually run the tests, `cd` into the `dejagnu.tests` directory and run the `./runCompletions` script:

[source,bash]
----
cd src/test/dejagnu.tests
./runCompletion
----

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:

[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`.