TESTING.SH(1)

✨ NAME ✨

TESTING.SH(1) — BeakerLib - testing - asserting functions, watchdog and report 🫶 (from the User Contributed Perl Documentation corner of the universe)

Okay bestie, this is the BeakerLib page for testing, and it’s lowkey the main-character energy of your test phase. ✨

🌸 DESCRIPTION 🌸

This file contains functions related directly to testing. These functions are various asserts affecting final result of the phase. Watchdog and the report result function is included as well. No cap. 💅

🧪 FUNCTIONS 🧪

💅 Manual Asserts 💅

These are the manual ones, bestie — you’re literally calling the result yourself. Periodt.

rlPass

Manual assertion, asserts and logs PASS. It’s giving instant good vibes.

rlPass comment

• comment — short test summary.

Returns 0 and asserts PASS. 🎀

rlFail

Manual assertion, asserts and logs FAIL. Not the vibe, but sometimes you gotta.

rlFail comment

• comment — short test summary.

Returns 1 and asserts FAIL. 💀

🧮 Arithmetic Asserts 🧮

Math girlie hours. 🧮

rlAssert0

Assertion checking for the equality of parameter to zero.

rlAssert0 comment value

• comment — short test summary, e.g. "Test if compilation ended successfully".
• value — integer value (usually return code of a command).

Returns 0 and asserts PASS when value == 0. 👑

rlAssertEquals

Assertion checking for the equality of two parameters.

rlAssertEquals comment value1 value2

• comment — short test summary, e.g. "Test if all 3 packages have been downloaded".
• value1 — first parameter to compare, can be a number or a string.
• value2 — second parameter to compare, can be a number or a string.

Returns 0 and asserts PASS when value1 == value2. ✨

rlAssertNotEquals

Assertion checking for the non-equality of two parameters.

rlAssertNotEquals comment value1 value2

• comment — short test summary, e.g. "Test if return code is not 139".
• value1 — first parameter to compare, can be a number or a string.
• value2 — second parameter to compare, can be a number or a string.

Returns 0 and asserts PASS when value1 != value2. 🔥

rlAssertGreater

Assertion checking whether first parameter is greater than the second one.

rlAssertGreater comment value1 value2

• comment — short test summary, e.g. "Test whether there are running more instances of program."
• value1 — integer value.
• value2 — integer value.

Returns 0 and asserts PASS when value1 > value2. 🌈

rlAssertGreaterOrEqual

Assertion checking whether first parameter is greater or equal to the second one.

rlAssertGreaterOrEqual comment value1 value2

• comment — short test summary (e.g. "There should present at least one...")
• value1 — integer value.
• value2 — integer value.

Returns 0 and asserts PASS when value1 X= value2. 🫶

rlAssertLesser

Assertion checking whether first parameter is lesser than the second one.

rlAssertLesser comment value1 value2

• comment — short test summary, e.g. "Test whether there are running more instances of program."
• value1 — integer value.
• value2 — integer value.

Returns 0 and asserts PASS when value1 < value2. 🦋

rlAssertLesserOrEqual

Assertion checking whether first parameter is lesser or equal to the second one.

rlAssertLesserOrEqual comment value1 value2

• comment — short test summary (e.g. "There should present at least one...")
• value1 — integer value.
• value2 — integer value.

Returns 0 and asserts PASS when value1 X= value2. 🎀

📁 File Asserts 📁

Filesystem vibe check. 📁

rlAssertExists

Assertion checking for the existence of a file or a directory.

rlAssertExists file|directory

• file|directory — path to the file or directory.

Returns 0 and asserts PASS when file exists. 💖

rlAssertNotExists

Assertion checking for the non-existence of a file or a directory.

rlAssertNotExists file|directory

• file|directory — path to the file or directory.

Returns 0 and asserts PASS when file does not exist. 🙈

rlAssertGrep

Assertion checking if the file contains a pattern.

rlAssertGrep pattern file [options]

• pattern — regular expression to be searched for.
• file — path to the file.
• options — optional parameters to be passed to grep, default is -q. Can be used to perform case insensitive matches (-i), or using extended (-E) or perl (-P) regular expressions.

Returns 0 and asserts PASS when file exists and contains given pattern. 🔍

rlAssertNotGrep

Assertion checking that the file does not contain a pattern.

rlAssertNotGrep pattern file [options]

• pattern — regular expression to be searched for.
• file — path to the file.
• options — optional parameters to be passed to grep, default is -q. Can be used to perform case insensitive matches (-i), or using extended (-E) or perl (-P) regular expressions.

Returns 0 and asserts PASS when file exists and does not contain given pattern. 🚫

rlAssertDiffer

Assertion checking that two files differ (are not identical).

rlAssertDiffer file1 file2

• file1 — path to first file1.
• file2 — path to second file.

Returns 0 and asserts PASS when file1 and file2 differs. 💅

rlAssertNotDiffer

Assertion checking that two files do not differ (are identical).

rlAssertNotDiffer file1 file2

• file1 — path to first file1.
• file2 — path to second file.

Returns 0 and asserts PASS when file1 and file2 do not differ. 🫶

🏃 Run, Watch, Report 🏃

Main character section, no cap. 🏃

rlRun

Run command with optional comment and make sure its exit code matches expectations. This one is iconic.

rlRun [-t] [-l] [-c] [-s] command [status[,status...] [comment]]

• -t — if specified, stdout and stderr of the command output will be tagged with strings 'STDOUT: ' and 'STDERR: '.
• -l — if specified, output of the command (tagged, if -t was specified) is logged using rlLog function. This is intended for short outputs, and therefore only last 50 lines are logged this way. Longer outputs should be analysed separately, or uploaded via rlFileSubmit or rlBundleLogs.
• -c — same as -l, but only log the command output if it failed.
• -s — store stdout and stderr to a file (mixed together, as the user would see it on a terminal) and set $rlRun_LOG variable to name of the file. $rlRun_LOG is now actually an array where the first index holds the last reference to the file. Thus its behavior is not changed if used without an index. The array is consumed by the rlJournalEnd function to remove the leftover files, so no manual files removal is needed anymore. Note that if you need to use such a file after calling the rlJournalEnd function you need to create your own copy of the respective file. When -t option is used, the content of the file becomes tagged too.

If the -s option is not used, $rlRun_LOG is not modified and keeps its content from the last "rlRun -s".

• command — command to run.
• status — expected exit code(s). Optional, default 0. If you expect more exit codes, separate them with comma (e.g. "0,1" when both 0 and 1 are OK and expected), or use from-to notation (i.e. "2-5" for "2,3,4,5"), or combine them (e.g. "2-4,26" for "2,3,4,26").
• comment — short summary describing the action (optional, but recommended - explain what you are doing here).

Returns the exit code of the command run. Asserts PASS when command's exit status is in the list of expected exit codes. ⭐

Note:

• The output of rlRun is buffered when using -t, -l or -s option (they use unix pipes, which are buffered by nature). If you need an unbuffered output just make sure that "expect" package is installed on your system (its "unbuffer" tool will automatically be used to produce unbuffered output).
• Be aware that there are some variables which can collide with your code executed within rlRun. You should avoid using __INTERNAL_rlRun_* variables.
• When any of -t -l, -c, or -s option is used, special file descriptors 111 and 112 are used to avoid the issue with incomplete log file, bz1361246. As there might be an indefinite loop, there's a timeout of two minutes implemented as a fix for bz1416796. Also an error message is issued to signal the possibility of running subprocess which keeps the file descriptors open.

Do not use these options if you expect process forking and continuous run. Try your own appropriate solution instead.

Warning: using "unbuffer" tool is now disabled because of bug 547686. 😭

rlWatchdog

Run "command". If it does not finish in specified time, then kill it using "signal". Note that the command is executed in a sub-shell so modified environment (e.g. set variables) is not reflected in the test environment. ⏱️

rlWatchdog command timeout [signal] [callback]

• command — command to run.
• timeout — timeout to wait, in seconds.
• signal — signal to use (optional, default KILL).
• callback — callback function to be called before the signal is send (optional, none by default). The callback function will have one argument available -- PGID of the process group.

Returns 0 if the command ends normally, without need to be killed. 🕰️

rlReport

Report test result to the test harness. The command to be used for reporting is set by the respective plugin. You can also use the $BEAKERLIB_COMMAND_REPORT_RESULT variable to use your custom command.

rlReport name result [score] [log]

• name — name of the test result.
• result — result (one of PASS, WARN, FAIL, SKIP). If called with something else, will use WARN.
• score — test score (optional).
• log — optional log file to be submitted instead of default "OUTPUTFILE".

rlCmpVersion

Compare two given versions composed by numbers and letters divided by dot (.), underscore (_), or dash (-). 🔢

rlCmpVersion ver1 ver2

If ver1 = ver2, sign '=' is printed to stdout and 0 is returned. If ver1 > ver2, sign '>' is printed to stdout and 1 is returned. If ver1 < ver2, sign '<' is printed to stdout and 2 is returned. 🦋

rlTestVersion

Test relationship between two given versions based on given operator.

rlTestVersion ver1 op ver2

• op — operator defining the logical expression. It can be '=', '==', '!=', '<', '<=', '=<', '>', '>=', or '=>'.

Returns 0 if the expression ver1 op ver2 is true; 1 if the expression is false and 2 if something went wrong. 💜

📦 Release Info 📦

OS release tea. ☕

Can use environment variable BEAKERLIB_OS_RELEASE for alternative os-release information. You can either supply a file path (recognised by starting with "/") or directly as a list of environment variables.

Example:

BEAKERLIB_OS_RELEASE="ID=rhel VERSION_ID=42" rlIsRHEL 42

rlIsRHEL

rlIsRHEL 🐧

rlIsRHEL [VERSION_SPEC]...

VERSION_SPEC — tells it which version of that particular RHEL distribution you mean, like 8, 8.4, or ">8.4".

For the full tea on how version specs work, go read the description of rlIsOSVersion (it's down below bestie, keep scrolling 💖).

Returns 0 when we're running on RHEL. And if you hand it version specs as arguments, it returns 0 only if that particular RHEL version is the one running.

Prototype:

rlIsRHEL

Returns 0 if we are running on RHEL.

rlIsRHEL 7 '>=8.5'

Returns 0 if we are running any RHEL 7 or RHEL 8.5 and higher.

---

rlIsFedora 🎩

rlIsFedora [VERSION_SPEC]...

VERSION_SPEC — specifies the version of that particular Fedora distribution, eg. 30, ">30".

More details live in the description of rlIsOSVersion, go peek 👀.

Returns 0 when we're running on Fedora. With version specs in the arguments it returns 0 if that particular Fedora version is running.

Prototype:

rlIsFedora

Returns 0 if we are running on Fedora.

rlIsFedora 30 32

Returns 0 if we are running Fedora 30 or 32.

---

rlIsCentOS 🌸

rlIsCentOS [VERSION_SPEC]...

VERSION_SPEC — specifies the version of that particular CentOS distribution, eg. 7, ">7".

Again, more details in the description of rlIsOSVersion.

Returns 0 when we're running on CentOS. With version specs in the arguments it returns 0 if that particular CentOS version is running.

Prototype:

rlIsCentOS

Returns 0 if we are running on CentOS.

rlIsCentOS 7.1 6

Returns 0 if we are running CentOS 7.1 or any CentOS 6.

---

rlIsOS 💻

rlIsOS ID

ID — this argument is based on the contents of /etc/os-release. Possible options for ID are e.g. fedora, rhel, centos, ol.

Returns 0 when we're running a system with the respective ID. Returns 1 when the parameter doesn't match the ID in os-release. Returns 2 when there's no ID defined. Returns 3 when no argument is given. (Yes bestie, it has opinions about your mistakes 💅)

Prototype:

rlIsOS rhel

Returns 0 if we are running on RHEL.

---

rlIsOSLike 🪞

rlIsOSLike ID_LIKE

ID_LIKE — based on the contents of /etc/os-release. Possible options for ID_LIKE are e.g. fedora, rhel.

Returns 0 when we're running a system with the requested ID_LIKE. Returns 1 when the parameter doesn't match ID nor ID_LIKE in os-release. Returns 2 when there's no ID or ID_LIKE defined. Returns 3 when no argument is given.

Prototype:

rlIsOSLike rhel

Returns 0 if we are running on RHEL, CentOS, Rocky Linux, etc..

rlIsOSLike fedora

Returns 0 if we are running on Fedora, RHEL, CentOS, Oracle Linux, etc..

---

rlIsOSVersion 🔢

rlIsOsVersion VERSION_SPEC...

VERSION_SPEC — this parameter is based on VERSION_ID in /etc/os-release. It's either "major" or "major"."minor" referring to a particular release.

It accepts multiple arguments separated by space (8.1 8.2 8.3 9).

To specify a group of distributions you can pass an optional operator together with the version number as one string ('>8.5'). The operator can be '<', '<=', '=<', '=', '>', '>=', matching whether the currently installed version is lesser, lesser or equal, equal, equal or greater, or greater than the version number supplied as the second half of the argument.

⚠️ Heads up bestie: when you use the >/< operators you have to either put the argument in quotes or escape the operators, otherwise bash will snatch them as a redirection operator and it will be a whole mess 😭

Returns 0 when we're running a distribution of the particular version requested by the argument.

It usually follows after rlIsOS and rlIsOSLike.

Be cautious when using it together with rlIsOSLike, because different distributions may use different versioning schema. (Not all heroes use the same numbering, ok? 👑)

Prototype:

rlIsOSVersion 6 7 9

Returns 0 if we are running a distribution with VERSION_ID 6, 7 or 9.

rlIsOSVersion 7.8 8

Returns 0 if we are running distribution 7.8 or any 8.

rlIsOSVersion ">=7.5" or rlIsOSVersion \>=7.5

Returns 0 if we are running distribution 7.5 or higher (both minors or majors).

Note:

rlIsOSVersion '<7.5' || rlIsOSVersion '<8.5'

would also cover 7.9, since it is less than 8.5 — which is not what you want 🙈. So if you want to construct a condition for a distribution <7.5 within the major 7, or a distribution <8.5 within the major 8, you actually need to use the following construct:

rlIsOSVersion 7 && rlIsOSVersion '<7.5' || rlIsOSVersion 8 && rlIsOSVersion '<8.5'

This returns 0 when running a distribution less than 7.5 and less than 8.5, but not 7.9 (nor 6.9). Slay, logic 💀

---

rlIsRHELLike 🎀

rlIsRHELLike [VERSION_SPEC]...

VERSION_SPEC — specifies the version of that particular RHEL distribution, eg. 8, 8.4, ">8.4".

For more details see the description of rlIsOSVersion.

Returns 0 when we're running on a RHEL-like distribution. These are considered to be RHEL, CentOS, Rocky Linux, etc.. With the given version specification in the arguments it returns 0 if that particular version of the RHEL-like distribution is running.

Prototype:

rlIsRHELLike

Returns 0 if we are running on a RHEL-like system.

rlIsRHELLike ">=6"

Returns 0 if we are running on a RHEL-like distribution of version 6.0 or higher.

---

✨ AUTHORS ✨

The absolute icons who made this happen 🫶:

• Ondrej Hudlicky <ohudlick@redhat.com>
• Petr Muller <pmuller@redhat.com>
• Jan Hutar <jhutar@redhat.com>
• Petr Splichal <psplicha@redhat.com>
• Ales Zelinka <azelinka@redhat.com>

---

and that's the whole page bestie!! 💖 You just read TESTING.SH(1) brought to you by perl v5.32.1, dated 2026-04-07. Go forth and vibe check your OS versions responsibly ✨🦋💅