1*64e33c5cSCy Schubertsrc/tests: The FreeBSD test suite 2*64e33c5cSCy Schubert================================= 3*64e33c5cSCy Schubert 4*64e33c5cSCy SchubertUsage of the FreeBSD test suite: 5*64e33c5cSCy Schubert(1) Run the tests: 6*64e33c5cSCy Schubert kyua test -k /usr/tests/Kyuafile 7*64e33c5cSCy Schubert(2) See the test results: 8*64e33c5cSCy Schubert kyua report 9*64e33c5cSCy Schubert 10*64e33c5cSCy SchubertFor further information on using the test suite, read tests(7): 11*64e33c5cSCy Schubert man tests 12*64e33c5cSCy Schubert 13*64e33c5cSCy SchubertDescription of FreeBSD test suite 14*64e33c5cSCy Schubert================================= 15*64e33c5cSCy SchubertThe build of the test suite is organized in the following manner: 16*64e33c5cSCy Schubert 17*64e33c5cSCy Schubert* The build of all test artifacts is protected by the MK_TESTS knob. 18*64e33c5cSCy Schubert The user can disable these with the WITHOUT_TESTS setting in 19*64e33c5cSCy Schubert src.conf(5). 20*64e33c5cSCy Schubert 21*64e33c5cSCy Schubert* The goal for /usr/tests/ (the installed test programs) is to follow 22*64e33c5cSCy Schubert the same hierarchy as /usr/src/ wherever possible, which in turn drives 23*64e33c5cSCy Schubert several of the design decisions described below. This simplifies the 24*64e33c5cSCy Schubert discoverability of tests. We want a mapping such as: 25*64e33c5cSCy Schubert 26*64e33c5cSCy Schubert /usr/src/bin/cp/ -> /usr/tests/bin/cp/ 27*64e33c5cSCy Schubert /usr/src/lib/libc/ -> /usr/tests/lib/libc/ 28*64e33c5cSCy Schubert /usr/src/usr.bin/cut/ -> /usr/tests/usr.bin/cut/ 29*64e33c5cSCy Schubert ... and many more ... 30*64e33c5cSCy Schubert 31*64e33c5cSCy Schubert* Test programs for specific utilities and libraries are located next 32*64e33c5cSCy Schubert to the source code of such programs. For example, the tests for the 33*64e33c5cSCy Schubert src/lib/libcrypt/ library live in src/lib/libcrypt/tests/. The tests/ 34*64e33c5cSCy Schubert subdirectory is optional and should, in general, be avoided. 35*64e33c5cSCy Schubert 36*64e33c5cSCy Schubert* The src/tests/ hierarchy (this directory) provides generic test 37*64e33c5cSCy Schubert infrastructure and glue code to join all test programs together into 38*64e33c5cSCy Schubert a single test suite definition. 39*64e33c5cSCy Schubert 40*64e33c5cSCy Schubert* The src/tests/ hierarchy also includes cross-functional test programs: 41*64e33c5cSCy Schubert i.e. test programs that cover more than a single utility or library 42*64e33c5cSCy Schubert and thus don't fit anywhere else in the tree. Consider this to follow 43*64e33c5cSCy Schubert the same rationale as src/share/man/: this directory contains generic 44*64e33c5cSCy Schubert manual pages while the manual pages that are specific to individual 45*64e33c5cSCy Schubert tools or libraries live next to the source code. 46*64e33c5cSCy Schubert 47*64e33c5cSCy SchubertIn order to keep the src/tests/ hierarchy decoupled from the actual test 48*64e33c5cSCy Schubertprograms being installed --which is a worthy goal because it simplifies 49*64e33c5cSCy Schubertthe addition of new test programs and simplifies the maintenance of the 50*64e33c5cSCy Schuberttree-- the top-level Kyuafile does not know which subdirectories may 51*64e33c5cSCy Schubertexist upfront. Instead, such Kyuafile automatically detects, at 52*64e33c5cSCy Schubertrun-time, which */Kyuafile files exist and uses those directly. 53*64e33c5cSCy Schubert 54*64e33c5cSCy SchubertSimilarly, every directory in src/ that wants to install a Kyuafile to 55*64e33c5cSCy Schubertjust recurse into other subdirectories reuses this Kyuafile with 56*64e33c5cSCy Schubertauto-discovery features. As an example, take a look at src/lib/tests/ 57*64e33c5cSCy Schubertwhose sole purpose is to install a Kyuafile into /usr/tests/lib/. 58*64e33c5cSCy SchubertThe goal in this specific case is for /usr/tests/lib/ to be generated 59*64e33c5cSCy Schubertentirely from src/lib/. 60*64e33c5cSCy Schubert 61*64e33c5cSCy Schubert-- 62