WARNING
-------
To be able to run these tests, you first need to get two of my other small
utilities available here: https://github.com/p-gen.

Make sure you have installed the latest git commit of these two utilities
before going any further.

- The first named  **ptylie** is a kind of script without the replay capacity
  but with a mechanism to inject keystrokes in the keyboard queue of the
  slave pty running your code.

- The second named **hlvt** is a minimalist embryonic headless terminal
  emulation able to process a typescript like the one generated by
  **ptylie** or scripts and render it in a virtual screen.
  The resulting output is the content of the screen after all the
  typescript content and DEC escape sequences have been interpreted.

  With newer Linux kernels (>= 6.2), you may need to run (as root)
  ``sysctl dev.tty.legacy_tiocsti=1`` for this to work.

Make sure that the **bash** shell is installed.

For accurate results, please use a terminal using DEC escape sequences
for attribute settings (colors, bold...), I highly recommend **xterm**
in this situation.

As most tests are using colors and UTF-8 the terminal and locale in use
must also support them.


Files
-----
The files present in this directory are:

- ``t????.in`` contains the words to feed smenu.
- ``t????.good`` is the screen content of the test after a successful run.
- ``t????.tst`` contains the keystrokes to pass to smenu.
- ``*.bl`` contains the blacklisted tests to ignore for an given OS
  (one per line).
- ``test.sh`` runs a single test.
- ``tests.sh`` runs selected or all tests.

Usage
-----
- Copy the ``tests`` directory to a place where you have write access
  if it is not already the case.
- Go to the ``tests`` directory.
- If the packaging is based on the result of ``make dist``, then you
  may have to get the tests from a gziped cpio archive. In that case:

  - Decompress the **tests.cpio.gz** archive (``gzip -dv tests.cpio.gz``).
  - Extract the tests from the **tests.cpio** archive in this directory
    (``cpio -idv < tests.cpio``).
  - Make tests.sh and test.sh executable (``chmod u+x tests.sh test.sh``)

- Make sure that your terminal has at least a size of 80x84.
- Make sure that you have previously built **smenu** with ``build.sh``.
- Make sure that **smenu** is (re-)installed as the tests will use the
  PATH to find it.
- if **ptylie** and/or **hlvt** are not in the ``PATH``, then put their
  base directories in the variables ``PTYLIE_PATH`` and/or ``HLVT_PATH``
  and **export** them.
- If you want to run all the provided tests, then simply run
  ``./tests.sh`` else add the subdirectory containing the ``txxxx``
  files you want to test as argument. Example: ``./tests.sh spaces``.
- An individual test can be performed by going into the ``tests``
  directory and by executing the command ``../test.sh`` with the test
  as argument without extension.
  Example ``../test.sh t0001``.
  Note that the script name is ``test.sh`` in this case and **not**
  ``tests.sh``.

The terminal should animate as if you were typing all that stuff yourself.
You can do whatever you want with this terminal during the test except
close it or reduce its size to less than 80x24.

The resulting files (``.log``) should not contain any occurrence of the
*BAD* word.
The ``tests.sh`` script will show these occurrences, if any, anyway.

Note
----
Before reporting a bug due to a failing test, please re-execute is
again at least 3 times with ``test.sh`` as you may have found a (timing)
bug in **ptylie**/**hlvt** and not in **smenu**.
