1BEAKERLIB(1) User Contributed Perl Documentation BEAKERLIB(1)
2
6 BeakerLib - a shell-level integration testing library
7
9 BeakerLib is a shell-level integration testing library, providing
10 convenience functions which simplify writing, running and analysis of
11 integration and blackbox tests.
12 The essential features include:
14 • Journal - uniform logging mechanism (logs & results saved in
16 flexible XML format, easy to compare results & generate reports)
17 • Phases - logical grouping of test actions, clear separation of
19 setup / test / cleanup (preventing false fails)
20 • Asserts - common checks affecting the overall results of the
22 individual phases (checking for exit codes, file existence &
23 content...)
24 • Helpers - convenience functions for common operations such as
26 managing services, backup & restore
27 The main script sets the "BEAKERLIB" variable and sources other scripts
29 where the actual functions are defined. You should source it at the
30 beginning of your test with:
31 . /usr/share/beakerlib/beakerlib.sh
33 See the EXAMPLES section for quick start inspiration.
35 See the BKRDOC section for more information about Automated
37 documentation generator for BeakerLib tests.
38 Result fingerprint
40 Beakerlib provides two types of fingerprint of the test run. The
41 fingerprints are counted at the phase end and journal end.
42 The first one is a phases fingerprint which represents a list of the
44 results of all the executed phases in the order of the execution.
45 The second one is a asserts fingerprint which represents a list of the
47 results of all the executed asserts in the order of the execution.
48 The lists are then hashed resulting in a 8 letters string.
50 Such fingerprint may be used as a reference result of the respective
52 test run in a particular environment.
53
55 Journalling
56 rlJournalStart
57 Initialize the journal file.
59 rlJournalStart
61 Run on the very beginning of your script to initialize journalling
63 functionality.
64 rlJournalEnd
66 Summarize the test run and upload the journal file.
68 rlJournalEnd
70 Run on the very end of your script to print summary of the whole test
72 run, generate OUTPUTFILE and include journal in Beaker logs.
73 rlJournalPrint
75 Print the content of the journal in pretty xml format.
77 rlJournalPrint [type]
79 type
81 Can be either 'raw' or 'pretty', with the latter as a default.
82 Raw: xml is in raw form, no indentation etc Pretty: xml is pretty
83 printed, indented, with one record per line
84 Example:
86 <?xml version="1.0"?>
88 <BEAKER_TEST>
89 <test_id>debugging</test_id>
90 <package>setup</package>
91 <pkgdetails>setup-2.8.9-1.fc12.noarch</pkgdetails>
92 <starttime>2010-02-08 15:17:47</starttime>
93 <endtime>2010-02-08 15:17:47</endtime>
94 <testname>/examples/beakerlib/Sanity/simple</testname>
95 <release>Fedora release 12 (Constantine)</release>
96 <hostname>localhost</hostname>
97 <arch>i686</arch>
98 <purpose>PURPOSE of /examples/beakerlib/Sanity/simple
99 Description: Minimal BeakerLib sanity test
100 Author: Petr Splichal <psplicha@redhat.com>
101 This is a minimal sanity test for BeakerLib. It contains a single
103 phase with a couple of asserts. We Just check that the "setup"
104 package is installed and that there is a sane /etc/passwd file.
105 </purpose>
106 <log>
107 <phase endtime="2010-02-08 15:17:47" name="Test" result="PASS"
108 score="0" starttime="2010-02-08 15:17:47" type="FAIL">
109 <test message="Checking for the presence of setup rpm">PASS</test>
110 <test message="File /etc/passwd should exist">PASS</test>
111 <test message="File '/etc/passwd' should contain 'root'">PASS</test>
112 </phase>
113 </log>
114 </BEAKER_TEST>
115 rlJournalPrintText
117 Print the content of the journal in pretty text format.
119 rlJournalPrintText [--full-journal]
121 --full-journal
123 The option is now deprecated, has no effect and will be removed in
124 a future version.
125 Example:
127 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
129 :: [ LOG ] :: TEST PROTOCOL
130 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
131 :: [ LOG ] :: Test run ID : debugging
133 :: [ LOG ] :: Package : debugging
134 :: [ LOG ] :: Test started : 2010-02-08 14:45:57
135 :: [ LOG ] :: Test finished : 2010-02-08 14:45:58
136 :: [ LOG ] :: Test name :
137 :: [ LOG ] :: Distro: : Fedora release 12 (Constantine)
138 :: [ LOG ] :: Hostname : localhost
139 :: [ LOG ] :: Architecture : i686
140 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
142 :: [ LOG ] :: Test description
143 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
144 PURPOSE of /examples/beakerlib/Sanity/simple
146 Description: Minimal BeakerLib sanity test
147 Author: Petr Splichal <psplicha@redhat.com>
148 This is a minimal sanity test for BeakerLib. It contains a single
150 phase with a couple of asserts. We Just check that the "setup"
151 package is installed and that there is a sane /etc/passwd file.
152 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
155 :: [ LOG ] :: Test
156 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
157 :: [ PASS ] :: Checking for the presence of setup rpm
159 :: [ PASS ] :: File /etc/passwd should exist
160 :: [ PASS ] :: File '/etc/passwd' should contain 'root'
161 :: [ LOG ] :: Duration: 1s
162 :: [ LOG ] :: Assertions: 3 good, 0 bad
163 :: [ PASS ] :: RESULT: Test
164 rlGetTestState
166 Returns number of failed asserts so far, or 255 if there are more than
168 255 failures. The variable ECODE is set to the precise number.
169 rlGetTestState
171 rlGetPhaseState
173 Returns number of failed asserts in the current phase so far, or 255 if
175 there are more than 255 failures. The variable ECODE is set to the
176 precise number.
177 rlGetPhaseState
179 Logging
181 rlLog
182 rlLogDebug
184 rlLogInfo
186 rlLogWarning
188 rlLogError
190 rlLogFatal
192 Create a time/priority-labelled message in the log. There is a bunch of
194 aliases which can create messages formated as DEBUG/INFO/WARNING/ERROR
195 or FATAL (but you would probably want to use rlDie instead of the last
196 one).
197 rlLog message [logfile] [priority] [label]
199 message
201 Message you want to show (use quotes when invoking).
202 logfile
204 Log file. If not supplied, OUTPUTFILE is assumed.
205 priority
207 Priority of the log.
208 label
210 Print this text instead of time in log label.
211 rlDie
213 Create a time-labelled message in the log, report test result, upload
215 logs, close unfinished phase and terminate the test.
216 rlDie message [file...]
218 message
220 Message you want to show (use quotes when invoking) - this option
221 is mandatory.
222 file
224 Files (logs) you want to upload as well. "rlBundleLogs" will be
225 used for it. Files which are not readable will be excluded before
226 calling "rlBundleLogs", so it is safe to call even with possibly
227 nonexistent logs and it will succeed.
228 rlBundleLogs
230 Create a tarball of files (e.g. logs) and attach them to the test
232 result.
233 rlBundleLogs package file [file...]
235 package
237 Name of the package. Will be used as part of the tarball name.
238 file
240 File(s) to be packed and submitted.
241 Returns result of submitting the tarball.
243 rlFileSubmit
245 Resolves absolute path to the file, replaces / with - and uploads this
247 renamed file using rhts-submit-log. It also allows you to specify your
248 custom name for the uploaded file.
249 rlFileSubmit [-s sep] path_to_file [required_name]
251 -s sep
253 Sets separator (i.e. the replacement of the /) to sep.
254 path_to_file
256 Either absolute or relative path to file. Relative path is
257 converted to absolute.
258 required_name
260 Default behavior renames file to full_path_to_file with / replaced
261 for -, if this does not suit your needs, you can specify the name
262 using this option.
263 Examples:
265 rlFileSubmit logfile.txt -> logfile.txt cd /etc; rlFileSubmit
267 ./passwd -> etc-passwd rlFileSubmit /etc/passwd -> etc-passwd
268 rlFileSubmit /etc/passwd my-top-secret_file -> my-top-secret-file
269 rlFileSubmit -s '_' /etc/passwd -> etc_passwd
270 Info
272 rlShowPackageVersion
273 Shows a message about version of packages.
275 rlShowPackageVersion package [package...]
277 package
279 Name of a package(s) you want to log.
280 rlGetArch
282 Sanitize architecture for simplier matching.
284 Return base arch for the current system (good when you need base arch
286 on a multilib system).
287 rlGetArch
289 On any 32-bit Intel (i386, i486, i586, ...) system you will get i386.
291 rlGetPrimaryArch
293 Return primary arch for the current system (good when you need base
295 arch on a multilib system).
296 rlGetPrimaryArch
298 On non-RHEL systems if the primary/secondary sedicision fails a
300 fallback to rlGetArch is done.
301 rlGetSecondaryArch
303 Return base arch for the current system (good when you need base arch
305 on a multilib system).
306 rlGetSecondaryArch
308 rlGetDistroRelease
310 rlGetDistroVariant
312 Return release or variant of the distribution on the system.
314 rlGetDistroRelease
316 rlGetDistroVariant
317 For example on the RHEL-4-AS you will get release 4 and variant AS, on
319 the RHEL-5-Client you will get release 5 and variant Client.
320 rlShowRunningKernel
322 Log a message with version of the currently running kernel.
324 rlShowRunningKernel
326 Phases
328 rlPhaseStart
329 Starts a phase of a specific type. The final phase result is based on
331 all asserts included in the phase. Do not forget to end phase with
332 "rlPhaseEnd" when you are done.
333 rlPhaseStart type [name]
335 type
337 Type of the phase, one of the following:
338 FAIL
340 When assert fails here, phase will report a FAIL.
341 WARN
343 When assert fails here, phase will report a WARN.
344 name
346 Optional name of the phase (if not provided, one will be
347 generated).
348 If all asserts included in the phase pass, phase reports PASS.
350 rlPhaseEnd
352 End current phase, summarize asserts included and report phase result.
354 rlPhaseEnd
356 Final phase result is based on included asserts and phase type.
358 rlPhaseStartSetup
360 rlPhaseStartTest
362 rlPhaseStartCleanup
364 Start a phase of the specified type: Setup -> WARN, Test -> FAIL,
366 Cleanup -> WARN.
367 rlPhaseStartSetup [name]
369 rlPhaseStartTest [name]
370 rlPhaseStartCleanup [name]
371 name
373 Optional name of the phase. If not specified, default
374 Setup/Test/Cleanup are used.
375 If you do not want these shortcuts, use plain "rlPhaseStart" function.
377 Reboot
379 Controlled reboot must not be executed inside of an open phase.
380 Otherwise it is possible the Overall result of the test will be
381 reported incorrectly.
382 Metric
384 rlLogMetricLow
385 Log a metric, which should be as low as possible to the journal.
387 (Example: memory consumption, run time)
388 rlLogMetricLow name value [tolerance]
390 name
392 Name of the metric. It has to be unique in a phase.
393 value
395 Value of the metric.
396 tolerance
398 It is used when comparing via rcw. It means how larger can the
399 second value be to not trigger a FAIL. Default is 0.2
400 When comparing FIRST, SECOND, then:
402 FIRST >= SECOND means PASS
404 FIRST+FIRST*tolerance >= SECOND means WARN
405 FIRST+FIRST*tolerance < SECOND means FAIL
406 Example: Simple benchmark is compared via this metric type in rcw. It
408 has a tolerance of 0.2. First run had 1 second. So:
409 For PASS, second run has to be better or equal to first.
411 So any value of second or less is a PASS.
412 For WARN, second run can be a little worse than first.
413 Tolerance is 0.2, so anything lower than 1.2 means WARN.
414 For FAIL, anything worse than 1.2 means FAIL.
415 rlLogMetricHigh
417 Log a metric, which should be as high as possible to the journal.
419 (Example: number of executions per second)
420 rlLogMetricHigh name value [tolerance]
422 name
424 Name of the metric. It has to be unique in a phase.
425 value
427 Value of the metric.
428 tolerance
430 It is used when comparing via rcw. It means how lower can the
431 second value be to not trigger a FAIL. Default is 0.2
432 When comparing FIRST, SECOND, then:
434 FIRST <= SECOND means PASS
436 FIRST+FIRST*tolerance <= SECOND means WARN
437 FIRST+FIRST*tolerance > SECOND means FAIL
438 Manual Asserts
440 rlPass
441 Manual assertion, asserts and logs PASS.
443 rlPass comment
445 comment
447 Short test summary.
448 Returns 0 and asserts PASS.
450 rlFail
452 Manual assertion, asserts and logs FAIL.
454 rlFail comment
456 comment
458 Short test summary.
459 Returns 1 and asserts FAIL.
461 Arithmetic Asserts
463 rlAssert0
464 Assertion checking for the equality of parameter to zero.
466 rlAssert0 comment value
468 comment
470 Short test summary, e.g. "Test if compilation ended successfully".
471 value
473 Integer value (usually return code of a command).
474 Returns 0 and asserts PASS when "value == 0".
476 rlAssertEquals
478 Assertion checking for the equality of two parameters.
480 rlAssertEquals comment value1 value2
482 comment
484 Short test summary, e.g. "Test if all 3 packages have been
485 downloaded".
486 value1
488 First parameter to compare, can be a number or a string
489 value2
491 Second parameter to compare, can be a number or a string
492 Returns 0 and asserts PASS when "value1 == value2".
494 rlAssertNotEquals
496 Assertion checking for the non-equality of two parameters.
498 rlAssertNotEquals comment value1 value2
500 comment
502 Short test summary, e.g. "Test if return code is not 139".
503 value1
505 First parameter to compare, can be a number or a string
506 value2
508 Second parameter to compare, can be a number or a string
509 Returns 0 and asserts PASS when "value1 != value2".
511 rlAssertGreater
513 Assertion checking whether first parameter is greater than the second
515 one.
516 rlAssertGreater comment value1 value2
518 comment
520 Short test summary, e.g. "Test whether there are running more
521 instances of program."
522 value1
524 Integer value.
525 value2
527 Integer value.
528 Returns 0 and asserts PASS when "value1 > value2".
530 rlAssertGreaterOrEqual
532 Assertion checking whether first parameter is greater or equal to the
534 second one.
535 rlAssertGreaterOrEqual comment value1 value2
537 comment
539 Short test summary (e.g. "There should present at least one...")
540 value1
542 Integer value.
543 value2
545 Integer value.
546 Returns 0 and asserts PASS when "value1 ≥= value2".
548 rlAssertLesser
550 Assertion checking whether first parameter is lesser than the second
552 one.
553 rlAssertLesser comment value1 value2
555 comment
557 Short test summary, e.g. "Test whether there are running more
558 instances of program."
559 value1
561 Integer value.
562 value2
564 Integer value.
565 Returns 0 and asserts PASS when "value1 < value2".
567 rlAssertLesserOrEqual
569 Assertion checking whether first parameter is lesser or equal to the
571 second one.
572 rlAssertLesserOrEqual comment value1 value2
574 comment
576 Short test summary (e.g. "There should present at least one...")
577 value1
579 Integer value.
580 value2
582 Integer value.
583 Returns 0 and asserts PASS when "value1 ≤= value2".
585 File Asserts
587 rlAssertExists
588 Assertion checking for the existence of a file or a directory.
590 rlAssertExists file|directory
592 file|directory
594 Path to the file or directory.
595 Returns 0 and asserts PASS when "file" exists.
597 rlAssertNotExists
599 Assertion checking for the non-existence of a file or a directory.
601 rlAssertNotExists file|directory
603 file|directory
605 Path to the file or directory.
606 Returns 0 and asserts PASS when "file" does not exist.
608 rlAssertGrep
610 Assertion checking if the file contains a pattern.
612 rlAssertGrep pattern file [options]
614 pattern
616 Regular expression to be searched for.
617 file
619 Path to the file.
620 options
622 Optional parameters to be passed to grep, default is "-q". Can be
623 used to perform case insensitive matches (-i), or using extended
624 (-E) or perl (-P) regular expressions.
625 Returns 0 and asserts PASS when "file" exists and contains given
627 "pattern".
628 rlAssertNotGrep
630 Assertion checking that the file does not contain a pattern.
632 rlAssertNotGrep pattern file [options]
634 pattern
636 Regular expression to be searched for.
637 file
639 Path to the file.
640 options
642 Optional parameters to be passed to grep, default is "-q". Can be
643 used to perform case insensitive matches (-i), or using extended
644 (-E) or perl (-P) regular expressions.
645 Returns 0 and asserts PASS when "file" exists and does not contain
647 given "pattern".
648 rlAssertDiffer
650 Assertion checking that two files differ (are not identical).
652 rlAssertDiffer file1 file2
654 file1
656 Path to first file1
657 file2
659 Path to second file
660 Returns 0 and asserts PASS when "file1" and "file2" differs.
662 rlAssertNotDiffer
664 Assertion checking that two files do not differ (are identical).
666 rlAssertNotDiffer file1 file2
668 file1
670 Path to first file1
671 file2
673 Path to second file
674 Returns 0 and asserts PASS when "file1" and "file2" do not differ.
676 Run, Watch, Report
678 rlRun
679 Run command with optional comment and make sure its exit code matches
681 expectations.
682 rlRun [-t] [-l] [-c] [-s] command [status[,status...] [comment]]
684 -t If specified, stdout and stderr of the command output will be
686 tagged with strings 'STDOUT: ' and 'STDERR: '.
687 -l If specified, output of the command (tagged, if -t was specified)
689 is logged using rlLog function. This is intended for short outputs,
690 and therefore only last 50 lines are logged this way. Longer
691 outputs should be analysed separately, or uploaded via rlFileSubmit
692 or rlBundleLogs.
693 -c Same as "-l", but only log the command output if it failed.
695 -s Store stdout and stderr to a file (mixed together, as the user
697 would see it on a terminal) and set $rlRun_LOG variable to name of
698 the file. $rlRun_LOG is now actually an array where the first index
699 holds the last reference to the file. Thus its behavior is not
700 changed if used without an index. The array is consumed by the
701 rlJournalEnd function to remove the leftover files, so no manual
702 files removal is needed anymore. Note that if you need to use such
703 a file after calling the rlJournalEnd function you need to create
704 your own copy of the respective file. When -t option is used, the
705 content of the file becomes tagged too.
706 If the -s option is not used, $rlRun_LOG is not modified and keeps
708 its content from the last "rlRun -s".
709 command
711 Command to run.
712 status
714 Expected exit code(s). Optional, default 0. If you expect more exit
715 codes, separate them with comma (e.g. "0,1" when both 0 and 1 are
716 OK and expected), or use from-to notation (i.e. "2-5" for
717 "2,3,4,5"), or combine them (e.g. "2-4,26" for "2,3,4,26").
718 comment
720 Short summary describing the action (optional, but recommended -
721 explain what you are doing here).
722 Returns the exit code of the command run. Asserts PASS when command\'s
724 exit status is in the list of expected exit codes.
725 Note:
727 • The output of rlRun is buffered when using "-t", "-l" or "-s"
729 option (they use unix pipes, which are buffered by nature). If you
730 need an unbuffered output just make sure that "expect" package is
731 installed on your system (its "unbuffer" tool will automatically be
732 used to produce unbuffered output).
733 • Be aware that there are some variables which can collide with your
735 code executed within rlRun. You should avoid using
736 __INTERNAL_rlRun_* variables.
737 • When any of "-t" "-l", "-c", or "-s" option is used, special file
739 descriptors 111 and 112 are used to avoid the issue with incomplete
740 log file, bz1361246. As there might be an indefinite loop, there's
741 a timeout of two minutes implemented as a fix for bz1416796. Also
742 an error message is issued to signal the possibility of running
743 subprocess which keeps the file descriptors open.
744 Do not use these options if you expect process forking and
746 continuouse run. Try your own apropriate solution instead.
747 Warning: using "unbuffer" tool is now disabled because of bug 547686.
749 rlWatchdog
751 Run "command". If it does not finish in specified time, then kill it
753 using "signal". Note that the command is executed in a sub-shell so
754 modified environment (e.g. set variables) is not relfected in the test
755 environment.
756 rlWatchdog command timeout [signal] [callback]
758 command
760 Command to run.
761 timeout
763 Timeout to wait, in seconds.
764 signal
766 Signal to use (optional, default KILL).
767 callback
769 Callback function to be called before the signal is send (optional,
770 none by default). The callback function will have one argument
771 available -- PGID of the process group.
772 Returns 0 if the command ends normally, without need to be killed.
774 rlReport
776 Report test result to the test harness. The command to be used for
778 reporting is set by the respective plugin. You can also use the
779 $BEAKERLIB_COMMAND_REPORT_RESULT variable to use your custom command.
780 rlReport name result [score] [log]
782 name
784 Name of the test result.
785 result
787 Result (one of PASS, WARN, FAIL). If called with something else,
788 will use WARN.
789 score
791 Test score (optional).
792 log Optional log file to be submitted instead of default "OUTPUTFILE".
794 rlCmpVersion
796 Compare two given versions composed by numbers and letters divided by
798 dot (.), underscore (_), or dash (-).
799 rlCmpVersion ver1 ver2
801 If ver1 = ver2, sign '=' is printed to stdout and 0 is returned. If
803 ver1 > ver2, sign '>' is printed to stdout and 1 is returned. If ver1
804 < ver2, sign '<' is printed to stdout and 2 is returned.
805 rlTestVersion
807 Test releation between two given versions based on given operator.
809 rlTestVersion ver1 op ver2
811 op Operator defining the logical expression. It can be '=', '==',
813 '!=', '<', '<=', '=<', '>', '>=', or '=>'.
814 Returns 0 if the expresison ver1 op ver2 is true; 1 if the expression
816 is false and 2 if something went wrong.
817 Release Info
819 rlIsRHEL
820 rlIsRHEL [VERSION_SPEC]...
822 VERSION_SPEC
824 Argument specifies version of particular RHEL distribution, eg. 8,
825 8.4 ">8.4".
826 For more details see description of "rlIsOSVersion".
828 Returns 0 when we're running on RHEL. With given version specification
830 in arguments returns 0 if the particular RHEL version is running.
831 Prototype:
833 rlIsRHEL
835 Returns 0 if we are running on RHEL.
837 rlIsRHEL 7 '>=8.5'
839 Returns 0 if we are running any RHEL 7 or RHEL 8.5 and higher.
841 rlIsFedora
843 rlIsFedora [VERSION_SPEC]...
845 VERSION_SPEC
847 Argument specifies version of particular Fedora distribution, eg.
848 30, ">30".
849 For more details see description of "rlIsOSVersion".
851 Returns 0 when we're running on Fedora. With given version
853 specification in arguments returns 0 if the particular Fedora version
854 is running.
855 Prototype:
857 rlIsFedora
859 Returns 0 if we are running on Fedora.
861 rlIsFedora 30 32
863 Returns 0 if we are running Fedora 30 or 32.
865 rlIsCentOS
867 rlIsCentOS [VERSION_SPEC]...
869 VERSION_SPEC
871 Argument specifies version of particular CentOS distribution, eg.
872 7, ">7".
873 For more details see description of "rlIsOSVersion".
875 Returns 0 when we're running on CentOS. With given version
877 specification in arguments returns 0 if the particular CentOS version
878 is running.
879 Prototype:
881 rlIsCentOS
883 Returns 0 if we are running on CentOS.
885 rlIsCentOS 7.1 6
887 Returns 0 if we are running CentOS 7.1 or any CentOS 6.
889 rlIsOS
891 rlIsOS ID
893 ID Argument is based on contents of /etc/os-release. Possible options
895 of ID are e.g. fedora, rhel, centos, ol.
896 Returns 0 when we're running on system with respective ID. Returns 1
898 when parameter does not match with ID in os-release. Returns 2 when
899 there is no ID defined. Returns 3 when no argument is given.
900 Prototype:
902 rlIsOS rhel
904 Returns 0 if we are running on RHEL.
906 rlIsOSLike
908 rlIsOSLike ID_LIKE
910 ID_LIKE
912 Argument is based on contents of /etc/os-release. Possible options
913 of ID_LIKE are e.g. fedora, rhel.
914 Returns 0 when we're running on system with requested ID_LIKE. Returns
916 1 when parameter does not match with ID nor ID_LIKE in os-release.
917 Returns 2 when there is no ID or ID_LIKE defined. Returns 3 when no
918 argument is given.
919 Prototype:
921 rlIsOSLike rhel
923 Returns 0 if we are running on RHEL, CentOS, Rocky Linux, etc..
925 rlIsOSLike fedora
927 Returns 0 if we are running on Fedora, RHEL, CentOS, Oracle Linux, etc..
929 rlIsOSVersion
931 rlIsOsVersion VERSION_SPEC...
933 VERSION_SPEC
935 Parameter is based on VERSION_ID in /etc/os-release. It consists
936 of either "major" or "major"."minor" refering to a particular
937 release.
938 It accepts multiple arguments separated by space (8.1 8.2 8.3 9).
940 To specify a group of distributions optional operator can be passed
942 in argument together with the version number as one string
943 ('>8.5'). Operator can be '<', '<=', '=<', '=', '>', '>=' matching
944 whether the currently installed version is lesser, lesser or equal,
945 equal, equal or greater, greater than the version number supplied
946 as second half of the argument.
947 Note that when using >/< operators you have to either put the
949 argument in quotes or escape the operators to avoid them being
950 interpreted as bash redirection operator.
951 Returns 0 when we're running distribution of the particular version
953 requested by the argument.
954 It usually follows after "rlIsOS" and "rlIsOSLike".
956 Be cautious when using together with "rlIsOSLike" as different
958 distributions may use different versioning schema.
959 Prototype:
961 rlIsOSVersion 6 7 9
963 Returns 0 if we are running distribution with VERSION_ID 6, 7 or 9.
965 rlIsOSVersion 7.8 8
967 Returns 0 if we are running distribution 7.8 or any 8.
969 rlIsOSVersion ">=7.5" or rlIsOSVersion \>=7.5
971 Returns 0 if we are running distribution 7.5 or higher (both minors or majors).
973 Note:
975 rlIsOSVersion '<7.5' || rlIsOSVersion '<8.5'
977 would also cover 7.9 as it is less than 8.5, which is not what you want.
979 So if you want to construct a condition for a distribution <7.5 within the major 7 or
980 a distribution <8.5 within the major 8 you actually need to use following construct:
981 rlIsOSVersion 7 && rlIsOSVersion '<7.5' || rlIsOSVersion 8 && rlIsOSVersion '<8.5'
983 This returns 0 when running distribution less than 7.5 and less then 8.5, but not 7.9 (nor 6.9).
985 rlIsRHELLike
987 rlIsRHELLike [VERSION_SPEC]...
989 VERSION_SPEC
991 Argument specifies version of particular RHEL distribution, eg. 8,
992 8.4 ">8.4".
993 For more details see description of "rlIsOSVersion".
995 Returns 0 when we're running on RHEL-like distribution. These are
997 considered to be RHEL, CentOS, Rocky Linux, etc.. With given version
998 specification in arguments returns 0 if the particular version of RHEL-
999 like distribution is running.
1000 Prototype:
1002 rlIsRHELLike
1004 Returns 0 if we are running on RHEL-like system.
1006 rlIsRHELLike ">=6"
1008 Returns 0 if we are running on RHEL-like distribution of version 6.0 or higher.
1010 Rpm Handling
1012 rlCheckRpm
1013 Check whether a package is installed.
1015 rlCheckRpm name [version] [release] [arch]
1017 name
1019 Package name like "kernel"
1020 version
1022 Package version like 2.6.25.6
1023 release
1025 Package release like "55.fc9"
1026 arch
1028 Package architucture like "i386"
1029 Returns 0 if the specified package is installed.
1031 rlAssertRpm
1033 Assertion making sure that a package is installed.
1035 rlAssertRpm name [version] [release] [arch]>
1037 rlAssertRpm --all
1038 name
1040 Package name like "kernel"
1041 version
1043 Package version like 2.6.25.6
1044 release
1046 Package release like "55.fc9"
1047 arch
1049 Package architucture like "i386"
1050 --all
1052 Assert all packages listed in the $PACKAGES $REQUIRES and
1053 $COLLECTIONS environment variables.
1054 Returns 0 and asserts PASS if the specified package is installed.
1056 rlAssertNotRpm
1058 Assertion making sure that a package is not installed. This is just
1060 inverse of "rlAssertRpm".
1061 rlAssertNotRpm name [version] [release] [arch]>
1063 name
1065 Package name like "kernel"
1066 version
1068 Package version like 2.6.25.6
1069 release
1071 Package release like "55.fc9"
1072 arch
1074 Package architucture like "i386"
1075 Returns 0 and asserts PASS if the specified package is not installed.
1077 Example
1079 Function "rlAssertRpm" is useful especially in prepare phase where it
1081 causes abort if a package is missing, while "rlCheckRpm" is handy when
1082 doing something like:
1083 if ! rlCheckRpm package; then
1085 yum install package
1086 rlAssertRpm package
1087 fi
1088 rlAssertBinaryOrigin
1090 Assertion making sure that given binary is owned by (one of) the given
1092 package(s).
1093 rlAssertBinaryOrigin binary package [package2 [...]]
1095 PACKAGES=... rlAssertBinaryOrigin binary
1096 binary
1098 Binary name like "ksh" or "/bin/ksh"
1099 package
1101 List of packages like "ksh mksh". The parameter is optional. If
1102 missing, contents of environment variable $PACKAGES are taken into
1103 account.
1104 Returns 0 and asserts PASS if the specified binary belongs to (one of)
1106 the given package(s). Returns 1 and asserts FAIL if the specified
1107 binary does not belong to (any of) the given package(s). Returns 2 and
1108 asserts FAIL if the specified binary is not found. Returns 3 and
1109 asserts FAIL if no packages are given. Returns 100 and asserts FAIL if
1110 invoked with no parameters.
1111 Example
1113 Function "rlAssertBinaryOrigin" is useful especially in prepare phase
1115 where it causes abort if a binary is missing or is owned by different
1116 package:
1117 PACKAGES=mksh rlAssertBinaryOrigin ksh
1119 or
1120 rlAssertBinaryOrigin ksh mksh
1121 Returns true if ksh is owned by the mksh package (in this case:
1123 /bin/ksh is a symlink pointing to /bin/mksh).
1124 rlGetMakefileRequires
1126 Prints space separated list of requirements defined in Makefile using
1128 'Requires' attribute.
1129 Return 0 if success.
1131 rlGetYAMLdeps
1133 Prints space separated list of requirements defined in metadata.yaml
1135 using 'require' and / or 'recommend' attribute.
1136 Full fmf ids and library references are to be ignored.
1138 rlGetYAMLdeps DEP_TYPE [array_var_name]
1140 DEP_TYPE
1142 Dependency type defined as a regexp. Expected values are 'require',
1143 'recommend', or 'require|recommend'. The matching attribute values
1144 are then processed. Defaults to 'require'.
1145 array_var_name
1147 Name of the variable to put the output to in a form of an array.
1148 This can hold also dependencies with specific version. If used,
1149 the output to stdout is suppressed.
1150 Return 0 if success.
1152 rlCheckRequirements
1154 Check that all given requirements are covered eigther by installed
1156 package or by binary available in PATHs or by some package's provides.
1157 rlRun "rlCheckRequirements REQ..."
1159 REQ Requirement to be checked. It can be package name, provides string
1161 or binary name. Moreover, the requirement can be written the same
1162 way as the Require in the spec file, including the version
1163 specification, e.g. "bash >= 4.4". The comparsion operator may be
1164 any of supported by rlTestVersion(), see its manual.
1165 Returns number of unsatisfied requirements.
1167 rlCheckMakefileRequires
1169 Check presence of required packages / binaries defined in metadata.yaml
1171 provided by "tmt" or Makefile of the test.
1172 Also check presence of recommended packages / binaries defined in
1174 metadata.yaml provided by "tmt". These however do not participate on
1175 the return code, these are just informative.
1176 Example
1178 rlRun "rlCheckMakefileRequires"
1180 Return 255 if requirements could not be retrieved, 0 if all
1182 requirements are satisfied or number of unsatisfied requirements.
1183 rlGetRequired =head3 rlGetRecommended
1185 Get a list of required or recommended packages / binaries defined in
1187 metadata.yaml provided by "tmt" or in a Makefile of the test.
1188 rlGetRequired [ARRAY_VAR_NAME]
1190 rlGetRecommended [ARRAY_VAR_NAME]
1191 ARRAY_VAR_NAME
1193 If provided the variable is populated as an array with the
1194 respective dependencies. Otherwise the dependencies are printed out
1195 to the STDOUT.
1196 Return 255 if requirements could not be retrieved, 0 otherwise.
1198 rlCheckRequired =head3 rlCheckRecommended =head3 rlCheckDependencies
1200 Check presence of required, recommended or both packages / binaries
1202 defined in metadata.yaml provided by "tmt" or in a Makefile of the
1203 test.
1204 Example
1206 rlRun "rlCheckRequired"
1208 rlRun "rlCheckRecommended"
1209 rlRun "rlCheckDependencies"
1210 Return 255 if requirements could not be retrieved, 0 if all
1212 requirements are satisfied or number of unsatisfied requirements.
1213 rlAssertRequired
1215 Ensures that all required packages provided in either metadata.yaml or
1217 Makefile are installed.
1218 rlAssertRequired
1220 Prints out a verbose list of installed/missing packages during
1222 operation.
1223 Returns 0 if all required packages are installed, 1 if one or more
1225 packages are missing or if no Makefile is present.
1226 Getting RPMs
1228 Download methods
1229 Functions handling rpm downloading/installing can use more methods for
1231 actual download of the rpm.
1232 Currently there are two download methonds available:
1234 direct
1236 Use use dirct download from build system (brew).
1237 yum Use yumdownloader or dnf download.
1239 The methods and their order are defined by
1241 BEAKERLIB_RPM_DOWNLOAD_METHODS variable as space separated list. By
1242 default it is 'direct yum'. This can be overridden by user. There may
1243 be done also additions or changes to the original value, e.g.
1244 BEAKERLIB_RPM_DOWNLOAD_METHODS='yum
1245 ${BEAKERLIB_RPM_DOWNLOAD_METHODS/yum/}'
1246 Beakerlib is prepared for more Koji-based sources of packages while
1250 usigng direct download method. By default packages are fetched from
1251 Koji, particularly from https://kojipkgs.fedoraproject.org/packages.
1252 rlRpmInstall
1254 Try to install specified package from local Red Hat sources.
1256 rlRpmInstall [--quiet] package version release arch
1258 --quiet
1260 Make the download and the install process be quiet.
1261 package
1263 Package name like "kernel"
1264 version
1266 Package version like 2.6.25.6
1267 release
1269 Package release like "55.fc9"
1270 arch
1272 Package arch like "i386"
1273 Returns 0 if specified package was installed successfully.
1275 rlRpmDownload
1277 Try to download specified package.
1279 rlRpmDownload [--quiet] {package version release arch|N-V-R.A}
1281 rlRpmDownload [--quiet] --source {package version release|N-V-R}
1282 --quiet
1284 Make the download process be quiet.
1285 package
1287 Package name like "kernel"
1288 version
1290 Package version like 2.6.25.6
1291 release
1293 Package release like "55.fc9"
1294 arch
1296 Package arch like "i386"
1297 Returns 0 if specified package was downloaded successfully.
1299 rlFetchSrcForInstalled
1301 Tries various ways to download source rpm for specified installed rpm.
1303 rlFetchSrcForInstalled [--quiet] package
1305 --quiet
1307 Make the download process be quiet.
1308 package
1310 Installed package name like "kernel". It accepts in-direct names.
1311 E.g. for the package name "krb5-libs" the function will download
1312 the "krb5" source rpm.
1313 Returns 0 if the source package was successfully downloaded.
1315 Mounting
1317 rlMount
1318 Create mount point (if neccessary) and mount a NFS share.
1320 rlMount [-o MOUNT_OPTS] server share mountpoint
1322 server
1324 NFS server hostname.
1325 share
1327 Shared directory name.
1328 mountpoint
1330 Local mount point.
1331 MOUNT_OPTS
1333 Mount options.
1334 Returns 0 if mounting the share was successful.
1336 rlCheckMount
1338 Check either if a directory is a mountpoint, if it is a mountpoint to a
1340 specific server, or if it is a mountpoint to a specific export on a
1341 specific server and if it uses specific mount options.
1342 rlCheckMount [-o MOUNT_OPTS] mountpoint
1344 rlCheckMount [-o MOUNT_OPTS] server mountpoint
1345 rlCheckMount [-o MOUNT_OPTS] server share mountpoint
1346 mountpoint
1348 Local mount point.
1349 server
1351 NFS server hostname
1352 share
1354 Shared directory name
1355 MOUNT_OPTS
1357 Mount options to check (comma separated list)
1358 With one parameter, returns 0 when specified directory exists and is a
1360 mountpoint. With two parameters, returns 0 when specific directory
1361 exists, is a mountpoint and an export from specific server is mounted
1362 there. With three parameters, returns 0 if a specific shared directory
1363 is mounted on a given server on a given mountpoint
1364 If the -o option is provided, returns 0 if the mountpoint uses all the
1366 given options, 2 otherwise.
1367 rlAssertMount
1369 Assertion making sure that given directory is a mount point, if it is a
1371 mountpoint to a specific server, or if it is a mountpoint to a specific
1372 export on a specific server and if it uses specific mount options.
1373 rlAssertMount [-o MOUNT_OPTS] mountpoint
1375 rlAssertMount [-o MOUNT_OPTS] server mountpoint
1376 rlAssertMount [-o MOUNT_OPTS] server share mountpoint
1377 mountpoint
1379 Local mount point.
1380 server
1382 NFS server hostname
1383 share
1385 Shared directory name
1386 MOUNT_OPTS
1388 Mount options to check (comma separated list)
1389 With one parameter, returns 0 when specified directory exists and is a
1391 mountpoint. With two parameters, returns 0 when specific directory
1392 exists, is a mountpoint and an export from specific server is mounted
1393 there. With three parameters, returns 0 if a specific shared directory
1394 is mounted on a given server on a given mountpoint. Asserts PASS when
1395 the condition is true.
1396 If the -o option is provided, asserts PASS if the above conditions are
1398 met and the mountpoint uses all the given options.
1399 rlHash, rlUnhash
1401 Hashes/Unhashes given string and prints the result to stdout.
1403 rlHash [--decode] [--algorithm HASH_ALG] --stdin|STRING
1405 rlUnhash [--algorithm HASH_ALG] --stdin|STRING
1406 --decode
1408 Unhash given string.
1409 --algorithm
1411 Use given hash algorithm. Currently supported algorithms:
1412 base64
1413 base64_ - this is standard base64 where '=' is replaced by '_'
1414 hex
1415 Defaults to hex. Default algorithm can be override using global
1417 variable rlHashAlgorithm.
1418 --stdin
1420 Get the string from stdin.
1421 STRING
1423 String to be hashed/unhashed.
1424 Returns 0 if success.
1426 Backup and Restore
1428 rlFileBackup
1429 Create a backup of files or directories (recursive). Can be used
1431 multiple times to add more files to backup. Backing up an already
1432 backed up file overwrites the original backup.
1433 rlFileBackup [--clean] [--namespace name] [--missing-ok|--no-missing-ok] file [file...]
1435 You can use "rlRun" for asserting the result but keep in mind meaning
1437 of exit codes, especialy exit code 8, if using without --clean option.
1438 --clean
1440 If this option is provided (has to be the first option of the
1441 command), then file/dir backed up using this command (provided in
1442 next options) will be (recursively) removed before we restore it.
1443 This option implies --missing-ok, which can be overridden by
1444 --no-missing-ok.
1445 --namespace name
1447 Specifies the namespace to use. Namespaces can be used to separate
1448 backups and their restoration.
1449 --missing-ok
1451 Do not raise an error in case of missing file to backup.
1452 --no-missing-ok
1454 Do raise an error in case of missing file to backup. This is
1455 useful with --clean. This behaviour can be globally set by global
1456 variable BEAKERLIB_FILEBACKUP_MISSING_OK=false.
1457 file
1459 Files and/or directories to be backed up.
1460 Returns 0 if the backup was successful. Returns 1 if parsing of
1462 parameters was not successful. Returns 2 if no files specification was
1463 provided. Returns 3 if BEAKERLIB_DIR variable is not set, e.g.
1464 rlJournalStart was not executed. Returns 4 if creating of main backup
1465 destination directories was not successful. Returns 5 if creating of
1466 file specific backup destination directories was not successful.
1467 Returns 6 if the copy of backed up files was not successful. Returns 7
1468 if attributes of backed up files were not successfuly copied. Returns
1469 8 if backed up files do not exist. This can be suppressed based on
1470 other options.
1471 Example with --clean:
1473 touch cleandir/aaa
1475 rlRun "rlFileBackup --clean cleandir/"
1476 touch cleandir/bbb
1477 ls cleandir/
1478 aaa bbb
1479 rlRun "rlFileRestore"
1480 ls cleandir/
1481 aaa
1482 rlFileRestore
1484 Restore backed up files to their original location. "rlFileRestore"
1486 does not remove new files appearing after backup has been made. If you
1487 don't want to leave anything behind just remove the whole original tree
1488 before running "rlFileRestore", or see "--clean" option of
1489 "rlFileBackup".
1490 rlFileRestore [--namespace name]
1492 You can use "rlRun" for asserting the result.
1494 --namespace name
1496 Specifies the namespace to use. Namespaces can be used to separate
1497 backups and their restoration.
1498 Returns 0 if backup dir is found and files are restored successfully.
1500 Return code bits meaning:
1502 XXXXX
1504 |||||
1505 ||||\_ error parsing parameters
1506 |||\__ could not find backup directory
1507 ||\___ files cleanup failed
1508 |\____ files restore failed
1509 \_____ no files were restored nor cleaned
1510 Services
1512 Following routines implement comfortable way how to start/stop system
1513 services with the possibility to restore them to their original state
1514 after testing.
1515 rlServiceStart
1517 Make sure the given "service" is running with fresh configuration.
1519 (Start it if it is stopped and restart if it is already running.) In
1520 addition, when called for the first time, the current state is saved so
1521 that the "service" can be restored to its original state when testing
1522 is finished, see "rlServiceRestore".
1523 rlServiceStart service [service...]
1525 service
1527 Name of the service(s) to start.
1528 Returns number of services which failed to start/restart; thus zero is
1530 returned when everything is OK.
1531 rlServiceStop
1533 Make sure the given "service" is stopped. Stop it if it is running and
1535 do nothing when it is already stopped. In addition, when called for the
1536 first time, the current state is saved so that the "service" can be
1537 restored to its original state when testing is finished, see
1538 "rlServiceRestore".
1539 rlServiceStop service [service...]
1541 service
1543 Name of the service(s) to stop.
1544 Returns number of services which failed to become stopped; thus zero is
1546 returned when everything is OK.
1547 rlServiceRestore
1549 Restore given "service" into its original state (before the first
1551 "rlServiceStart" or "rlServiceStop" was called). If "rlServiceStart"
1552 was called on already running "service", "rlServiceRestore" will
1553 restart the "service" when restoring its state.
1554 rlServiceRestore [service...]
1556 service
1558 Name of the service(s) to restore to original state. All services
1559 will be restored in reverse order if no service name is given.
1560 Returns number of services which failed to get back to their original
1562 state; thus zero is returned when everything is OK.
1563 rlServiceStatus
1565 Print status (output of `service SERVICE status` or `systemctl status
1567 SERVICE`) of given "SERVICE".
1568 rlServiceStatus SERVICE [SERVICE...]
1570 SERVICE
1572 The service to get the status of.
1573 Returns service status return code of the last provided SERVICE.
1575 rlServiceEnable
1577 Enables selected services if needed, or does nothing if already
1579 enabled. In addition, when called for the first time, the current
1580 state is saved so that the "service" can be restored to its original
1581 state when testing is finished, see "rlServiceRestore".
1582 rlServiceEnable service [service...]
1584 service
1586 Name of the service(s) to enable.
1587 Returns number of services which failed enablement; thus zero is
1589 returned when everything is OK.
1590 rlServiceDisable
1592 Disables selected services if needed, or does nothing if already
1594 disabled. In addition, when called for the first time, the current
1595 state is saved so that the "service" can be restored to its original
1596 state when testing is finished, see "rlServiceRestore".
1597 rlServiceDisable service [service...]
1599 service
1601 Name of the service(s) to disable.
1602 Returns number of services which failed disablement; thus zero is
1604 returned when everything is OK.
1605 Sockets
1607 Following routines implement comfortable way how to start/stop system
1608 sockets with the possibility to restore them to their original state
1609 after testing.
1610 rlSocketStart
1612 Make sure the given "socket" is running. (Start it if stopped, leave it
1614 if already running.) In addition, when called for the first time, the
1615 current state is saved so that the "socket" can be restored to its
1616 original state when testing is finished, see "rlSocketRestore".
1617 rlSocketStart socket [socket...]
1619 socket
1621 Name of the socket(s) to start.
1622 Returns number of sockets which failed to start/restart; thus zero is
1624 returned when everything is OK.
1625 rlSocketStop
1627 Make sure the given "socket" is stopped. Stop it if it is running and
1629 do nothing when it is already stopped. In addition, when called for the
1630 first time, the current state is saved so that the "socket" can be
1631 restored to its original state when testing is finished, see
1632 "rlSocketRestore".
1633 rlSocketStop socket [socket...]
1635 socket
1637 Name of the socket(s) to stop.
1638 Returns number of sockets which failed to become stopped; thus zero is
1640 returned when everything is OK.
1641 rlSocketRestore
1643 Restore given "socket" into its original state (before the first
1645 "rlSocketStart" or "rlSocketStop" was called).
1646 Warning !!! Xinetd process [even though it might have been used] is
1648 NOT restored. It is recommended to call rlServiceRestore xinetd as
1649 well.
1650 rlSocketRestore socket [socket...]
1652 socket
1654 Name of the socket(s) to restore to original state.
1655 Returns number of sockets which failed to get back to their original
1657 state; thus zero is returned when everything is OK.
1658 Cleanup management
1660 Cleanup management works with a so-called cleanup buffer, which is a
1661 temporary representation of what should be run at cleanup time, and a
1662 final cleanup script (executable), which is generated from this buffer
1663 and wraps it using BeakerLib essentials (journal initialization,
1664 cleanup phase, ...). The cleanup script must always be updated on an
1665 atomic basis (filesystem-wise) to allow an asynchronous execution by a
1666 third party (ie. test watcher).
1667 The test watcher usage is mandatory for the cleanup management system
1669 to work properly as it is the test watcher that executes the actual
1670 cleanup script. Limited, catastrophe-avoiding mechanism is in place
1671 even when the test is not run in test watcher, but that should be seen
1672 as a backup and such situation is to be avoided whenever possible.
1673 The cleanup script shares all environment (variables, exported or not,
1675 and functions) with the test itself - the cleanup append/prepend
1676 functions "sample" or "snapshot" the environment at the time of their
1677 call, IOW any changes to the test environment are synchronized to the
1678 cleanup script only upon calling append/prepend. When the
1679 append/prepend functions are called within a function which has local
1680 variables, these will appear as global in the cleanup.
1681 While the cleanup script receives $PWD from the test, its working dir
1683 is set to the initial test execution dir even if $PWD contains
1684 something else. It is impossible to use relative paths inside cleanup
1685 reliably - certain parts of the cleanup might have been added under
1686 different current directories (CWDs). Therefore always use absolute
1687 paths in append/prepend cleanup or make sure you never 'cd' elsewhere
1688 (ie. to a TmpDir).
1689 rlCleanupAppend
1691 Appends a string to the cleanup buffer and recreates the cleanup
1693 script.
1694 rlCleanupAppend string
1696 Returns 0 if the operation was successful, 1 otherwise.
1698 rlCleanupPrepend
1700 Prepends a string to the cleanup buffer and recreates the cleanup
1702 script.
1703 rlCleanupPrepend string
1705 Returns 0 if the operation was successful, 1 otherwise.
1707 Time Performance
1709 rlPerfTime_RunsInTime
1710 Measures, how many runs of some commands can be done in specified time.
1712 This approach is suitable for short-time running tasks (up to few
1713 seconds), where averaging few runs is not precise. This is done several
1714 times, and the final result is the average of all runs. It prints the
1715 number on stdout, so it has to be captured.
1716 rlPerfTime_RunsInTime command [time] [runs]
1718 command
1720 Command to run.
1721 time
1723 Time in seconds (optional, default=30).
1724 runs
1726 Number of averaged runs (optional, default=3).
1727 rlPerfTime_AvgFromRuns
1729 Measures the average time of running some task. This approach is
1731 suitable for long-time running tasks (tens of seconds and more), where
1732 it is precise enough. Measured runs can be preceded by dry run, which
1733 is not measured and it's purpose is to warm up various caches. It
1734 prints the number on stdout, so it has to be captured. Or, result is
1735 then stored in special rl_retval variable.
1736 rlPerfTime_AvgFromRuns command [count] [warmup]
1738 command
1740 Command to run.
1741 count
1743 Times to run (optional, default=3).
1744 warmup
1746 Warm-up run, run if this option is not "warmup" (optional,
1747 default="warmup")
1748 Analyze
1750 rlDejaSum
1751 TODO description
1753 rlDejaSum par1 par2
1755 par1
1757 TODO description
1758 par2
1760 TODO description
1761 Return 0 if... TODO
1763 rlImport
1765 Imports code provided by one or more libraries into the test namespace.
1767 The library search mechanism is based on Beaker test hierarchy system,
1768 i.e.:
1769 /component/type/test-name/test-file
1771 When test-file calls rlImport with 'foo/bar' parameter, the libraries
1773 are searched in following locations: these are the possible path
1774 prefixes
1775 - colon-separated paths from $BEAKERLIB_LIBRARY_PATH
1777 - /mnt/tests
1778 - /usr/share/beakerlib-libraries
1779 the next component of the path is one of the following:
1781 - /foo/Library/bar
1783 - /foo/bar
1784 - /libs/foo/bar
1785 - /*/foo/Library/bar
1786 - /*/foo/bar
1787 - /libs/*/foo/Library/bar
1788 - /libs/*/foo/bar
1789 the directory path is then constructed as prefix/path/lib.sh If the
1791 library is still not found an upwards directory traversal is used, and
1792 a check for presence of the library in the above mentioned possible
1793 paths is to be performed. This means this function needs to be called
1794 from the test hierarchy, not e.g. the /tmp directory.
1795 Once library is found, it is sourced and a verifier function is called.
1797 The verifier function is cunstructed by composing the library prefix
1798 and LibraryLoaded. Library prefix must be defined in the library
1799 itself. It should be part of lib.sh header in format: '# library-
1800 prefix = <PREFIX>'. If the verifier passes the library is ready to
1801 use. Also variable <PREFIX>LibraryDir is created and it points to the
1802 library folder.
1803 Usage:
1805 rlImport --all
1807 rlImport LIBRARY [LIBRARY2...]
1808 --all
1810 Read $BEAKERLIB_DIR/metadata.yaml or ./Makefile, pickup the library
1811 requirements and import them all.
1812 LIBRARY
1814 Must have '[component/]path' or '.' format. Identifies the library
1815 to import. The dot (.) is a special case where the lib.sh from the
1816 current directory is used.
1817 Returns 0 if the import of all libraries was successful. Returns non-
1819 zero if one or more library failed to import.
1820 Process Synchronisation
1822 rlWaitForCmd
1823 Pauses script execution until command exit status is the expeced value.
1825 Logs a WARNING and returns 1 if the command didn't exit successfully
1826 before timeout elapsed or a maximum number of invocations has been
1827 reached.
1828 rlWaitForCmd command [-p PID] [-t time] [-m count] [-d delay] [-r retval]
1830 command
1832 Command that will be executed until its return code is equal 0 or
1833 value speciefied as option to '-r'.
1834 -t time
1836 Timeout in seconds, default=120. If the command doesn't return 0
1837 before time elapses, the command will be killed.
1838 -p PID
1840 PID of the process to check before running command. If the process
1841 exits before the socket is opened, the command will log a WARNING.
1842 -m count
1844 Maximum number of 'command' executions before continuing anyway.
1845 Default is infite. Returns 1 if the maximum was reached.
1846 -d delay
1848 Delay between 'command' invocations. Default 1.
1849 -r retval
1851 Expected return value of command. Default 0.
1852 rlWaitForFile
1854 Pauses script execution until specified file or directory starts
1856 existing. Returns 0 if file started existing, 1 if timeout was reached
1857 or PID exited. Return code is greater than 1 in case of error.
1858 rlWaitForFile path [-p PID] [-t time] [-d delay]
1860 path
1862 Path to file that should start existing.
1863 -t time
1865 Timeout in seconds (optional, default=120). If the file isn't
1866 opened before the time elapses the command returns 1.
1867 -p PID
1869 PID of the process that should also be running. If the process
1870 exits before the file is created, the command returns with status
1871 code of 1.
1872 -d delay
1874 Delay between subsequent checks for existence of file. Default 1.
1875 rlWaitForSocket
1877 Pauses script execution until local socket starts listening. Returns 0
1879 if socket started listening, 1 if timeout was reached or PID exited.
1880 Return code is greater than 1 in case of error.
1881 rlWaitForSocket {port|path} [-p PID] [-t time] [-d delay] [--close] [--remote]
1883 port|path
1885 Network port to wait for opening or a path to UNIX socket. Regular
1886 expressions are also supported.
1887 -t time
1889 Timeout in seconds (optional, default=120). If the socket isn't
1890 opened before the time elapses the command returns 1.
1891 -p PID
1893 PID of the process that should also be running. If the process
1894 exits before the socket is opened, the command returns with status
1895 code of 1.
1896 -d delay
1898 Delay between subsequent checks for availability of socket. Default
1899 1.
1900 --close
1902 Wait for the socket to stop listening.
1903 --remote
1905 Wait for the remote socket to start listening instead of local one.
1906 rlWait
1908 Wrapper around bash builtin 'wait' command. See bash_builtins(1) man
1910 page. Kills the process and all its children if the timeout elapses.
1911 rlWaitFor [n ...] [-s SIGNAL] [-t time]
1913 n List of PIDs to wait for. They need to be background tasks of
1915 current shell. See bash_builtins(1) section for 'wait' command.
1916 -t time
1918 Timeout in seconds (optional, default=30). If the wait isn't
1919 successful before the time elapses then all specified tasks are
1920 killed.
1921 -s SIGNAL
1923 Signal used to kill the process, optional SIGTERM by default.
1924 Virtual X Server
1926 Functions providing simple way how to start and stop virtual X server.
1927 rlVirtualXStart
1929 Start a virtual X server on a first free display. Tries only first N
1931 displays, so you can run out of them.
1932 rlVirtualXStart name [N]
1934 name
1936 String identifying the X server.
1937 N Maximum number of displays to try. Defaults to 3.
1939 Returns 0 when the server is started successfully.
1941 rlVirtualXGetDisplay
1943 Get the DISPLAY variable for specified virtual X server.
1945 rlVirtualXGetDisplay name
1947 name
1949 String identifying the X server.
1950 Displays the number of display where specified virtual X server is
1952 running to standard output. Returns 0 on success.
1953 rlVirtualXStop
1955 Kill the specified X server.
1957 rlVirtualXStop name
1959 name
1961 String identifying the X server.
1962 Returns 0 when the server is stopped successfully.
1964 Example
1966 Below is a simple example of usage. Note that a lot of usefull
1968 debugging information is reported on the DEBUG level, so you can run
1969 your test with "DEBUG=1 make run" to get them.
1970 rlVirtualXStart $TEST
1972 rlAssert0 "Virtual X server started" $?
1973 export DISPLAY="$( rlVirtualXGetDisplay $TEST )"
1974 # ...your test which needs X...
1975 rlVirtualXStop $TEST
1976 rlAssert0 "Virtual X server killed" $?
1977 These are "Requires" lines for your scripts - note different package
1979 names for different RHEL versions:
1980 @echo "Requires: xorg-x11-server-Xvfb" >> $(METADATA) # RHEL-5
1982 @echo "Requires: xorg-x11-Xvfb" >> $(METADATA) # RHEL-4
1983 @echo "Requires: XFree86-Xvfb" >> $(METADATA) # RHEL-3
1984 rlYash_parse
1986 Parse yaml data to the associative array.
1988 rlYash_parse VAR_NAME YAML_DATA
1990 VAR_NAME
1992 Name of the variable to which the yaml structure will be saved.
1993 Note that the variable needs to be predeclared as an associative
1995 array.
1996 YAML_DATA
1998 The actual yaml data.
1999 Beakerlib Profiling
2001 Enable profiling
2002 Set environment variable BEAKERLIB_PROFILING=1
2004 BEAKERLIB_PROFILING=1 make run
2006 A file /dev/shm/beakerlib_profile will be created for later processing.
2008 Process the profile
2010 /usr/share/beakerlib/profiling.sh process > profile.csv
2012
2014 Location of test results related output files can be configured by
2015 setting BEAKERLIB_DIR variable before running the test. If it is not
2016 set, temporary directory is created.
2017 journal.txt
2019 Journal in human readable form.
2020 journal.xml
2022 Journal in XML format, requires python. This dependency can be avoided
2023 if the test is run with variable BEAKERLIB_JOURNAL set to 0 in which
2024 case journal.xml is not created.
2025 XSLT
2027 XML journal can be transformed through XSLT template. Which template is
2029 used is configurable by setting BEAKERLIB_JOURNAL variable. Value can
2030 be either filename in which case beakerlib will try to use
2031 $INSTALL_DIR/xslt-template/$filename (e.g.:
2032 /usr/share/beakerlib/xstl-templates/xunit.xsl) or it can be path to a
2033 template anywhere on the system.
2034 TestResults
2036 Overall results of the test in a 'sourceable' form. Each line contains
2037 a pair VAR=VALUE. All variable names have 'TESTRESULT_' prefix.
2038 List of variables:
2040 TESTRESULT_STATE
2042 Current state of the test run; possible values: started, incomplete
2043 and complete. - 'started' is set after a Journal is opened. -
2044 'incomplete' is set after a Phase is closed. - 'complete' is set
2045 after a Journal is closed.
2046 TESTRESULT_RESULT_STRING
2048 Result of the test in a string, e.g.: PASS, FAIL, WARN.
2049 TESTRESULT_RESULT_ECODE
2051 Result of the test as an integer, 0 equals to PASS.
2052 TESTRESULT_PHASES_PASSED
2054 Number of phases that ended with PASS.
2055 TESTRESULT_PHASES_FAILED
2057 Number of phases that ended with non-PASS result.
2058 TESTRESULT_PHASES_SKIPPED
2060 Number of skipped phases.
2061 TESTRESULT_ASSERTS_FAILED
2063 Number of asserts that ended with non-PASS result in the whole
2064 test.
2065 TESTRESULT_STARTTIME
2067 Time when test started in seconds since epoch.
2068 TESTRESULT_ENDTIME
2070 Time when test ended in seconds since epoch.
2071 TESTRESULT_DURATION
2073 Duration of the test run in seconds.
2074 TESTRESULT_BEAKERLIB_DIR
2076 Directory with test results files.
2077 TESTRESULT_PHASES_FINGERPRINT
2079 A hash of all phases results which may serve as a reference result
2080 in a specific environment.
2081 TESTRESULT_ASSERTS_FINGERPRINT
2083 A hash of all asserts results which may serve as a reference result
2084 in a specific environment.
2085
2087 Simple
2088 A minimal BeakerLib test can look like this:
2089 . /usr/share/beakerlib/beakerlib.sh
2091 rlJournalStart
2093 rlPhaseStartTest
2094 rlAssertRpm "setup"
2095 rlAssertExists "/etc/passwd"
2096 rlAssertGrep "root" "/etc/passwd"
2097 rlPhaseEnd
2098 rlJournalEnd
2099 Phases
2101 Here comes a bit more interesting example of a test which sets all the
2102 recommended variables and makes use of the phases:
2103 # Include the BeakerLib environment
2105 . /usr/share/beakerlib/beakerlib.sh
2106 # Set the full test name
2108 TEST="/examples/beakerlib/Sanity/phases"
2109 # Package being tested
2111 PACKAGE="coreutils"
2112 rlJournalStart
2114 # Setup phase: Prepare test directory
2115 rlPhaseStartSetup
2116 rlAssertRpm $PACKAGE
2117 rlRun 'TmpDir=$(mktemp -d)' 0 'Creating tmp directory' # no-reboot
2118 rlRun "pushd $TmpDir"
2119 rlPhaseEnd
2120 # Test phase: Testing touch, ls and rm commands
2122 rlPhaseStartTest
2123 rlRun "touch foo" 0 "Creating the foo test file"
2124 rlAssertExists "foo"
2125 rlRun "ls -l foo" 0 "Listing the foo test file"
2126 rlRun "rm foo" 0 "Removing the foo test file"
2127 rlAssertNotExists "foo"
2128 rlRun "ls -l foo" 2 "Listing foo should now report an error"
2129 rlPhaseEnd
2130 # Cleanup phase: Remove test directory
2132 rlPhaseStartCleanup
2133 rlRun "popd"
2134 rlRun "rm -r $TmpDir" 0 "Removing tmp directory"
2135 rlPhaseEnd
2136 rlJournalEnd
2137 # Print the test report
2139 rlJournalPrintText
2140 The ouput of the rlJournalPrintText command would produce an output
2142 similar to the following:
2143 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2145 :: TEST PROTOCOL
2146 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2147 Package : coreutils
2149 Installed : coreutils-8.27-19.fc27.x86_64
2150 beakerlib RPM : beakerlib-1.17-6.fc27.noarch
2151 Test started : 2018-02-08 15:43:03 CET
2152 Test finished : 2018-02-08 15:43:04 CET
2153 Test duration : 1 seconds
2154 Test name : /examples/beakerlib/Sanity/phases
2155 Distro : Fedora release 27 (Twenty Seven)
2156 Hostname : localhost
2157 Architecture : x86_64
2158 CPUs : 4 x Intel Core Processor (Skylake)
2159 RAM size : 1992 MB
2160 HDD size : 17.55 GB
2161 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2163 :: Test description
2164 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2165 PURPOSE of /examples/beakerlib/Sanity/phases
2167 Description: Testing BeakerLib phases
2168 Author: Petr Splichal <psplicha@redhat.com>
2169 This example shows how the phases work in the BeakerLib on a
2171 trivial smoke test for the "touch", "ls" and "rm" commands from
2172 the coreutils package.
2173 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2177 :: Setup
2178 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2179 :: [ 15:43:03 ] :: [ PASS ] :: Checking for the presence of coreutils rpm
2181 :: [ 15:43:03 ] :: [ LOG ] :: Package versions:
2182 :: [ 15:43:03 ] :: [ LOG ] :: coreutils-8.27-19.fc27.x86_64
2183 :: [ 15:43:03 ] :: [ PASS ] :: Creating tmp directory (Expected 0, got 0)
2184 :: [ 15:43:03 ] :: [ PASS ] :: Command 'pushd /tmp/tmp.MMQf7dj9QV' (Expected 0, got 0)
2185 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2186 :: Duration: 1s
2187 :: Assertions: 3 good, 0 bad
2188 :: RESULT: PASS
2189 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2192 :: Test
2193 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2194 :: [ 15:43:04 ] :: [ PASS ] :: Creating the foo test file (Expected 0, got 0)
2196 :: [ 15:43:04 ] :: [ PASS ] :: File foo should exist
2197 :: [ 15:43:04 ] :: [ PASS ] :: Listing the foo test file (Expected 0, got 0)
2198 :: [ 15:43:04 ] :: [ PASS ] :: Removing the foo test file (Expected 0, got 0)
2199 :: [ 15:43:04 ] :: [ PASS ] :: File foo should not exist
2200 :: [ 15:43:04 ] :: [ PASS ] :: Listing foo should now report an error (Expected 2, got 2)
2201 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2202 :: Duration: 0s
2203 :: Assertions: 6 good, 0 bad
2204 :: RESULT: PASS
2205 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2208 :: Cleanup
2209 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2210 :: [ 15:43:04 ] :: [ PASS ] :: Command 'popd' (Expected 0, got 0)
2212 :: [ 15:43:04 ] :: [ PASS ] :: Removing tmp directory (Expected 0, got 0)
2213 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2214 :: Duration: 0s
2215 :: Assertions: 2 good, 0 bad
2216 :: RESULT: PASS
2217 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2220 :: /examples/beakerlib/Sanity/phases
2221 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2222 :: [ 15:43:04 ] :: [ LOG ] :: Phases fingerprint: ZmU1NmJ
2224 :: [ 15:43:04 ] :: [ LOG ] :: Asserts fingerprint: YTBiZDE
2225 :: [ 15:43:04 ] :: [ LOG ] :: JOURNAL XML: /var/tmp/beakerlib-pRiJfWE/journal.xml
2226 :: [ 15:43:04 ] :: [ LOG ] :: JOURNAL TXT: /var/tmp/beakerlib-pRiJfWE/journal.txt
2227 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2228 :: Duration: 1s
2229 :: Phases: 3 good, 0 bad
2230 :: OVERALL RESULT: PASS
2231 Note that the detailed test description is read from a separate file
2233 PURPOSE placed in the same directory as the test itself.
2234 A lot of useful debugging information is reported on the DEBUG level.
2236 You can run your test with "DEBUG=1 make run" to get them.
2237 Verbosity of the test logging may be altered also by setting the
2239 LOG_LEVEL variable. Possible values are "ERROR", "WARNING", "INFO" and
2240 "DEBUG". You will see messages like the ones below.
2241 :: [ WARNING ] :: rlGetArch: Update test to use rlGetPrimaryArch/rlGetSecondaryArch
2243 :: [ DEBUG ] :: rlGetArch: This is architecture 'x86_64'
2244 :: [ ERROR ] :: this function was dropped as its development is completely moved to the beaker library
2245 :: [ INFO ] :: if you realy on this function and you really need to have it present in core beakerlib, file a RFE, please
2246 Setting LOG_LEVEL="DEBUG" is equivalent to DEBUG=1.
2248 Set DEBUG_TO_CONSOLE_ONLY=1 in conjuction with DEBUG=1 to avoid storing
2250 debug messages in journal. This also speeds up the execution in debug
2251 mode as those messages are not fully processed than.
2252
2254 Description
2255 Bkrdoc is a documentation generator from tests written using
2256 BeakerLib library. This generator makes documentation from test
2257 code with and also without any documentation markup.
2258 What it's good for
2260 For fast, brief and reliable documentation creation. It`s good for
2261 quick start with unknown BeakerLib test. Created documentations
2262 provides information about the documentation credibility. Also
2263 created documentations shows environmental variables and helps
2264 reader to run test script from which was documentation created.
2265 Bkrdoc project page
2267 https://github.com/rh-lab-q/bkrdoc
2268
2270 Project Page
2271 https://github.com/beakerlib/beakerlib
2272 Manual
2274 https://github.com/beakerlib/beakerlib/wiki/man
2275 Issues list
2277 https://bugzilla.redhat.com/buglist.cgi?component=beakerlib&&order=bug_status%2Cassigned_to%2Cpriority
2278 https://github.com/beakerlib/beakerlib/issues
2280 Reporting issues
2282 https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora&component=beakerlib
2283 https://github.com/beakerlib/beakerlib/issues/new
2285
2287 • Petr Muller <pmuller@redhat.com>
2288 • Ondrej Hudlicky <ohudlick@redhat.com>
2290 • Jan Hutar <jhutar@redhat.com>
2292 • Petr Splichal <psplicha@redhat.com>
2294 • Ales Zelinka <azelinka@redhat.com>
2296 • Dalibor Pospisil <dapospis@redhat.com>
2298 • Martin Kyral <mkyral@redhat.com>
2300 • Jakub Prokes <jprokes@redhat.com>
2302 • Jakub Heger <jheger@redhat.com>
2304perl v5.36.0 2023-01-18 BEAKERLIB(1)