Make tests(7) more concise.

[• rodrigc]

Summary

Update the text in tests(7) to make it more concise,
and easier to understand how to run the FreeBSD test suite.

[• rodrigc]

TESTS(7) FreeBSD Miscellaneous Information Manual TESTS(7)

NAME

tests - introduction to the FreeBSD Test Suite

DESCRIPTION

The FreeBSD Test Suite consists of many programs for testing the FreeBSD
operating system.  These programs can be found under /usr/tests.

RUNNING THE TESTS

The kyua(1) program must first be installed using pkg(7):

      $ pkg install kyua

To list all the tests under /usr/tests:

      $ kyua list -k /usr/tests/Kyuafile

To run all the tests under /usr/tests:

      $ kyua test -k /usr/tests/Kyuafile

To run tests only for cp(1) and cut(1):

      $ kyua test -k /usr/tests/Kyuafile bin/cp usr.bin/cut

REPORTING TEST RESULTS

After running the tests, a report can be generated that shows the test
output and lists the passed and failed tests.

To generate a plain-text report:

      $ kyua report

To generate an HTML report:

      $ kyua report-html --output ~/public_html/tests

For further details on the command-line interface of Kyua, please refer
to its manual page kyua(1).

CONFIGURING TESTS

Some test cases in the FreeBSD Test Suite require manual configuration by
the administrator before they can be run.  Unless certain properties are
defined, the tests that require them will be skipped.

Test suites are configured by defining their configuration variables in
/usr/local/etc/kyua/kyua.conf.  The format of this file is detailed in
kyua.conf(5).

The following configuration variables are available in the FreeBSD Test
Suite:

allow_devfs_side_effects   If defined, enables tests that may destroy and
                           recreate semipermanent device nodes, like disk
                           devices.  Without this variable, tests may
                           still create and destroy device nodes that are
                           normally transient, like /dev/tap* and
                           /dev/pts*, as long as they clean them up
                           afterwards.  However, tests that require this
                           variable have a relaxed cleanup requirement;
                           they must recreate any devices that they
                           destroyed, but not necessarily with the same
                           devnames.

allow_sysctl_side_effects  Enables tests that change globally significant
                           sysctl(8) variables.  The tests will undo any
                           changes in their cleanup phases.

disks                      Must be set to a space delimited list of disk
                           device nodes.  Tests that need destructive
                           access to disks must use these devices.  Tests
                           are not required to preserve any data present
                           on these disks.

fibs                       Must be set to a space delimited list of FIBs
                           (routing tables).  Tests that need to modify a
                           routing table may use any of these.  Tests
                           will cleanup any new routes that they create.

REPORTING TEST FAILURES TO DEVELOPERS

If there is any failure during the execution of the test suite, please
consider reporting it to the FreeBSD developers so that the failure can
be analyzed and fixed.  To do so, either send a message to the
appropriate mailing list or file a problem report.  For more details
please refer to:
      o   FreeBSD Mailing Lists: http://lists.freebsd.org/
      o   Problem Reporting: http://www.freebsd.org/support.html

FILES

/usr/local/etc/kyua/kyua.conf   System-wide configuration file for
                                kyua(1).
~/.kyua/kyua.conf               User-specific configuration file for
                                kyua(1); overrides the system file.
~/.kyua/store.db                Default result database used by Kyua.
/usr/tests/                     Location of the FreeBSD Test Suite.
/usr/tests/Kyuafile             Top-level test suite definition file.

SEE ALSO

kyua(1), build(7)

HISTORY

The FreeBSD Test Suite first appeared in FreeBSD 10.1.

The tests manual page first appeared in NetBSD 6.0 and was later ported
to FreeBSD 10.1.

AUTHORS

Julio Merino <[e-mail]>

FreeBSD 11.0-CURRENT November 19, 2015 FreeBSD 11.0-CURRENT

[bjk]

share/man/man7/tests.7

48

ports are still a supported way of installing things.
It's probably best to just way that kyua must be installed and remain silent on how. This is a reference manual, not necessarily a how-to guide.

110

I don't see a macro specific for device names, so please use .Pa for these two.

[jmmv]

share/man/man7/tests.7

36

Why is the explanation of the utility of the test suite gone?

70

Why is the explanation of WITH_TESTS gone?

72

nit: The list of top-level sections that are allowed in a manpage is well-defined by mandoc. This is the reason why all these sections were actually sub-sections marked with .Ss, and I think this markup change should be reverted.

78

Why is this whole section gone?

[wblock]

share/man/man7/tests.7

39

s/many/a collection of/

48

Worth saying that "The devel/kyua port or package must be installed." though, so the reader knows where to find it.

53

"in" rather than "under" makes more sense to me.

59

s/under/in/ (as above)

107

Not yours, but... passive->active:
s/enables/enable/

and "could destroy" reads better than "may destroy".

109

s/may/might/

("may" implies permission)

116

s/Enables/Enable/ (as above)

121

I would say "space-delimited".

125

"space-delimited"

126

Does "may" here mean "are allowed to" or "might"?

127

s/cleanup/clean up/

("cleanup" is a thing, "clean up" is a verb)