KYUA-LIST(1)

💖 KYUA-LIST 💖

okay bestie, welcome to kyua-list(1) — the manual page for kyua list, and yes it is exactly as iconic as it sounds. sit down, grab a strawberry 🍓, and let's get into it.

---

✨ NAME ✨

kyua list — lists test cases and their metadata 🦋

---

🌸 SYNOPSIS 🌸

kyua list [--build-root path] [--kyuafile file] [--verbose] test_case1
     [.. test_caseN]

---

👑 DESCRIPTION 👑

okay so kyua list scans all the test programs and test cases in a test suite (the test suite is defined by a kyuafile(5), iykyk) and then prints out a list of all their names — and optionally, if you ask nicely, it also shows off any metadata properties they have. it's giving "let me introduce you to everyone at the party". ✨

the optional arguments you pass to kyua list are how you pick <em>which</em> test programs or test cases get listed. they're filters, and we explain them down below in "Test filters". 💅

important: this command has to be run inside a test suite, or you have to hand it a test suite with the --kyuafile flag. no test suite, no list, no vibes. 😭

these are the subcommand options it recognizes:

• --build-root path — tells it where the build root is, like, where to go find the test programs that the Kyuafile points at, in case that's a different place than the Kyuafile's own directory. more on this in "Build directories" below 🎀
• --kyuafile path, -k path — picks which Kyuafile to process. default is a Kyuafile file chillin' in the current directory.
• --verbose, -v — prints the metadata properties for every single test case. all of them. the whole buffet. 🔥

---

🧚 Build directories 🧚

so, build directories — also called object directories, target directories, product directories, etc., because why have one name when you can have four — are this concept that lets a developer keep the source tree clean from build products by asking the build system to dump all those build products into a separate subtree instead. queen behavior honestly 👑

most build systems these days support build directories. for example, the GNU Automake/Autoconf build system exposes that concept when you invoke it like this:

$ cd my-project-1.0
$ mkdir build
$ cd build
$ ../configure
$ make

with that invocation, all the results of the build end up in the my-project-1.0/build/ subdirectory, while the contents of my-project-1.0/ stay perfectly intact. no mess, no stress 💅

and because build directories are a whole integral part of most build systems, and because they're a tool developers use all the time, kyua list supports build directories too. that shows up as kyua list being able to run tests from build directories while reading the (often immutable) test suite definition from the source tree. it's multi-talented fr fr.

one super important property of build directories is that they follow (or, like, need to follow) the exact same layout as the source tree. for example, consider these directory listings:

src/Kyuafile
src/bin/ls/
src/bin/ls/Kyuafile
src/bin/ls/ls.c
src/bin/ls/ls_test.c
src/sbin/su/
src/sbin/su/Kyuafile
src/sbin/su/su.c
src/sbin/su/su_test.c

obj/bin/ls/
obj/bin/ls/ls*
obj/bin/ls/ls_test*
obj/sbin/su/
obj/sbin/su/su*
obj/sbin/su/su_test*

notice how the directory layout inside src/ matches the one in obj/? matchy matchy 🫶 the src/ directory holds only source files and the definition of the test suite (the Kyuafiles), while the obj/ directory holds only the binaries that got generated during a build.

all commands that deal with the workspace support the --build-root path option. when you provide it, the directory you specified is treated as the root of the build directory. so, using our previous fake tree layout, we could invoke kyua list as any of these:

$ kyua list --kyuafile=src/Kyuafile --build-root=obj
$ cd src && kyua list --build-root=../obj

---

🎀 Test filters 🎀

a test filter is a string used to match test cases or test programs in a test suite. filters look like this:

test_program_name[:test_case_name]

where test_program_name is the name of a test program or a subdirectory in the test suite, and test_case_name is the name of a test case. that's it, that's the whole format 💖

---

💀 EXIT STATUS 💀

kyua list returns 0 on success, or 1 if any of the test case filters you gave it doesn't match any test case. (rude, but fair.)

additional exit codes may be returned as described in kyua(1).

---

🌈 SEE ALSO 🌈

kyua(1), kyuafile(5)

---

and that's the whole page, bestie!! 🎀✨ this lil' cutie came from the Debian folks and it's dated October 13, 2014 — old but iconic, and it ate, no cap. go forth and kyua list responsibly 💅💖🦋