Page MenuHomeFreeBSD
Files F153465499

D56475.diff
No OneTemporary
Actions

D56475.diff
View Options

diff --git a/share/man/man7/tests.7 b/share/man/man7/tests.7
--- a/share/man/man7/tests.7
+++ b/share/man/man7/tests.7
@@ -25,7 +25,7 @@
.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
-.Dd April 1, 2025
+.Dd April 17, 2026
.Dt TESTS 7
.Os
.Sh NAME
@@ -97,37 +97,107 @@
introduce unexpected failures.
.El
.Ss Running the tests
-Use the following command to run the whole test suite:
+By default, Kyua looks for tests in the current directory.
+To run the whole test suite, either use the
+.Fl k
+option to specify the top-level
+.Pa Kyuafile :
.Bd -literal -offset indent
$ kyua test -k /usr/tests/Kyuafile
.Ed
.Pp
+or just change to the test suite root before running Kyua:
+.Bd -literal -offset indent
+$ cd /usr/tests
+$ kyua test
+.Ed
+.Pp
The above will iterate through all test programs in
.Pa /usr/tests
recursively, execute them, store their results and debugging data in Kyua's
database (by default in
-.Pa ~/.kyua/store.db ) ,
+.Pa ~/.kyua/store/ ) ,
and print a summary of the results.
This summary includes a brief count of all total tests run and how many of
them failed.
.Pp
-It is possible to restrict which tests to run by providing their names in
-the command line.
-For example, this would execute the tests for the
+It is possible to restrict which tests to run by providing their
+names, or a portion of their path, on the command line.
+For example, this would execute all of the tests provided for the
.Xr cp 1
and
-.Xr cut 1
+.Xr stat 1
utilities:
.Bd -literal -offset indent
-$ kyua test -k /usr/tests/Kyuafile bin/cp usr.bin/cut
+$ cd /usr/tests
+$ kyua test bin/cp usr.bin/stat
+.Ed
+.Pp
+This would execute only one of the two test programs provided for
+.Xr stat 1 :
+.Bd -literal -offset indent
+$ cd /usr/tests
+$ kyua test usr.bin/stat/stat_test
+.Ed
+.Pp
+This would execute just a single test case:
+.Bd -literal -offset indent
+$ cd /usr/tests
+$ kyua test usr.bin/stat/stat_test:t_flag
+.Ed
+.Pp
+Finally, this would execute that test case in debug mode:
+.Bd -literal -offset indent
+$ cd /usr/tests
+$ kyua debug -p usr.bin/stat/stat_test:t_flag
.Ed
+.Pp
+The
+.Fl p
+option tells Kyua to pause before cleanup so you can inspect the
+temporary directory to better understand why the test failed.
+.Pp
+Note that some tests may require root privileges to execute:
+.Bd -literal -offset indent
+$ cd /usr/tests
+$ kyua debug usr.bin/stat/stat_test:h_flag
+usr.bin/stat/stat_test:h_flag -> skipped: Requires root privileges
+$ sudo kyua debug usr.bin/stat/stat_test:h_flag
+[...]
+usr.bin/stat/stat_test:h_flag -> passed
+.Ed
+.Pp
+Conversely, some tests will only work correctly if run as an
+unprivileged user.
+This will normally be noted in the test's metadata, causing Kyua to
+automatically drop privileges before running the test.
.Ss Obtaining reports of the tests execution
Additional information about the test results can be retrieved
by using Kyua's various reporting commands.
-For example, the following would print a plain-text report of the executed
-tests and show which ones failed:
+For example, the following would print a plain-text report of the
+tests executed in the latest test run and show which ones failed:
+.Bd -literal -offset indent
+$ kyua report --verbose
+.Ed
+.Pp
+To show the results of an arbitrary test run, use the
+.Fl r
+option to specify which results file to read:
+.Bd -literal -offset indent
+$ kyua report --verbose \\
+ -r ~/.kyua/store/results.usr_tests.20260417-173009-335060.db
+.Ed
+.Pp
+Keep in mind that if the tests were run as root, the results will have
+been stored in root's
+.Pa kyua
+directory, and the easiest way to access them will be to run the
+.Cm report
+command as root as well:
.Bd -literal -offset indent
-$ kyua report --verbose -r <.db file from output of test>
+$ cd /usr/tests
+$ sudo kyua test usr.bin/stat
+$ sudo kyua report --verbose
.Ed
.Pp
This example would generate an HTML report ready to be published on a
@@ -207,8 +277,14 @@
User-specific configuration file for
.Xr kyua 1 ;
overrides the system file.
-.It Pa ~/.kyua/store.db
-Default result database used by Kyua.
+.It Pa ~/.kyua/logs/
+Default location of Kyua debug logs (one
+.Pa .log
+file per test run).
+.It Pa ~/.kyua/store/
+Default location of Kyua test results (one
+.Pa .db
+file per test run).
.It Pa /usr/tests/
Location of the
.Fx

File Metadata

Mime Type
text/plain
Expires
Wed, Apr 22, 8:07 AM (10 h, 58 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
31771173
Default Alt Text
D56475.diff (4 KB)

Event Timeline