ATF-TEST-CASE(4)

💖 ATF-TEST-CASE 💖

okay bestie, welcome to atf-test-case(4) from the Kernel Interfaces Manual — this is the generic description of test cases, and honestly it's giving foundational. let's get into it ✨

---

🌸 NAME 🌸

atf-test-case — generic description of test cases 🎀

---

✨ DESCRIPTION ✨

so a test case is a lil piece of code that stress-tests one specific feature of the software. and the way that feature is typically self-contained enough — either in how much code implements it or in the general idea behind it — means it totally warrants its own independent testing. because of that, test cases are very fine-grained, but they do try to group similar smaller tests that are semantically related together. 🫶

every test case, no matter what language it's written in, is defined by three components: a header, a body, and a cleanup routine. let's break it down:

• the header is basically a declarative piece of code that defines several properties describing what the test case does and how it behaves. in other words: it defines the test case's meta-data, which we get into more in the “Meta-data” section below. 📝
• the body is the test case itself. it executes all the actions needed to reproduce the test and checks for failures. this body is only executed if the abstract conditions specified by the header are met. 💅
• the cleanup routine is a piece of code that's always executed after the body, regardless of the exit status of the test case. it can be used to undo side-effects of the test case. and note — almost all side-effects of a test case are automatically cleaned up by the library; that's explained in more detail in the rest of this document. 🧹

keeping the separation between a test case's header and body well-defined is extremely important, because the header is always parsed, whereas the body is only executed when the conditions defined in the header are met and when the user specifies that test case. no cap. 🔥

and finally — test cases are always contained into test programs. the test programs act as a front-end to them, providing a consistent interface to the user and several APIs to ease their implementation. iconic behavior honestly. 👑

---

🌈 Results 🌈

upon termination, a test case reports a status and, optionally, a textual reason describing why the test reported that status. and here's the thing bestie — the caller must ensure that the test case really performed the task that its status describes, because the test program may be bogus and therefore provide a misleading result. like, it could give you a result that indicates success but the error code of the program says otherwise. 💀

the possible exit statuses of a test case are one of the following:

• expected_death — the test case expects to terminate abruptly.
• expected_exit — the test case expects to exit cleanly.
• expected_failure — the test case expects to exit with a controller fatal/non-fatal failure. if this happens, the test program exits with a success error code.
• expected_signal — the test case expects to receive a signal that makes it terminate.
• expected_timeout — the test case expects to execute for longer than its timeout.
• passed — the test case was executed successfully. the test program exits with a success error code.
• skipped — the test case could not be executed because some preconditions were not met. this is not a failure because it can typically be resolved by adjusting the system to meet the necessary conditions. this is always accompanied by a reason, a message describing why the test was skipped. the test program exits with a success error code.
• failed — an error appeared during the execution of the test case. this is always accompanied by a reason, a message describing why the test failed. the test program exits with a failure error code.

the usefulness of the ‘expected_*’ results comes when writing test cases that verify known failures caused, in general, due to programming errors (aka bugs 🐛). whenever the faulty condition that the ‘expected_*’ result is trying to cover gets fixed, then the test case will be reported as ‘failed’ and the developer will have to adjust it to match its new condition. the way that's actually a feature and not a bug, iykyk 😌

it's important to note that all ‘expected_*’ results are only provided as a hint to the caller; the caller must verify that the test case did actually terminate as the expected condition says. periodt. 💅

---

🦋 Input/output 🦋

test cases are free to print whatever they want to their stdout(4) and stderr(4) file descriptors. they are, in fact, encouraged to print status information as they execute to keep the user informed of their actions. this is especially important for long test cases. 📢

test cases will log their results to an auxiliary file, which is then collected by the test program they are contained in. the developer need not care about this as long as he uses the correct APIs to implement the test cases. 🫶

the standard input of the test cases is unconditionally connected to ‘/dev/zero’. yes, unconditionally. no vibes check, it's just zeroes. 🌸

---

🎀 Meta-data 🎀

the following metadata properties can be exposed via the test case's head:

• descr — Type: textual. Optional.

a brief textual description of the test case's purpose. will be shown to the user in reports. also good for documentation purposes. 📖

• has.cleanup — Type: boolean. Optional.

if set to true, specifies that the test case has a cleanup routine that has to be executed by the runtime engine during the cleanup phase of the execution. this property is automatically set by the framework when defining a test case with a cleanup routine, so it should never be set by hand. 🙈

• ident — Type: textual. Required.

the test case's identifier. must be unique inside the test program and should be short but descriptive. this one's mandatory bestie, no skipping it. ✨

• require.arch — Type: textual. Optional.

a whitespace separated list of architectures that the test case can be run under without causing errors due to an architecture mismatch. 🏗️

• require.config — Type: textual. Optional.

a whitespace separated list of configuration variables that must be defined to execute the test case. if any of the required variables is not defined, the test case is skipped. 🌙

• require.diskspace — Type: integer. Optional. specifies the minimum amount of available disk space needed by the test. the value can have a size suffix such as ‘K’, ‘M’, ‘G’ or ‘T’ to make the amount of bytes easier to type and read. 💾
• require.files — Type: textual. Optional.

a whitespace separated list of files that must be present to execute the test case. the names of these files must be absolute paths. if any of the required files is not found, the test case is skipped. 📁

• require.machine — Type: textual. Optional.

a whitespace separated list of machine types that the test case can be run under without causing errors due to a machine type mismatch. 🖥️

• require.memory — Type: integer. Optional. specifies the minimum amount of physical memory needed by the test. the value can have a size suffix such as ‘K’, ‘M’, ‘G’ or ‘T’ to make the amount of bytes easier to type and read. 🧠
• require.progs — Type: textual. Optional.

a whitespace separated list of programs that must be present to execute the test case. these can be given as plain names, in which case they are looked in the user's PATH, or as absolute paths. if any of the required programs is not found, the test case is skipped. 🔧

• require.user — Type: textual. Optional.

the required privileges to execute the test case. can be one of ‘root’ or ‘unprivileged’.

if the test case is running as a regular user and this property is ‘root’, the test case is skipped. 🙅

if the test case is running as root and this property is ‘unprivileged’, the runtime engine will automatically drop the privileges if the ‘unprivileged-user’ configuration property is set; otherwise the test case is skipped. 🔐

• timeout — Type: integral. Optional; defaults to ‘300’.

specifies the maximum amount of time the test case can run. this is particularly useful because some tests can stall either because they are incorrectly coded or because they trigger an anomalous behavior of the program. it is not acceptable for these tests to stall the whole execution of the test program. ⏰

can optionally be set to zero, in which case the test case has no run-time limit. this is discouraged. 🚫

• X-'NAME' — Type: textual. Optional.

a user-defined property named ‘NAME’. these properties are free form, have no special meaning within ATF, and can be specified at will by the test case. the runtime engine should propagate these properties from the test case to the end user so that the end user can rely on custom properties for test case tagging and classification. 🏷️

---

🌈 Environment 🌈

every time a test case is executed, several environment variables are cleared or reseted to sane values to ensure they do not make the test fail due to unexpected conditions. these variables are:

• HOME — set to the work directory's path.
• LANG — undefined.
• LC_ALL — undefined.
• LC_COLLATE — undefined.
• LC_CTYPE — undefined.
• LC_MESSAGES — undefined.
• LC_MONETARY — undefined.
• LC_NUMERIC — undefined.
• LC_TIME — undefined.
• TZ — hardcoded to ‘UTC’.

and that's where part 1 wraps up, bestie — more coming your way 💖

🗂️ Work directories 🗂️

okay so bestie, here's the ✨magic✨ — the test program always makes a temporary directory and switches to it before it runs the test case's body. every single time. no cap.

and the reason is kinda genius: this way the test case is free to mess with its current directory however it wants 😌, and the runtime engine can still clean it all up later in a safe way, yeeting every trace of its execution off the system. it's giving responsible queen behavior 💅

to do that cleanup, the runtime engine does a recursive removal of the work directory, and it does not cross mount points. if it finds a mount point, the file system gets unmounted — if possible. (that "if possible" is doing a lot of heavy lifting there, just saying 🙈)

---

🎀 File creation mode mask (umask) 🎀

test cases are always executed with a file creation mode mask (umask) of 0022. that's the starting vibe, not a cage 🦋

the test case's code is totally free to change it during execution — go off, bestie, it's your process 💖

---

👀 SEE ALSO 👀

• atf-test-program(1) — the whole other page you're gonna wanna read, fr fr 📖✨

---

and that's a wrap on this one, bestie!! this lil page came from the Debian fam, dated December 26, 2024 — so it's official, it's documented, and it's iconic. go write some test cases and slay 💅🎀🦋✨