[bug #62478] add more documentation of test suite usage

[G. Branden Robinson]

Update of bug #62478 (project groff):

                  Status:             In Progress => Need Info              

    _______________________________________________________

Follow-up Comment #5:


[comment #4 comment #4:]
> [comment #2 comment #2:]
> > It is not even intended as a test suite for an existing groff
> > installation.  Its purpose is to check the behavior of the groff
> > system _that has just been compiled on a host_ for correctness.
> 
> This scope is implied by the fact that the test suite is typically run via
"make," which is part of the build system, but is it explicitly documented? 
The text in INSTALL.extra introducing the test suite says that it can be used
for this purpose without stating that is its _sole_ intended use.

Well, here's what document says at present.


Once groff is built, you can check it for correct operation without
having to install it.  groff comes with a test suite; use 'make check'
to run it.

[...]

If a test fails, gather its log file from the build directory.  For
instance, the test "tmac/tests/localization-works.sh" (in the source
directory) will have a log file called
"tmac/tests/localization-works.sh.log" in the build directory.

To re-run a test, change to the top of the build directory (if
necessary) and run the test by name from the shell prompt.

For example, to rerun the test mentioned above from a "build" directory
I created as a subdirectory in the source tree, I would do this.

  (cd build && ../tmac/tests/localization-works.sh)

I can view the test log as follows.

  cat build/tmac/tests/localization-works.sh.log


It's common--though not as common as it should be--for software projects to be
distributed with an integrated test suite.  In my opinion this is pretty
elementary knowledge in software engineering.  It's beyond the scope of this
document to spin people up on such fundamentals; if they lack this background,
they either shouldn't be building groff from source code or should be prepared
to do some learning from additional sources.

The issue the submitter originally raised was not, as I read it, a lack of
knowledge of such fundamentals, but a desire to see either a more generalized
*roff testing tool, or a decoupling of groff's individual test scripts from
the (Auto)make-based test harness.  Both of those ideas are non-starters for
me personally.

What would you suggest?


    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?62478>

_______________________________________________
  Message sent via Savannah
  https://savannah.gnu.org/