164e33c5cSCy Schubertsrc/tests: The FreeBSD test suite 264e33c5cSCy Schubert================================= 364e33c5cSCy Schubert 464e33c5cSCy SchubertUsage of the FreeBSD test suite: 564e33c5cSCy Schubert(1) Run the tests: 664e33c5cSCy Schubert kyua test -k /usr/tests/Kyuafile 764e33c5cSCy Schubert(2) See the test results: 864e33c5cSCy Schubert kyua report 964e33c5cSCy Schubert 1064e33c5cSCy SchubertFor further information on using the test suite, read tests(7): 1164e33c5cSCy Schubert man tests 1264e33c5cSCy Schubert 1364e33c5cSCy SchubertDescription of FreeBSD test suite 1464e33c5cSCy Schubert================================= 1564e33c5cSCy SchubertThe build of the test suite is organized in the following manner: 1664e33c5cSCy Schubert 1764e33c5cSCy Schubert* The build of all test artifacts is protected by the MK_TESTS knob. 1864e33c5cSCy Schubert The user can disable these with the WITHOUT_TESTS setting in 1964e33c5cSCy Schubert src.conf(5). 2064e33c5cSCy Schubert 2164e33c5cSCy Schubert* The goal for /usr/tests/ (the installed test programs) is to follow 2264e33c5cSCy Schubert the same hierarchy as /usr/src/ wherever possible, which in turn drives 2364e33c5cSCy Schubert several of the design decisions described below. This simplifies the 2464e33c5cSCy Schubert discoverability of tests. We want a mapping such as: 2564e33c5cSCy Schubert 2664e33c5cSCy Schubert /usr/src/bin/cp/ -> /usr/tests/bin/cp/ 2764e33c5cSCy Schubert /usr/src/lib/libc/ -> /usr/tests/lib/libc/ 2864e33c5cSCy Schubert /usr/src/usr.bin/cut/ -> /usr/tests/usr.bin/cut/ 2964e33c5cSCy Schubert ... and many more ... 3064e33c5cSCy Schubert 3164e33c5cSCy Schubert* Test programs for specific utilities and libraries are located next 3264e33c5cSCy Schubert to the source code of such programs. For example, the tests for the 3364e33c5cSCy Schubert src/lib/libcrypt/ library live in src/lib/libcrypt/tests/. The tests/ 3464e33c5cSCy Schubert subdirectory is optional and should, in general, be avoided. 3564e33c5cSCy Schubert 3664e33c5cSCy Schubert* The src/tests/ hierarchy (this directory) provides generic test 3764e33c5cSCy Schubert infrastructure and glue code to join all test programs together into 3864e33c5cSCy Schubert a single test suite definition. 3964e33c5cSCy Schubert 4064e33c5cSCy Schubert* The src/tests/ hierarchy also includes cross-functional test programs: 4164e33c5cSCy Schubert i.e. test programs that cover more than a single utility or library 4264e33c5cSCy Schubert and thus don't fit anywhere else in the tree. Consider this to follow 4364e33c5cSCy Schubert the same rationale as src/share/man/: this directory contains generic 4464e33c5cSCy Schubert manual pages while the manual pages that are specific to individual 4564e33c5cSCy Schubert tools or libraries live next to the source code. 4664e33c5cSCy Schubert 4764e33c5cSCy SchubertIn order to keep the src/tests/ hierarchy decoupled from the actual test 4864e33c5cSCy Schubertprograms being installed --which is a worthy goal because it simplifies 4964e33c5cSCy Schubertthe addition of new test programs and simplifies the maintenance of the 5064e33c5cSCy Schuberttree-- the top-level Kyuafile does not know which subdirectories may 5164e33c5cSCy Schubertexist upfront. Instead, such Kyuafile automatically detects, at 5264e33c5cSCy Schubertrun-time, which */Kyuafile files exist and uses those directly. 5364e33c5cSCy Schubert 5464e33c5cSCy SchubertSimilarly, every directory in src/ that wants to install a Kyuafile to 5564e33c5cSCy Schubertjust recurse into other subdirectories reuses this Kyuafile with 5664e33c5cSCy Schubertauto-discovery features. As an example, take a look at src/lib/tests/ 5764e33c5cSCy Schubertwhose sole purpose is to install a Kyuafile into /usr/tests/lib/. 5864e33c5cSCy SchubertThe goal in this specific case is for /usr/tests/lib/ to be generated 5964e33c5cSCy Schubertentirely from src/lib/. 6064e33c5cSCy Schubert 6164e33c5cSCy Schubert-- 62