ATF-TEST-CASE(4)

atf-test-case 💅✨

Section 4 · Kernel Interfaces Manual · ATF-TEST-CASE(4)

okay bestie, welcome to the group chat, because we are about to talk about atf-test-case — and ngl it's giving main character energy in the ATF world. 🎀

---

✨ NAME ✨

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

---

like. that's the whole vibe of this page, fr fr. it's the generic description — the blueprint, the template, the moment before the glow-up. every test case in the ATF universe is a lil cousin of this one. 💖

bestie this page is long so it's coming to you in 2 parts — and this is part 1, so don't you dare close the tab, we are not done. 🌸

💖 DESCRIPTION 💖

okay so bestie, a test case is literally just a piece of code that stress-tests one specific feature of the software. and like, that feature is usually self-contained enough — either in how much code implements it, or in the general ~idea~ of it — that it deserves its own independent testing moment. which means test cases are very fine-grained, but they still group together similar smaller tests that are semantically related. it's giving organized chaos. 🎀

so every test case, no matter what language it's written in, is made of three components: a header, a body, and a cleanup routine.

• The header is basically a declarative lil piece of code that defines a bunch of 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 runs all the actions needed to reproduce the test, and it checks for failures. this body only runs if the abstract conditions in the header are met. no conditions met? no body. periodt.
• The cleanup routine is a piece of code that always runs after the body, no matter what the exit status of the test case was. use it to undo side-effects of the test case. and bestie, note that almost all side-effects of a test case get automatically cleaned up by the library — that's explained in more detail in the rest of this document. 🫶

It is EXTREMELY important to keep the separation between a test case's header and body well-defined, 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. two separate vibe checks, okay? don't mix them up. 💅

and finally: test cases are always contained inside test programs. the test programs act as a front-end to them, giving a consistent interface to the user plus several APIs to make implementing them easier. 👑

---

🌈 Results 🌈

when a test case terminates, it reports a status and, optionally, a textual reason explaining why it reported that status. now listen — the caller has to make sure the test case actually did the thing its status claims, because the test program could be bogus and therefore give a misleading result. like, it could say "success" while the program's error code says otherwise. awkward. 😭

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

• 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. slay! ✨
• 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 shows up when you're writing test cases that verify known failures — which are generally caused by programming errors (aka bugs, we've all been there 🙈). whenever the faulty condition that the ‘expected_*’ result is trying to cover gets fixed, the test case will be reported as ‘failed’ and the developer will have to adjust it to match its new condition. character development fr fr.

⚠️ important bestie: 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. don't just trust it. 💅

---

🌸 Input/output 🌸

test cases are free to print whatever they want to their stdout(4) and stderr(4) file descriptors. in fact they're encouraged to print status information as they execute, to keep the user informed of their actions. this is specially important for long test cases — nobody wants to stare at a silent terminal wondering if it's frozen. 👀

test cases will log their results to an auxiliary file, which then gets collected by the test program they're contained in. the developer doesn't need to care about this as long as he uses the correct APIs to implement the test cases. iykyk. 🧚

the standard input of the test cases is unconditionally connected to ‘/dev/zero’. yeah. that's just how it is.

---

✨ Meta-data ✨

this next list describes all the meta-data properties interpreted internally by ATF. you're free to define new properties in your test cases and use them however you want, but non-standard properties must be prefixed by ‘X-’. house rules, bestie. 🎀

• descr — Type: textual. Required.

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. put your hands down, the framework's got this. 🙌

• ident — Type: textual. Required.

the test case's identifier. must be unique inside the test program and should be short but descriptive.

• 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're looked for 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're 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. not on my watch. 😤

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

---

🦋 Environment 🦋

every single time a test case is executed, several environment variables get cleared or reseted to sane values, so they can't 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’. timezone consistency, we love to see it. ⏰

---

💜 Work directories 💜

the test program always creates a temporary directory and switches to it before running the test case's body. this way the test case is free to modify its current directory however it wishes, and the runtime engine will be able to clean it up later on in a safe way — removing any traces of its execution from the system. 🧹✨

to do so, the runtime engine will perform a recursive removal of the work directory without crossing mount points; if a mount point is found, the file system will be unmounted (if possible). careful, bestie, that's the spicy part. 🔥

---

🎀 File creation mode mask (umask) 🎀

test cases are always executed with a file creation mode mask (umask) of ‘0022’. the test case's code is free to change this during execution though — live your truth. 💅

---

👑 SEE ALSO 👑

atf-test-program(1)

---

and that's the whole page, bestie! this one came from the Debian crew, dated March 6, 2017, and it lives in the ATF-TEST-CASE(4) manual — go forth and write iconic test cases. mwah. 💖✨🎀🦋