From nobody Sat Apr 25 17:11:49 2026 X-Original-To: dev-commits-src-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4g2xFf0HtFz6bq7J for ; Sat, 25 Apr 2026 17:11:50 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R13" (not verified)) by mx1.freebsd.org (Postfix) with ESMTPS id 4g2xFd3KLFz3L10 for ; Sat, 25 Apr 2026 17:11:49 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1777137109; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=Sh+XM8Wv7ELhxBd1kPEDubIVNIH0vtTF6OOeE5zBu7k=; b=ctTRU+IUFdphtVCKCr9fe5WqTrXsFPB7J2dvEPxCc5fxxBc+C7YFMS5E0Lft00YiUiPnzx TiExHFfqixqughhTj+j5kR7zjFc2FA92IZSzuRqVmM8hQ6K9cDndH/xCmBdTYxy35YIgdp DHachR2MHAUC9tjZYY1sTlTcnU+jlusyBxb29FkxXmwmsSYbzoIFJHwvnbtqHnsGszvAZu 9VO0OmqwCXGWU7EwE5OKhXDKEWpbVQeLSMAg/T2yzofgmkx3G2EBEooX6KHfRygxhgNiXj ccTcMB8QTqjYL53wJ/kf3S38xwvT9GKITW9NcS8zNZd6leg/qFEmZ8BcBHL6FA== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1777137109; a=rsa-sha256; cv=none; b=HYgJykx0kgjV/Cz15AzMxr6r5/Elp9bBizi29kSzocuQbct+rXd1Y5bKFH9OxwpHo+95+t Hc3c8jBSqszal+4i4NE/ORjB8qORYsmJzRpTfMyYgxNdwuU0+RIKFIDqLwgp2NqtmTKT0c hx2aZstNBZoagb/Ul7u0dyNJBT2fZtYt7es7OHu53ZWVf/8RxE7GO1b0Vl7A73tPbeF/gt RY0NcR49pPP9doZLfaD8GaJNS0CpTJwCxtgnL9Dd36o0TjV3q0rorE+Ba0pUvOixC+uhH3 NlJQQsO+RMrmGRFgnQBWqVndcWXV6EciEkKniG6jgF2P6eKyHq7J3xQYejJTBQ== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1777137109; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=Sh+XM8Wv7ELhxBd1kPEDubIVNIH0vtTF6OOeE5zBu7k=; b=G/OXQS+zdEqyPeo2eF2ePWW/tCxgz4x/8un/QkkWZPwfe9gPOBBFLWKDuTn9U+qxkR1MFY ISeidoxy5Ev9ggNxa1lPOuQWiBfGDJxpEd5TDdVGrD38tATUfXbnHS8Ik6z9dosaY72tIB HEuf9GH2LXiOcd6JqGocySlaQrBWxrNIxe690/12kI/Q54uHt8a1EpWH24H1/GdgqS/qC/ rWJhWCDBoTpqMCa4dMM/oOfrNLRsnsjCk2JFcpejuW3JD12HZW3Sla5R2Jd+uy0zpAQftV rDJ+8g89TMYe1Qb2OGKWVrAkajc/sUlaJWBRZFk3URfk5pGsQA6gVfc1cXN7WQ== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) by mxrelay.nyi.freebsd.org (Postfix) with ESMTP id 4g2xFd2sCRzjtg for ; Sat, 25 Apr 2026 17:11:49 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from git (uid 1279) (envelope-from git@FreeBSD.org) id 18446 by gitrepo.freebsd.org (DragonFly Mail Agent v0.13+ on gitrepo.freebsd.org); Sat, 25 Apr 2026 17:11:49 +0000 To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-branches@FreeBSD.org From: Dag-Erling=?utf-8?Q? Sm=C3=B8rg?=rav Subject: git: 3e08beca5acb - stable/15 - tests.7: Provide better examples List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-all@freebsd.org Sender: owner-dev-commits-src-all@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: des X-Git-Repository: src X-Git-Refname: refs/heads/stable/15 X-Git-Reftype: branch X-Git-Commit: 3e08beca5acb8ceef831d78c507c93406c46831f Auto-Submitted: auto-generated Date: Sat, 25 Apr 2026 17:11:49 +0000 Message-Id: <69ecf5d5.18446.552dc72c@gitrepo.freebsd.org> The branch stable/15 has been updated by des: URL: https://cgit.FreeBSD.org/src/commit/?id=3e08beca5acb8ceef831d78c507c93406c46831f commit 3e08beca5acb8ceef831d78c507c93406c46831f Author: Dag-Erling Smørgrav AuthorDate: 2026-04-22 08:19:32 +0000 Commit: Dag-Erling Smørgrav CommitDate: 2026-04-25 17:11:25 +0000 tests.7: Provide better examples Previous authors appear to have prioritized brevity over clarity. This unfortunately resulted in a manual page that left its reader with the false impression that Kyua is difficult to use. Attempt to correct this by providing more and simpler examples with longer explanations. While here, correct outdated information about where Kyua stores its logs and results. MFC after: 1 week Reviewed by: ziaee, ngie Differential Revision: https://reviews.freebsd.org/D56475 (cherry picked from commit 3d00db6b8b73ef7f89654a2928d247d62d39ee29) --- share/man/man7/tests.7 | 102 ++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 89 insertions(+), 13 deletions(-) diff --git a/share/man/man7/tests.7 b/share/man/man7/tests.7 index 61b0789b9149..97cc6beba4dc 100644 --- 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 @@ third-party packages or manual modifications to configuration files) do not 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 @@ System-wide configuration file for 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