tests - introduction to the FreeBSD Test Suite

The FreeBSD Test Suite consists of many programs for testing the FreeBSD
operating system.  These programs can be found under /usr/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

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

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.

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

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

kyua(1), build(7)

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.

Julio Merino <jmmv@FreeBSD.org>