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
40 Journalling
41 rlJournalStart
42 Initialize the journal file.
44 rlJournalStart
46 Run on the very beginning of your script to initialize journalling
48 functionality.
49 rlJournalEnd
51 Summarize the test run and upload the journal file.
53 rlJournalEnd
55 Run on the very end of your script to print summary of the whole test
57 run, generate OUTPUTFILE and include journal in Beaker logs.
58 rlJournalPrint
60 Print the content of the journal in pretty xml format.
62 rlJournalPrint [type]
64 type
66 Can be either 'raw' or 'pretty', with the latter as a default.
67 Raw: xml is in raw form, no indentation etc Pretty: xml is pretty
68 printed, indented, with one record per line
69 Example:
71 <?xml version="1.0"?>
73 <BEAKER_TEST>
74 <test_id>debugging</test_id>
75 <package>setup</package>
76 <pkgdetails>setup-2.8.9-1.fc12.noarch</pkgdetails>
77 <starttime>2010-02-08 15:17:47</starttime>
78 <endtime>2010-02-08 15:17:47</endtime>
79 <testname>/examples/beakerlib/Sanity/simple</testname>
80 <release>Fedora release 12 (Constantine)</release>
81 <hostname>localhost</hostname>
82 <arch>i686</arch>
83 <purpose>PURPOSE of /examples/beakerlib/Sanity/simple
84 Description: Minimal BeakerLib sanity test
85 Author: Petr Splichal <psplicha@redhat.com>
86 This is a minimal sanity test for BeakerLib. It contains a single
88 phase with a couple of asserts. We Just check that the "setup"
89 package is installed and that there is a sane /etc/passwd file.
90 </purpose>
91 <log>
92 <phase endtime="2010-02-08 15:17:47" name="Test" result="PASS"
93 score="0" starttime="2010-02-08 15:17:47" type="FAIL">
94 <test message="Checking for the presence of setup rpm">PASS</test>
95 <test message="File /etc/passwd should exist">PASS</test>
96 <test message="File '/etc/passwd' should contain 'root'">PASS</test>
97 </phase>
98 </log>
99 </BEAKER_TEST>
100 rlJournalPrintText
102 Print the content of the journal in pretty text format.
104 rlJournalPrintText [--full-journal]
106 --full-journal
108 The option is now deprecated, has no effect and will be removed in
109 a future version.
110 Example:
112 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
114 :: [ LOG ] :: TEST PROTOCOL
115 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
116 :: [ LOG ] :: Test run ID : debugging
118 :: [ LOG ] :: Package : debugging
119 :: [ LOG ] :: Test started : 2010-02-08 14:45:57
120 :: [ LOG ] :: Test finished : 2010-02-08 14:45:58
121 :: [ LOG ] :: Test name :
122 :: [ LOG ] :: Distro: : Fedora release 12 (Constantine)
123 :: [ LOG ] :: Hostname : localhost
124 :: [ LOG ] :: Architecture : i686
125 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
127 :: [ LOG ] :: Test description
128 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
129 PURPOSE of /examples/beakerlib/Sanity/simple
131 Description: Minimal BeakerLib sanity test
132 Author: Petr Splichal <psplicha@redhat.com>
133 This is a minimal sanity test for BeakerLib. It contains a single
135 phase with a couple of asserts. We Just check that the "setup"
136 package is installed and that there is a sane /etc/passwd file.
137 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
140 :: [ LOG ] :: Test
141 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
142 :: [ PASS ] :: Checking for the presence of setup rpm
144 :: [ PASS ] :: File /etc/passwd should exist
145 :: [ PASS ] :: File '/etc/passwd' should contain 'root'
146 :: [ LOG ] :: Duration: 1s
147 :: [ LOG ] :: Assertions: 3 good, 0 bad
148 :: [ PASS ] :: RESULT: Test
149 rlGetTestState
151 Returns number of failed asserts so far, or 255 if there are more than
153 255 failures. The variable ECODE is set to the precise number.
154 rlGetTestState
156 rlGetPhaseState
158 Returns number of failed asserts in the current phase so far, or 255 if
160 there are more than 255 failures. The variable ECODE is set to the
161 precise number.
162 rlGetPhaseState
164 Logging
166 rlLog
167 rlLogDebug
169 rlLogInfo
171 rlLogWarning
173 rlLogError
175 rlLogFatal
177 Create a time/priority-labelled message in the log. There is a bunch of
179 aliases which can create messages formated as DEBUG/INFO/WARNING/ERROR
180 or FATAL (but you would probably want to use rlDie instead of the last
181 one).
182 rlLog message [logfile] [priority] [label]
184 message
186 Message you want to show (use quotes when invoking).
187 logfile
189 Log file. If not supplied, OUTPUTFILE is assumed.
190 priority
192 Priority of the log.
193 label
195 Print this text instead of time in log label.
196 rlDie
198 Create a time-labelled message in the log, report test result, upload
200 logs, close unfinished phase and terminate the test.
201 rlDie message [file...]
203 message
205 Message you want to show (use quotes when invoking) - this option
206 is mandatory.
207 file
209 Files (logs) you want to upload as well. "rlBundleLogs" will be
210 used for it. Files which are not readable will be excluded before
211 calling "rlBundleLogs", so it is safe to call even with possibly
212 nonexistent logs and it will succeed.
213 rlBundleLogs
215 Create a tarball of files (e.g. logs) and attach them to the test
217 result.
218 rlBundleLogs package file [file...]
220 package
222 Name of the package. Will be used as part of the tarball name.
223 file
225 File(s) to be packed and submitted.
226 Returns result of submitting the tarball.
228 rlFileSubmit
230 Resolves absolute path to the file, replaces / with - and uploads this
232 renamed file using rhts-submit-log. It also allows you to specify your
233 custom name for the uploaded file.
234 rlFileSubmit [-s sep] path_to_file [required_name]
236 -s sep
238 Sets separator (i.e. the replacement of the /) to sep.
239 path_to_file
241 Either absolute or relative path to file. Relative path is
242 converted to absolute.
243 required_name
245 Default behavior renames file to full_path_to_file with / replaced
246 for -, if this does not suit your needs, you can specify the name
247 using this option.
248 Examples:
250 rlFileSubmit logfile.txt -> logfile.txt cd /etc; rlFileSubmit
252 ./passwd -> etc-passwd rlFileSubmit /etc/passwd -> etc-passwd
253 rlFileSubmit /etc/passwd my-top-secret_file -> my-top-secret-file
254 rlFileSubmit -s '_' /etc/passwd -> etc_passwd
255 Info
257 rlShowPackageVersion
258 Shows a message about version of packages.
260 rlShowPackageVersion package [package...]
262 package
264 Name of a package(s) you want to log.
265 rlGetArch
267 Sanitize architecture for simplier matching.
269 Return base arch for the current system (good when you need base arch
271 on a multilib system).
272 rlGetArch
274 On any 32-bit Intel (i386, i486, i586, ...) system you will get i386.
276 rlGetPrimaryArch
278 Return primary arch for the current system (good when you need base
280 arch on a multilib system).
281 rlGetPrimaryArch
283 On non-RHEL systems if the primary/secondary sedicision fails a
285 fallback to rlGetArch is done.
286 rlGetSecondaryArch
288 Return base arch for the current system (good when you need base arch
290 on a multilib system).
291 rlGetSecondaryArch
293 rlGetDistroRelease
295 rlGetDistroVariant
297 Return release or variant of the distribution on the system.
299 rlGetDistroRelease
301 rlGetDistroVariant
302 For example on the RHEL-4-AS you will get release 4 and variant AS, on
304 the RHEL-5-Client you will get release 5 and variant Client.
305 rlShowRunningKernel
307 Log a message with version of the currently running kernel.
309 rlShowRunningKernel
311 Phases
313 rlPhaseStart
314 Starts a phase of a specific type. The final phase result is based on
316 all asserts included in the phase. Do not forget to end phase with
317 "rlPhaseEnd" when you are done.
318 rlPhaseStart type [name]
320 type
322 Type of the phase, one of the following:
323 FAIL
325 When assert fails here, phase will report a FAIL.
326 WARN
328 When assert fails here, phase will report a WARN.
329 name
331 Optional name of the phase (if not provided, one will be
332 generated).
333 If all asserts included in the phase pass, phase reports PASS.
335 rlPhaseEnd
337 End current phase, summarize asserts included and report phase result.
339 rlPhaseEnd
341 Final phase result is based on included asserts and phase type.
343 rlPhaseStartSetup
345 rlPhaseStartTest
347 rlPhaseStartCleanup
349 Start a phase of the specified type: Setup -> WARN, Test -> FAIL,
351 Cleanup -> WARN.
352 rlPhaseStartSetup [name]
354 rlPhaseStartTest [name]
355 rlPhaseStartCleanup [name]
356 name
358 Optional name of the phase. If not specified, default
359 Setup/Test/Cleanup are used.
360 If you do not want these shortcuts, use plain "rlPhaseStart" function.
362 Reboot
364 Controlled reboot must not be executed inside of an open phase.
365 Otherwise it is possible the Overall result of the test will be
366 reported incorrectly.
367 Metric
369 rlLogMetricLow
370 Log a metric, which should be as low as possible to the journal.
372 (Example: memory consumption, run time)
373 rlLogMetricLow name value [tolerance]
375 name
377 Name of the metric. It has to be unique in a phase.
378 value
380 Value of the metric.
381 tolerance
383 It is used when comparing via rcw. It means how larger can the
384 second value be to not trigger a FAIL. Default is 0.2
385 When comparing FIRST, SECOND, then:
387 FIRST >= SECOND means PASS
389 FIRST+FIRST*tolerance >= SECOND means WARN
390 FIRST+FIRST*tolerance < SECOND means FAIL
391 Example: Simple benchmark is compared via this metric type in rcw. It
393 has a tolerance of 0.2. First run had 1 second. So:
394 For PASS, second run has to be better or equal to first.
396 So any value of second or less is a PASS.
397 For WARN, second run can be a little worse than first.
398 Tolerance is 0.2, so anything lower than 1.2 means WARN.
399 For FAIL, anything worse than 1.2 means FAIL.
400 rlLogMetricHigh
402 Log a metric, which should be as high as possible to the journal.
404 (Example: number of executions per second)
405 rlLogMetricHigh name value [tolerance]
407 name
409 Name of the metric. It has to be unique in a phase.
410 value
412 Value of the metric.
413 tolerance
415 It is used when comparing via rcw. It means how lower can the
416 second value be to not trigger a FAIL. Default is 0.2
417 When comparing FIRST, SECOND, then:
419 FIRST <= SECOND means PASS
421 FIRST+FIRST*tolerance <= SECOND means WARN
422 FIRST+FIRST*tolerance > SECOND means FAIL
423 Manual Asserts
425 rlPass
426 Manual assertion, asserts and logs PASS.
428 rlPass comment
430 comment
432 Short test summary.
433 Returns 0 and asserts PASS.
435 rlFail
437 Manual assertion, asserts and logs FAIL.
439 rlFail comment
441 comment
443 Short test summary.
444 Returns 1 and asserts FAIL.
446 Arithmetic Asserts
448 rlAssert0
449 Assertion checking for the equality of parameter to zero.
451 rlAssert0 comment value
453 comment
455 Short test summary, e.g. "Test if compilation ended successfully".
456 value
458 Integer value (usually return code of a command).
459 Returns 0 and asserts PASS when "value == 0".
461 rlAssertEquals
463 Assertion checking for the equality of two parameters.
465 rlAssertEquals comment value1 value2
467 comment
469 Short test summary, e.g. "Test if all 3 packages have been
470 downloaded".
471 value1
473 First parameter to compare, can be a number or a string
474 value2
476 Second parameter to compare, can be a number or a string
477 Returns 0 and asserts PASS when "value1 == value2".
479 rlAssertNotEquals
481 Assertion checking for the non-equality of two parameters.
483 rlAssertNotEquals comment value1 value2
485 comment
487 Short test summary, e.g. "Test if return code is not 139".
488 value1
490 First parameter to compare, can be a number or a string
491 value2
493 Second parameter to compare, can be a number or a string
494 Returns 0 and asserts PASS when "value1 != value2".
496 rlAssertGreater
498 Assertion checking whether first parameter is greater than the second
500 one.
501 rlAssertGreater comment value1 value2
503 comment
505 Short test summary, e.g. "Test whether there are running more
506 instances of program."
507 value1
509 Integer value.
510 value2
512 Integer value.
513 Returns 0 and asserts PASS when "value1 > value2".
515 rlAssertGreaterOrEqual
517 Assertion checking whether first parameter is greater or equal to the
519 second one.
520 rlAssertGreaterOrEqual comment value1 value2
522 comment
524 Short test summary (e.g. "There should present at least one...")
525 value1
527 Integer value.
528 value2
530 Integer value.
531 Returns 0 and asserts PASS when "value1 X= value2".
533 rlAssertLesser
535 Assertion checking whether first parameter is lesser than the second
537 one.
538 rlAssertLesser comment value1 value2
540 comment
542 Short test summary, e.g. "Test whether there are running more
543 instances of program."
544 value1
546 Integer value.
547 value2
549 Integer value.
550 Returns 0 and asserts PASS when "value1 < value2".
552 rlAssertLesserOrEqual
554 Assertion checking whether first parameter is lesser or equal to the
556 second one.
557 rlAssertLesserOrEqual comment value1 value2
559 comment
561 Short test summary (e.g. "There should present at least one...")
562 value1
564 Integer value.
565 value2
567 Integer value.
568 Returns 0 and asserts PASS when "value1 X= value2".
570 File Asserts
572 rlAssertExists
573 Assertion checking for the existence of a file or a directory.
575 rlAssertExists file|directory
577 file|directory
579 Path to the file or directory.
580 Returns 0 and asserts PASS when "file" exists.
582 rlAssertNotExists
584 Assertion checking for the non-existence of a file or a directory.
586 rlAssertNotExists file|directory
588 file|directory
590 Path to the file or directory.
591 Returns 0 and asserts PASS when "file" does not exist.
593 rlAssertGrep
595 Assertion checking if the file contains a pattern.
597 rlAssertGrep pattern file [options]
599 pattern
601 Regular expression to be searched for.
602 file
604 Path to the file.
605 options
607 Optional parameters to be passed to grep, default is "-q". Can be
608 used to perform case insensitive matches (-i), or using extended
609 (-E) or perl (-P) regular expressions.
610 Returns 0 and asserts PASS when "file" exists and contains given
612 "pattern".
613 rlAssertNotGrep
615 Assertion checking that the file does not contain a pattern.
617 rlAssertNotGrep pattern file [options]
619 pattern
621 Regular expression to be searched for.
622 file
624 Path to the file.
625 options
627 Optional parameters to be passed to grep, default is "-q". Can be
628 used to perform case insensitive matches (-i), or using extended
629 (-E) or perl (-P) regular expressions.
630 Returns 0 and asserts PASS when "file" exists and does not contain
632 given "pattern".
633 rlAssertDiffer
635 Assertion checking that two files differ (are not identical).
637 rlAssertDiffer file1 file2
639 file1
641 Path to first file1
642 file2
644 Path to second file
645 Returns 0 and asserts PASS when "file1" and "file2" differs.
647 rlAssertNotDiffer
649 Assertion checking that two files do not differ (are identical).
651 rlAssertNotDiffer file1 file2
653 file1
655 Path to first file1
656 file2
658 Path to second file
659 Returns 0 and asserts PASS when "file1" and "file2" do not differ.
661 Run, Watch, Report
663 rlRun
664 Run command with optional comment and make sure its exit code matches
666 expectations.
667 rlRun [-t] [-l] [-c] [-s] command [status[,status...] [comment]]
669 -t If specified, stdout and stderr of the command output will be
671 tagged with strings 'STDOUT: ' and 'STDERR: '.
672 -l If specified, output of the command (tagged, if -t was specified)
674 is logged using rlLog function. This is intended for short outputs,
675 and therefore only last 50 lines are logged this way. Longer
676 outputs should be analysed separately, or uploaded via rlFileSubmit
677 or rlBundleLogs.
678 -c Same as "-l", but only log the command output if it failed.
680 -s Store stdout and stderr to a file (mixed together, as the user
682 would see it on a terminal) and set $rlRun_LOG variable to name of
683 the file. $rlRun_LOG is now actually an array where the first index
684 holds the last reference to the file. Thus its behavior is not
685 changed if used without an index. The array is consumed by the
686 rlJournalEnd function to remove the leftover files, so no manual
687 files removal is needed anymore. Note that if you need to use such
688 a file after calling the rlJournalEnd function you need to create
689 your own copy of the respective file. When -t option is used, the
690 content of the file becomes tagged too.
691 If the -s option is not used, $rlRun_LOG is not modified and keeps
693 its content from the last "rlRun -s".
694 command
696 Command to run.
697 status
699 Expected exit code(s). Optional, default 0. If you expect more exit
700 codes, separate them with comma (e.g. "0,1" when both 0 and 1 are
701 OK and expected), or use from-to notation (i.e. "2-5" for
702 "2,3,4,5"), or combine them (e.g. "2-4,26" for "2,3,4,26").
703 comment
705 Short summary describing the action (optional, but recommended -
706 explain what you are doing here).
707 Returns the exit code of the command run. Asserts PASS when command\'s
709 exit status is in the list of expected exit codes.
710 Note:
712 • The output of rlRun is buffered when using "-t", "-l" or "-s"
714 option (they use unix pipes, which are buffered by nature). If you
715 need an unbuffered output just make sure that "expect" package is
716 installed on your system (its "unbuffer" tool will automatically be
717 used to produce unbuffered output).
718 • Be aware that there are some variables which can collide with your
720 code executed within rlRun. You should avoid using
721 __INTERNAL_rlRun_* variables.
722 • When any of "-t" "-l", "-c", or "-s" option is used, special file
724 descriptors 111 and 112 are used to avoid the issue with incomplete
725 log file, bz1361246. As there might be an indefinite loop, there's
726 a timeout of two minutes implemented as a fix for bz1416796. Also
727 an error message is issued to signal the possibility of running
728 subprocess which keeps the file descriptors open.
729 Do not use these options if you expect process forking and
731 continuouse run. Try your own apropriate solution instead.
732 Warning: using "unbuffer" tool is now disabled because of bug 547686.
734 rlWatchdog
736 Run "command". If it does not finish in specified time, then kill it
738 using "signal". Note that the command is executed in a sub-shell so
739 modified environment (e.g. set variables) is not relfected in the test
740 environment.
741 rlWatchdog command timeout [signal] [callback]
743 command
745 Command to run.
746 timeout
748 Timeout to wait, in seconds.
749 signal
751 Signal to use (optional, default KILL).
752 callback
754 Callback function to be called before the signal is send (optional,
755 none by default). The callback function will have one argument
756 available -- PGID of the process group.
757 Returns 0 if the command ends normally, without need to be killed.
759 rlReport
761 Report test result to the test harness. The command to be used for
763 reporting is set by the respective plugin. You can also use the
764 $BEAKERLIB_COMMAND_REPORT_RESULT variable to use your custom command.
765 rlReport name result [score] [log]
767 name
769 Name of the test result.
770 result
772 Result (one of PASS, WARN, FAIL). If called with something else,
773 will use WARN.
774 score
776 Test score (optional).
777 log Optional log file to be submitted instead of default "OUTPUTFILE".
779 rlCmpVersion
781 Compare two given versions composed by numbers and letters divided by
783 dot (.), underscore (_), or dash (-).
784 rlCmpVersion ver1 ver2
786 If ver1 = ver2, sign '=' is printed to stdout and 0 is returned. If
788 ver1 > ver2, sign '>' is printed to stdout and 1 is returned. If ver1
789 < ver2, sign '<' is printed to stdout and 2 is returned.
790 rlTestVersion
792 Test releation between two given versions based on given operator.
794 rlTestVersion ver1 op ver2
796 op Operator defining the logical expression. It can be '=', '==',
798 '!=', '<', '<=', '=<', '>', '>=', or '=>'.
799 Returns 0 if the expresison ver1 op ver2 is true; 1 if the expression
801 is false and 2 if something went wrong.
802 Release Info
804 rlIsRHEL
805 rlIsRHEL [VERSION_SPEC]...
807 VERSION_SPEC
809 Argument specifies version of particular RHEL distribution, eg. 8,
810 8.4 ">8.4".
811 For more details see description of "rlIsOSVersion".
813 Returns 0 when we're running on RHEL. With given version specification
815 in arguments returns 0 if the particular RHEL version is running.
816 Prototype:
818 rlIsRHEL
820 Returns 0 if we are running on RHEL.
822 rlIsRHEL 7 '>=8.5'
824 Returns 0 if we are running any RHEL 7 or RHEL 8.5 and higher.
826 rlIsFedora
828 rlIsFedora [VERSION_SPEC]...
830 VERSION_SPEC
832 Argument specifies version of particular Fedora distribution, eg.
833 30, ">30".
834 For more details see description of "rlIsOSVersion".
836 Returns 0 when we're running on Fedora. With given version
838 specification in arguments returns 0 if the particular Fedora version
839 is running.
840 Prototype:
842 rlIsFedora
844 Returns 0 if we are running on Fedora.
846 rlIsFedora 30 32
848 Returns 0 if we are running Fedora 30 or 32.
850 rlIsCentOS
852 rlIsCentOS [VERSION_SPEC]...
854 VERSION_SPEC
856 Argument specifies version of particular CentOS distribution, eg.
857 7, ">7".
858 For more details see description of "rlIsOSVersion".
860 Returns 0 when we're running on CentOS. With given version
862 specification in arguments returns 0 if the particular CentOS version
863 is running.
864 Prototype:
866 rlIsCentOS
868 Returns 0 if we are running on CentOS.
870 rlIsCentOS 7.1 6
872 Returns 0 if we are running CentOS 7.1 or any CentOS 6.
874 rlIsOS
876 rlIsOS ID
878 ID Argument is based on contents of /etc/os-release. Possible options
880 of ID are e.g. fedora, rhel, centos, ol.
881 Returns 0 when we're running on system with respective ID. Returns 1
883 when parameter does not match with ID in os-release. Returns 2 when
884 there is no ID defined. Returns 3 when no argument is given.
885 Prototype:
887 rlIsOS rhel
889 Returns 0 if we are running on RHEL.
891 rlIsOSLike
893 rlIsOSLike ID_LIKE
895 ID_LIKE
897 Argument is based on contents of /etc/os-release. Possible options
898 of ID_LIKE are e.g. fedora, rhel.
899 Returns 0 when we're running on system with requested ID_LIKE. Returns
901 1 when parameter does not match with ID nor ID_LIKE in os-release.
902 Returns 2 when there is no ID or ID_LIKE defined. Returns 3 when no
903 argument is given.
904 Prototype:
906 rlIsOSLike rhel
908 Returns 0 if we are running on RHEL, CentOS, Rocky Linux, etc..
910 rlIsOSLike fedora
912 Returns 0 if we are running on Fedora, RHEL, CentOS, Oracle Linux, etc..
914 rlIsOSVersion
916 rlIsOsVersion VERSION_SPEC...
918 VERSION_SPEC
920 Parameter is based on VERSION_ID in /etc/os-release. It consists
921 of either "major" or "major"."minor" refering to a particular
922 release.
923 It accepts multiple arguments separated by space (8.1 8.2 8.3 9).
925 To specify a group of distributions optional operator can be passed
927 in argument together with the version number as one string
928 ('>8.5'). Operator can be '<', '<=', '=<', '=', '>', '>=' matching
929 whether the currently installed version is lesser, lesser or equal,
930 equal, equal or greater, greater than the version number supplied
931 as second half of the argument.
932 Note that when using >/< operators you have to either put the
934 argument in quotes or escape the operators to avoid them being
935 interpreted as bash redirection operator.
936 Returns 0 when we're running distribution of the particular version
938 requested by the argument.
939 It usually follows after "rlIsOS" and "rlIsOSLike".
941 Be cautious when using together with "rlIsOSLike" as different
943 distributions may use different versioning schema.
944 Prototype:
946 rlIsOSVersion 6 7 9
948 Returns 0 if we are running distribution with VERSION_ID 6, 7 or 9.
950 rlIsOSVersion 7.8 8
952 Returns 0 if we are running distribution 7.8 or any 8.
954 rlIsOSVersion ">=7.5" or rlIsOSVersion \>=7.5
956 Returns 0 if we are running distribution 7.5 or higher (both minors or majors).
958 Note:
960 rlIsOSVersion '<7.5' || rlIsOSVersion '<8.5'
962 would also cover 7.9 as it is less than 8.5, which is not what you want.
964 So if you want to construct a condition for a distribution <7.5 within the major 7 or
965 a distribution <8.5 within the major 8 you actually need to use following construct:
966 rlIsOSVersion 7 && rlIsOSVersion '<7.5' || rlIsOSVersion 8 && rlIsOSVersion '<8.5'
968 This returns 0 when running distribution less than 7.5 and less then 8.5, but not 7.9 (nor 6.9).
970 rlIsRHELLike
972 rlIsRHELLike [VERSION_SPEC]...
974 VERSION_SPEC
976 Argument specifies version of particular RHEL distribution, eg. 8,
977 8.4 ">8.4".
978 For more details see description of "rlIsOSVersion".
980 Returns 0 when we're running on RHEL-like distribution. These are
982 considered to be RHEL, CentOS, Rocky Linux, etc.. With given version
983 specification in arguments returns 0 if the particular version of RHEL-
984 like distribution is running.
985 Prototype:
987 rlIsRHELLike
989 Returns 0 if we are running on RHEL-like system.
991 rlIsRHELLike ">=6"
993 Returns 0 if we are running on RHEL-like distribution of version 6.0 or higher.
995 Rpm Handling
997 rlCheckRpm
998 Check whether a package is installed.
1000 rlCheckRpm name [version] [release] [arch]
1002 name
1004 Package name like "kernel"
1005 version
1007 Package version like 2.6.25.6
1008 release
1010 Package release like "55.fc9"
1011 arch
1013 Package architucture like "i386"
1014 Returns 0 if the specified package is installed.
1016 rlAssertRpm
1018 Assertion making sure that a package is installed.
1020 rlAssertRpm name [version] [release] [arch]>
1022 rlAssertRpm --all
1023 name
1025 Package name like "kernel"
1026 version
1028 Package version like 2.6.25.6
1029 release
1031 Package release like "55.fc9"
1032 arch
1034 Package architucture like "i386"
1035 --all
1037 Assert all packages listed in the $PACKAGES $REQUIRES and
1038 $COLLECTIONS environment variables.
1039 Returns 0 and asserts PASS if the specified package is installed.
1041 rlAssertNotRpm
1043 Assertion making sure that a package is not installed. This is just
1045 inverse of "rlAssertRpm".
1046 rlAssertNotRpm name [version] [release] [arch]>
1048 name
1050 Package name like "kernel"
1051 version
1053 Package version like 2.6.25.6
1054 release
1056 Package release like "55.fc9"
1057 arch
1059 Package architucture like "i386"
1060 Returns 0 and asserts PASS if the specified package is not installed.
1062 Example
1064 Function "rlAssertRpm" is useful especially in prepare phase where it
1066 causes abort if a package is missing, while "rlCheckRpm" is handy when
1067 doing something like:
1068 if ! rlCheckRpm package; then
1070 yum install package
1071 rlAssertRpm package
1072 fi
1073 rlAssertBinaryOrigin
1075 Assertion making sure that given binary is owned by (one of) the given
1077 package(s).
1078 rlAssertBinaryOrigin binary package [package2 [...]]
1080 PACKAGES=... rlAssertBinaryOrigin binary
1081 binary
1083 Binary name like "ksh" or "/bin/ksh"
1084 package
1086 List of packages like "ksh mksh". The parameter is optional. If
1087 missing, contents of environment variable $PACKAGES are taken into
1088 account.
1089 Returns 0 and asserts PASS if the specified binary belongs to (one of)
1091 the given package(s). Returns 1 and asserts FAIL if the specified
1092 binary does not belong to (any of) the given package(s). Returns 2 and
1093 asserts FAIL if the specified binary is not found. Returns 3 and
1094 asserts FAIL if no packages are given. Returns 100 and asserts FAIL if
1095 invoked with no parameters.
1096 Example
1098 Function "rlAssertBinaryOrigin" is useful especially in prepare phase
1100 where it causes abort if a binary is missing or is owned by different
1101 package:
1102 PACKAGES=mksh rlAssertBinaryOrigin ksh
1104 or
1105 rlAssertBinaryOrigin ksh mksh
1106 Returns true if ksh is owned by the mksh package (in this case:
1108 /bin/ksh is a symlink pointing to /bin/mksh).
1109 rlGetMakefileRequires
1111 Prints space separated list of requirements defined in Makefile using
1113 'Requires' attribute.
1114 Return 0 if success.
1116 rlGetYAMLdeps
1118 Prints space separated list of requirements defined in metadata.yaml
1120 using 'require' and / or 'recommend' attribute.
1121 Full fmf ids and library references are to be ignored.
1123 rlGetYAMLdeps DEP_TYPE [array_var_name]
1125 DEP_TYPE
1127 Dependency type defined as a regexp. Expected values are 'require',
1128 'recommend', or 'require|recommend'. The matching attribute values
1129 are then processed. Defaults to 'require'.
1130 array_var_name
1132 Name of the variable to put the output to in a form of an array.
1133 This can hold also dependencies with specific version. If used,
1134 the output to stdout is suppressed.
1135 Return 0 if success.
1137 rlCheckRequirements
1139 Check that all given requirements are covered eigther by installed
1141 package or by binary available in PATHs or by some package's provides.
1142 rlRun "rlCheckRequirements REQ..."
1144 REQ Requirement to be checked. It can be package name, provides string
1146 or binary name. Moreover, the requirement can be written the same
1147 way as the Require in the spec file, including the version
1148 specification, e.g. "bash >= 4.4". The comparsion operator may be
1149 any of supported by rlTestVersion(), see its manual.
1150 Returns number of unsatisfied requirements.
1152 rlCheckMakefileRequires
1154 Check presence of required packages / binaries defined in metadata.yaml
1156 provided by "tmt" or Makefile of the test.
1157 Also check presence of recommended packages / binaries defined in
1159 metadata.yaml provided by "tmt". These however do not participate on
1160 the return code, these are just informative.
1161 Example
1163 rlRun "rlCheckMakefileRequires"
1165 Return 255 if requirements could not be retrieved, 0 if all
1167 requirements are satisfied or number of unsatisfied requirements.
1168 rlGetRequired =head3 rlGetRecommended
1170 Get a list of required or recommended packages / binaries defined in
1172 metadata.yaml provided by "tmt" or in a Makefile of the test.
1173 rlGetRequired [ARRAY_VAR_NAME]
1175 rlGetRecommended [ARRAY_VAR_NAME]
1176 ARRAY_VAR_NAME
1178 If provided the variable is populated as an array with the
1179 respective dependencies. Otherwise the dependencies are printed out
1180 to the STDOUT.
1181 Return 255 if requirements could not be retrieved, 0 otherwise.
1183 rlCheckRequired =head3 rlCheckRecommended =head3 rlCheckDependencies
1185 Check presence of required, recommended or both packages / binaries
1187 defined in metadata.yaml provided by "tmt" or in a Makefile of the
1188 test.
1189 Example
1191 rlRun "rlCheckRequired"
1193 rlRun "rlCheckRecommended"
1194 rlRun "rlCheckDependencies"
1195 Return 255 if requirements could not be retrieved, 0 if all
1197 requirements are satisfied or number of unsatisfied requirements.
1198 rlAssertRequired
1200 Ensures that all required packages provided in either metadata.yaml or
1202 Makefile are installed.
1203 rlAssertRequired
1205 Prints out a verbose list of installed/missing packages during
1207 operation.
1208 Returns 0 if all required packages are installed, 1 if one or more
1210 packages are missing or if no Makefile is present.
1211 Getting RPMs
1213 Download methods
1214 Functions handling rpm downloading/installing can use more methods for
1216 actual download of the rpm.
1217 Currently there are two download methonds available:
1219 direct
1221 Use use dirct download from build system (brew).
1222 yum Use yumdownloader or dnf download.
1224 The methods and their order are defined by
1226 BEAKERLIB_RPM_DOWNLOAD_METHODS variable as space separated list. By
1227 default it is 'direct yum'. This can be overridden by user. There may
1228 be done also additions or changes to the original value, e.g.
1229 BEAKERLIB_RPM_DOWNLOAD_METHODS='yum
1230 ${BEAKERLIB_RPM_DOWNLOAD_METHODS/yum/}'
1231 Beakerlib is prepared for more Koji-based sources of packages while
1235 usigng direct download method. By default packages are fetched from
1236 Koji, particularly from https://kojipkgs.fedoraproject.org/packages.
1237 rlRpmInstall
1239 Try to install specified package from local Red Hat sources.
1241 rlRpmInstall [--quiet] package version release arch
1243 --quiet
1245 Make the download and the install process be quiet.
1246 package
1248 Package name like "kernel"
1249 version
1251 Package version like 2.6.25.6
1252 release
1254 Package release like "55.fc9"
1255 arch
1257 Package arch like "i386"
1258 Returns 0 if specified package was installed successfully.
1260 rlRpmDownload
1262 Try to download specified package.
1264 rlRpmDownload [--quiet] {package version release arch|N-V-R.A}
1266 rlRpmDownload [--quiet] --source {package version release|N-V-R}
1267 --quiet
1269 Make the download process be quiet.
1270 package
1272 Package name like "kernel"
1273 version
1275 Package version like 2.6.25.6
1276 release
1278 Package release like "55.fc9"
1279 arch
1281 Package arch like "i386"
1282 Returns 0 if specified package was downloaded successfully.
1284 rlFetchSrcForInstalled
1286 Tries various ways to download source rpm for specified installed rpm.
1288 rlFetchSrcForInstalled [--quiet] package
1290 --quiet
1292 Make the download process be quiet.
1293 package
1295 Installed package name like "kernel". It accepts in-direct names.
1296 E.g. for the package name "krb5-libs" the function will download
1297 the "krb5" source rpm.
1298 Returns 0 if the source package was successfully downloaded.
1300 Mounting
1302 rlMount
1303 Create mount point (if neccessary) and mount a NFS share.
1305 rlMount [-o MOUNT_OPTS] server share mountpoint
1307 server
1309 NFS server hostname.
1310 share
1312 Shared directory name.
1313 mountpoint
1315 Local mount point.
1316 MOUNT_OPTS
1318 Mount options.
1319 Returns 0 if mounting the share was successful.
1321 rlCheckMount
1323 Check either if a directory is a mountpoint, if it is a mountpoint to a
1325 specific server, or if it is a mountpoint to a specific export on a
1326 specific server and if it uses specific mount options.
1327 rlCheckMount [-o MOUNT_OPTS] mountpoint
1329 rlCheckMount [-o MOUNT_OPTS] server mountpoint
1330 rlCheckMount [-o MOUNT_OPTS] server share mountpoint
1331 mountpoint
1333 Local mount point.
1334 server
1336 NFS server hostname
1337 share
1339 Shared directory name
1340 MOUNT_OPTS
1342 Mount options to check (comma separated list)
1343 With one parameter, returns 0 when specified directory exists and is a
1345 mountpoint. With two parameters, returns 0 when specific directory
1346 exists, is a mountpoint and an export from specific server is mounted
1347 there. With three parameters, returns 0 if a specific shared directory
1348 is mounted on a given server on a given mountpoint
1349 If the -o option is provided, returns 0 if the mountpoint uses all the
1351 given options, 2 otherwise.
1352 rlAssertMount
1354 Assertion making sure that given directory is a mount point, if it is a
1356 mountpoint to a specific server, or if it is a mountpoint to a specific
1357 export on a specific server and if it uses specific mount options.
1358 rlAssertMount [-o MOUNT_OPTS] mountpoint
1360 rlAssertMount [-o MOUNT_OPTS] server mountpoint
1361 rlAssertMount [-o MOUNT_OPTS] server share mountpoint
1362 mountpoint
1364 Local mount point.
1365 server
1367 NFS server hostname
1368 share
1370 Shared directory name
1371 MOUNT_OPTS
1373 Mount options to check (comma separated list)
1374 With one parameter, returns 0 when specified directory exists and is a
1376 mountpoint. With two parameters, returns 0 when specific directory
1377 exists, is a mountpoint and an export from specific server is mounted
1378 there. With three parameters, returns 0 if a specific shared directory
1379 is mounted on a given server on a given mountpoint. Asserts PASS when
1380 the condition is true.
1381 If the -o option is provided, asserts PASS if the above conditions are
1383 met and the mountpoint uses all the given options.
1384 rlHash, rlUnhash
1386 Hashes/Unhashes given string and prints the result to stdout.
1388 rlHash [--decode] [--algorithm HASH_ALG] --stdin|STRING
1390 rlUnhash [--algorithm HASH_ALG] --stdin|STRING
1391 --decode
1393 Unhash given string.
1394 --algorithm
1396 Use given hash algorithm. Currently supported algorithms:
1397 base64
1398 base64_ - this is standard base64 where '=' is replaced by '_'
1399 hex
1400 Defaults to hex. Default algorithm can be override using global
1402 variable rlHashAlgorithm.
1403 --stdin
1405 Get the string from stdin.
1406 STRING
1408 String to be hashed/unhashed.
1409 Returns 0 if success.
1411 Backup and Restore
1413 rlFileBackup
1414 Create a backup of files or directories (recursive). Can be used
1416 multiple times to add more files to backup. Backing up an already
1417 backed up file overwrites the original backup.
1418 rlFileBackup [--clean] [--namespace name] [--missing-ok|--no-missing-ok] file [file...]
1420 You can use "rlRun" for asserting the result but keep in mind meaning
1422 of exit codes, especialy exit code 8, if using without --clean option.
1423 --clean
1425 If this option is provided (has to be the first option of the
1426 command), then file/dir backed up using this command (provided in
1427 next options) will be (recursively) removed before we restore it.
1428 This option implies --missing-ok, which can be overridden by
1429 --no-missing-ok.
1430 --namespace name
1432 Specifies the namespace to use. Namespaces can be used to separate
1433 backups and their restoration.
1434 --missing-ok
1436 Do not raise an error in case of missing file to backup.
1437 --no-missing-ok
1439 Do raise an error in case of missing file to backup. This is
1440 useful with --clean. This behaviour can be globally set by global
1441 variable BEAKERLIB_FILEBACKUP_MISSING_OK=false.
1442 file
1444 Files and/or directories to be backed up.
1445 Returns 0 if the backup was successful. Returns 1 if parsing of
1447 parameters was not successful. Returns 2 if no files specification was
1448 provided. Returns 3 if BEAKERLIB_DIR variable is not set, e.g.
1449 rlJournalStart was not executed. Returns 4 if creating of main backup
1450 destination directories was not successful. Returns 5 if creating of
1451 file specific backup destination directories was not successful.
1452 Returns 6 if the copy of backed up files was not successful. Returns 7
1453 if attributes of backed up files were not successfuly copied. Returns
1454 8 if backed up files do not exist. This can be suppressed based on
1455 other options.
1456 Example with --clean:
1458 touch cleandir/aaa
1460 rlRun "rlFileBackup --clean cleandir/"
1461 touch cleandir/bbb
1462 ls cleandir/
1463 aaa bbb
1464 rlRun "rlFileRestore"
1465 ls cleandir/
1466 aaa
1467 rlFileRestore
1469 Restore backed up files to their original location. "rlFileRestore"
1471 does not remove new files appearing after backup has been made. If you
1472 don't want to leave anything behind just remove the whole original tree
1473 before running "rlFileRestore", or see "--clean" option of
1474 "rlFileBackup".
1475 rlFileRestore [--namespace name]
1477 You can use "rlRun" for asserting the result.
1479 --namespace name
1481 Specifies the namespace to use. Namespaces can be used to separate
1482 backups and their restoration.
1483 Returns 0 if backup dir is found and files are restored successfully.
1485 Return code bits meaning:
1487 XXXXX
1489 |||||
1490 ||||\_ error parsing parameters
1491 |||\__ could not find backup directory
1492 ||\___ files cleanup failed
1493 |\____ files restore failed
1494 \_____ no files were restored nor cleaned
1495 Services
1497 Following routines implement comfortable way how to start/stop system
1498 services with the possibility to restore them to their original state
1499 after testing.
1500 rlServiceStart
1502 Make sure the given "service" is running with fresh configuration.
1504 (Start it if it is stopped and restart if it is already running.) In
1505 addition, when called for the first time, the current state is saved so
1506 that the "service" can be restored to its original state when testing
1507 is finished, see "rlServiceRestore".
1508 rlServiceStart service [service...]
1510 service
1512 Name of the service(s) to start.
1513 Returns number of services which failed to start/restart; thus zero is
1515 returned when everything is OK.
1516 rlServiceStop
1518 Make sure the given "service" is stopped. Stop it if it is running and
1520 do nothing when it is already stopped. In addition, when called for the
1521 first time, the current state is saved so that the "service" can be
1522 restored to its original state when testing is finished, see
1523 "rlServiceRestore".
1524 rlServiceStop service [service...]
1526 service
1528 Name of the service(s) to stop.
1529 Returns number of services which failed to become stopped; thus zero is
1531 returned when everything is OK.
1532 rlServiceRestore
1534 Restore given "service" into its original state (before the first
1536 "rlServiceStart" or "rlServiceStop" was called). If "rlServiceStart"
1537 was called on already running "service", "rlServiceRestore" will
1538 restart the "service" when restoring its state.
1539 rlServiceRestore [service...]
1541 service
1543 Name of the service(s) to restore to original state. All services
1544 will be restored in reverse order if no service name is given.
1545 Returns number of services which failed to get back to their original
1547 state; thus zero is returned when everything is OK.
1548 rlServiceStatus
1550 Print status (output of `service SERVICE status` or `systemctl status
1552 SERVICE`) of given "SERVICE".
1553 rlServiceStatus SERVICE [SERVICE...]
1555 SERVICE
1557 The service to get the status of.
1558 Returns service status return code of the last provided SERVICE.
1560 rlServiceEnable
1562 Enables selected services if needed, or does nothing if already
1564 enabled. In addition, when called for the first time, the current
1565 state is saved so that the "service" can be restored to its original
1566 state when testing is finished, see "rlServiceRestore".
1567 rlServiceEnable service [service...]
1569 service
1571 Name of the service(s) to enable.
1572 Returns number of services which failed enablement; thus zero is
1574 returned when everything is OK.
1575 rlServiceDisable
1577 Disables selected services if needed, or does nothing if already
1579 disabled. 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 rlServiceDisable service [service...]
1584 service
1586 Name of the service(s) to disable.
1587 Returns number of services which failed disablement; thus zero is
1589 returned when everything is OK.
1590 Sockets
1592 Following routines implement comfortable way how to start/stop system
1593 sockets with the possibility to restore them to their original state
1594 after testing.
1595 rlSocketStart
1597 Make sure the given "socket" is running. (Start it if stopped, leave it
1599 if already running.) In addition, when called for the first time, the
1600 current state is saved so that the "socket" can be restored to its
1601 original state when testing is finished, see "rlSocketRestore".
1602 rlSocketStart socket [socket...]
1604 socket
1606 Name of the socket(s) to start.
1607 Returns number of sockets which failed to start/restart; thus zero is
1609 returned when everything is OK.
1610 rlSocketStop
1612 Make sure the given "socket" is stopped. Stop it if it is running and
1614 do nothing when it is already stopped. In addition, when called for the
1615 first time, the current state is saved so that the "socket" can be
1616 restored to its original state when testing is finished, see
1617 "rlSocketRestore".
1618 rlSocketStop socket [socket...]
1620 socket
1622 Name of the socket(s) to stop.
1623 Returns number of sockets which failed to become stopped; thus zero is
1625 returned when everything is OK.
1626 rlSocketRestore
1628 Restore given "socket" into its original state (before the first
1630 "rlSocketStart" or "rlSocketStop" was called).
1631 Warning !!! Xinetd process [even though it might have been used] is
1633 NOT restored. It is recommended to call rlServiceRestore xinetd as
1634 well.
1635 rlSocketRestore socket [socket...]
1637 socket
1639 Name of the socket(s) to restore to original state.
1640 Returns number of sockets which failed to get back to their original
1642 state; thus zero is returned when everything is OK.
1643 Cleanup management
1645 Cleanup management works with a so-called cleanup buffer, which is a
1646 temporary representation of what should be run at cleanup time, and a
1647 final cleanup script (executable), which is generated from this buffer
1648 and wraps it using BeakerLib essentials (journal initialization,
1649 cleanup phase, ...). The cleanup script must always be updated on an
1650 atomic basis (filesystem-wise) to allow an asynchronous execution by a
1651 third party (ie. test watcher).
1652 The test watcher usage is mandatory for the cleanup management system
1654 to work properly as it is the test watcher that executes the actual
1655 cleanup script. Limited, catastrophe-avoiding mechanism is in place
1656 even when the test is not run in test watcher, but that should be seen
1657 as a backup and such situation is to be avoided whenever possible.
1658 The cleanup script shares all environment (variables, exported or not,
1660 and functions) with the test itself - the cleanup append/prepend
1661 functions "sample" or "snapshot" the environment at the time of their
1662 call, IOW any changes to the test environment are synchronized to the
1663 cleanup script only upon calling append/prepend. When the
1664 append/prepend functions are called within a function which has local
1665 variables, these will appear as global in the cleanup.
1666 While the cleanup script receives $PWD from the test, its working dir
1668 is set to the initial test execution dir even if $PWD contains
1669 something else. It is impossible to use relative paths inside cleanup
1670 reliably - certain parts of the cleanup might have been added under
1671 different current directories (CWDs). Therefore always use absolute
1672 paths in append/prepend cleanup or make sure you never 'cd' elsewhere
1673 (ie. to a TmpDir).
1674 rlCleanupAppend
1676 Appends a string to the cleanup buffer and recreates the cleanup
1678 script.
1679 rlCleanupAppend string
1681 Returns 0 if the operation was successful, 1 otherwise.
1683 rlCleanupPrepend
1685 Prepends a string to the cleanup buffer and recreates the cleanup
1687 script.
1688 rlCleanupPrepend string
1690 Returns 0 if the operation was successful, 1 otherwise.
1692 Time Performance
1694 rlPerfTime_RunsInTime
1695 Measures, how many runs of some commands can be done in specified time.
1697 This approach is suitable for short-time running tasks (up to few
1698 seconds), where averaging few runs is not precise. This is done several
1699 times, and the final result is the average of all runs. It prints the
1700 number on stdout, so it has to be captured.
1701 rlPerfTime_RunsInTime command [time] [runs]
1703 command
1705 Command to run.
1706 time
1708 Time in seconds (optional, default=30).
1709 runs
1711 Number of averaged runs (optional, default=3).
1712 rlPerfTime_AvgFromRuns
1714 Measures the average time of running some task. This approach is
1716 suitable for long-time running tasks (tens of seconds and more), where
1717 it is precise enough. Measured runs can be preceded by dry run, which
1718 is not measured and it's purpose is to warm up various caches. It
1719 prints the number on stdout, so it has to be captured. Or, result is
1720 then stored in special rl_retval variable.
1721 rlPerfTime_AvgFromRuns command [count] [warmup]
1723 command
1725 Command to run.
1726 count
1728 Times to run (optional, default=3).
1729 warmup
1731 Warm-up run, run if this option is not "warmup" (optional,
1732 default="warmup")
1733 Analyze
1735 rlDejaSum
1736 TODO description
1738 rlDejaSum par1 par2
1740 par1
1742 TODO description
1743 par2
1745 TODO description
1746 Return 0 if... TODO
1748 rlImport
1750 Imports code provided by one or more libraries into the test namespace.
1752 The library search mechanism is based on Beaker test hierarchy system,
1753 i.e.:
1754 /component/type/test-name/test-file
1756 When test-file calls rlImport with 'foo/bar' parameter, the libraries
1758 are searched in following locations: these are the possible path
1759 prefixes
1760 - colon-separated paths from $BEAKERLIB_LIBRARY_PATH
1762 - /mnt/tests
1763 - /usr/share/beakerlib-libraries
1764 the next component of the path is one of the following:
1766 - /foo/Library/bar
1768 - /foo/bar
1769 - /libs/foo/bar
1770 - /*/foo/Library/bar
1771 - /libs/*/foo/Library/bar
1772 - /libs/*/foo/bar
1773 the directory path is then constructed as prefix/path/lib.sh If the
1775 library is still not found an upwards directory traversal is used, and
1776 a check for presence of the library in the above mentioned possible
1777 paths is to be performed. This means this function needs to be called
1778 from the test hierarchy, not e.g. the /tmp directory.
1779 Once library is found, it is sourced and a verifier function is called.
1781 The verifier function is cunstructed by composing the library prefix
1782 and LibraryLoaded. Library prefix must be defined in the library
1783 itself. It should be part of lib.sh header in format: '# library-
1784 prefix = <PREFIX>'. If the verifier passes the library is ready to
1785 use. Also variable <PREFIX>LibraryDir is created and it points to the
1786 library folder.
1787 Usage:
1789 rlImport --all
1791 rlImport LIBRARY [LIBRARY2...]
1792 --all
1794 Read $BEAKERLIB_DIR/metadata.yaml or ./Makefile, pickup the library
1795 requirements and import them all.
1796 LIBRARY
1798 Must have 'component[/path]' format. Identifies the library to
1799 import.
1800 Returns 0 if the import of all libraries was successful. Returns non-
1802 zero if one or more library failed to import.
1803 Process Synchronisation
1805 rlWaitForCmd
1806 Pauses script execution until command exit status is the expeced value.
1808 Logs a WARNING and returns 1 if the command didn't exit successfully
1809 before timeout elapsed or a maximum number of invocations has been
1810 reached.
1811 rlWaitForCmd command [-p PID] [-t time] [-m count] [-d delay] [-r retval]
1813 command
1815 Command that will be executed until its return code is equal 0 or
1816 value speciefied as option to '-r'.
1817 -t time
1819 Timeout in seconds, default=120. If the command doesn't return 0
1820 before time elapses, the command will be killed.
1821 -p PID
1823 PID of the process to check before running command. If the process
1824 exits before the socket is opened, the command will log a WARNING.
1825 -m count
1827 Maximum number of 'command' executions before continuing anyway.
1828 Default is infite. Returns 1 if the maximum was reached.
1829 -d delay
1831 Delay between 'command' invocations. Default 1.
1832 -r retval
1834 Expected return value of command. Default 0.
1835 rlWaitForFile
1837 Pauses script execution until specified file or directory starts
1839 existing. Returns 0 if file started existing, 1 if timeout was reached
1840 or PID exited. Return code is greater than 1 in case of error.
1841 rlWaitForFile path [-p PID] [-t time] [-d delay]
1843 path
1845 Path to file that should start existing.
1846 -t time
1848 Timeout in seconds (optional, default=120). If the file isn't
1849 opened before the time elapses the command returns 1.
1850 -p PID
1852 PID of the process that should also be running. If the process
1853 exits before the file is created, the command returns with status
1854 code of 1.
1855 -d delay
1857 Delay between subsequent checks for existence of file. Default 1.
1858 rlWaitForSocket
1860 Pauses script execution until local socket starts listening. Returns 0
1862 if socket started listening, 1 if timeout was reached or PID exited.
1863 Return code is greater than 1 in case of error.
1864 rlWaitForSocket {port|path} [-p PID] [-t time] [-d delay] [--close] [--remote]
1866 port|path
1868 Network port to wait for opening or a path to UNIX socket. Regular
1869 expressions are also supported.
1870 -t time
1872 Timeout in seconds (optional, default=120). If the socket isn't
1873 opened before the time elapses the command returns 1.
1874 -p PID
1876 PID of the process that should also be running. If the process
1877 exits before the socket is opened, the command returns with status
1878 code of 1.
1879 -d delay
1881 Delay between subsequent checks for availability of socket. Default
1882 1.
1883 --close
1885 Wait for the socket to stop listening.
1886 --remote
1888 Wait for the remote socket to start listening instead of local one.
1889 rlWait
1891 Wrapper around bash builtin 'wait' command. See bash_builtins(1) man
1893 page. Kills the process and all its children if the timeout elapses.
1894 rlWaitFor [n ...] [-s SIGNAL] [-t time]
1896 n List of PIDs to wait for. They need to be background tasks of
1898 current shell. See bash_builtins(1) section for 'wait' command.
1899 -t time
1901 Timeout in seconds (optional, default=30). If the wait isn't
1902 successful before the time elapses then all specified tasks are
1903 killed.
1904 -s SIGNAL
1906 Signal used to kill the process, optional SIGTERM by default.
1907 Virtual X Server
1909 Functions providing simple way how to start and stop virtual X server.
1910 rlVirtualXStart
1912 Start a virtual X server on a first free display. Tries only first N
1914 displays, so you can run out of them.
1915 rlVirtualXStart name [N]
1917 name
1919 String identifying the X server.
1920 N Maximum number of displays to try. Defaults to 3.
1922 Returns 0 when the server is started successfully.
1924 rlVirtualXGetDisplay
1926 Get the DISPLAY variable for specified virtual X server.
1928 rlVirtualXGetDisplay name
1930 name
1932 String identifying the X server.
1933 Displays the number of display where specified virtual X server is
1935 running to standard output. Returns 0 on success.
1936 rlVirtualXStop
1938 Kill the specified X server.
1940 rlVirtualXStop name
1942 name
1944 String identifying the X server.
1945 Returns 0 when the server is stopped successfully.
1947 Example
1949 Below is a simple example of usage. Note that a lot of usefull
1951 debugging information is reported on the DEBUG level, so you can run
1952 your test with "DEBUG=1 make run" to get them.
1953 rlVirtualXStart $TEST
1955 rlAssert0 "Virtual X server started" $?
1956 export DISPLAY="$( rlVirtualXGetDisplay $TEST )"
1957 # ...your test which needs X...
1958 rlVirtualXStop $TEST
1959 rlAssert0 "Virtual X server killed" $?
1960 These are "Requires" lines for your scripts - note different package
1962 names for different RHEL versions:
1963 @echo "Requires: xorg-x11-server-Xvfb" >> $(METADATA) # RHEL-5
1965 @echo "Requires: xorg-x11-Xvfb" >> $(METADATA) # RHEL-4
1966 @echo "Requires: XFree86-Xvfb" >> $(METADATA) # RHEL-3
1967 rlYash_parse
1969 Parse yaml data to the associative array.
1971 rlYash_parse VAR_NAME YAML_DATA
1973 VAR_NAME
1975 Name of the variable to which the yaml structure will be saved.
1976 Note that the variable needs to be predeclared as an associative
1978 array.
1979 YAML_DATA
1981 The actual yaml data.
1982 Beakerlib Profiling
1984 Enable profiling
1985 Set environment variable BEAKERLIB_PROFILING=1
1987 BEAKERLIB_PROFILING=1 make run
1989 A file /dev/shm/beakerlib_profile will be created for later processing.
1991 Process the profile
1993 /usr/share/beakerlib/profiling.sh process > profile.csv
1995
1997 Location of test results related output files can be configured by
1998 setting BEAKERLIB_DIR variable before running the test. If it is not
1999 set, temporary directory is created.
2000 journal.txt
2002 Journal in human readable form.
2003 journal.xml
2005 Journal in XML format, requires python. This dependency can be avoided
2006 if the test is run with variable BEAKERLIB_JOURNAL set to 0 in which
2007 case journal.xml is not created.
2008 XSLT
2010 XML journal can be transformed through XSLT template. Which template is
2012 used is configurable by setting BEAKERLIB_JOURNAL variable. Value can
2013 be either filename in which case beakerlib will try to use
2014 $INSTALL_DIR/xslt-template/$filename (e.g.:
2015 /usr/share/beakerlib/xstl-templates/xunit.xsl) or it can be path to a
2016 template anywhere on the system.
2017 TestResults
2019 Overall results of the test in a 'sourceable' form. Each line contains
2020 a pair VAR=VALUE. All variable names have 'TESTRESULT_' prefix.
2021 List of variables:
2023 TESTRESULT_STATE - Current state of the test run; possible values:
2025 started, incomplete and complete.
2026 - 'started' is set after a Journal is opened.
2027 - 'incomplete' is set after a Phase is closed.
2028 - 'complete' is set after a Journal is closed.
2029 TESTRESULT_RESULT_STRING - Result of the test in a string, e.g.: PASS,
2031 FAIL, WARN.
2032 TESTRESULT_RESULT_ECODE - Result of the test as an integer, 0 equals to
2034 PASS.
2035 TESTRESULT_PHASES_PASSED - Number of phases that ended with PASS.
2037 TESTRESULT_PHASES_FAILED - Number of phases that ended with non-PASS
2039 result.
2040 TESTRESULT_PHASES_SKIPPED - Number of skipped phases.
2042 TESTRESULT_ASSERTS_FAILED - Number of asserts that ended with non-PASS
2044 result in the whole test.
2045 TESTRESULT_STARTTIME - Time when test started in seconds since epoch.
2047 TESTRESULT_ENDTIME - Time when test ended in seconds since epoch.
2049 TESTRESULT_DURATION - Duration of the test run in seconds.
2051 TESTRESULT_BEAKERLIB_DIR - Directory with test results files.
2053
2055 Simple
2056 A minimal BeakerLib test can look like this:
2057 . /usr/share/beakerlib/beakerlib.sh
2059 rlJournalStart
2061 rlPhaseStartTest
2062 rlAssertRpm "setup"
2063 rlAssertExists "/etc/passwd"
2064 rlAssertGrep "root" "/etc/passwd"
2065 rlPhaseEnd
2066 rlJournalEnd
2067 Phases
2069 Here comes a bit more interesting example of a test which sets all the
2070 recommended variables and makes use of the phases:
2071 # Include the BeakerLib environment
2073 . /usr/share/beakerlib/beakerlib.sh
2074 # Set the full test name
2076 TEST="/examples/beakerlib/Sanity/phases"
2077 # Package being tested
2079 PACKAGE="coreutils"
2080 rlJournalStart
2082 # Setup phase: Prepare test directory
2083 rlPhaseStartSetup
2084 rlAssertRpm $PACKAGE
2085 rlRun 'TmpDir=$(mktemp -d)' 0 'Creating tmp directory' # no-reboot
2086 rlRun "pushd $TmpDir"
2087 rlPhaseEnd
2088 # Test phase: Testing touch, ls and rm commands
2090 rlPhaseStartTest
2091 rlRun "touch foo" 0 "Creating the foo test file"
2092 rlAssertExists "foo"
2093 rlRun "ls -l foo" 0 "Listing the foo test file"
2094 rlRun "rm foo" 0 "Removing the foo test file"
2095 rlAssertNotExists "foo"
2096 rlRun "ls -l foo" 2 "Listing foo should now report an error"
2097 rlPhaseEnd
2098 # Cleanup phase: Remove test directory
2100 rlPhaseStartCleanup
2101 rlRun "popd"
2102 rlRun "rm -r $TmpDir" 0 "Removing tmp directory"
2103 rlPhaseEnd
2104 rlJournalEnd
2105 # Print the test report
2107 rlJournalPrintText
2108 The ouput of the rlJournalPrintText command would produce an output
2110 similar to the following:
2111 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2113 :: TEST PROTOCOL
2114 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2115 Package : coreutils
2117 Installed : coreutils-8.27-19.fc27.x86_64
2118 beakerlib RPM : beakerlib-1.17-6.fc27.noarch
2119 Test started : 2018-02-08 15:43:03 CET
2120 Test finished : 2018-02-08 15:43:04 CET
2121 Test duration : 1 seconds
2122 Test name : /examples/beakerlib/Sanity/phases
2123 Distro : Fedora release 27 (Twenty Seven)
2124 Hostname : localhost
2125 Architecture : x86_64
2126 CPUs : 4 x Intel Core Processor (Skylake)
2127 RAM size : 1992 MB
2128 HDD size : 17.55 GB
2129 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2131 :: Test description
2132 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2133 PURPOSE of /examples/beakerlib/Sanity/phases
2135 Description: Testing BeakerLib phases
2136 Author: Petr Splichal <psplicha@redhat.com>
2137 This example shows how the phases work in the BeakerLib on a
2139 trivial smoke test for the "touch", "ls" and "rm" commands from
2140 the coreutils package.
2141 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2145 :: Setup
2146 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2147 :: [ 15:43:03 ] :: [ PASS ] :: Checking for the presence of coreutils rpm
2149 :: [ 15:43:03 ] :: [ LOG ] :: Package versions:
2150 :: [ 15:43:03 ] :: [ LOG ] :: coreutils-8.27-19.fc27.x86_64
2151 :: [ 15:43:03 ] :: [ PASS ] :: Creating tmp directory (Expected 0, got 0)
2152 :: [ 15:43:03 ] :: [ PASS ] :: Command 'pushd /tmp/tmp.MMQf7dj9QV' (Expected 0, got 0)
2153 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2154 :: Duration: 1s
2155 :: Assertions: 3 good, 0 bad
2156 :: RESULT: PASS
2157 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2160 :: Test
2161 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2162 :: [ 15:43:04 ] :: [ PASS ] :: Creating the foo test file (Expected 0, got 0)
2164 :: [ 15:43:04 ] :: [ PASS ] :: File foo should exist
2165 :: [ 15:43:04 ] :: [ PASS ] :: Listing the foo test file (Expected 0, got 0)
2166 :: [ 15:43:04 ] :: [ PASS ] :: Removing the foo test file (Expected 0, got 0)
2167 :: [ 15:43:04 ] :: [ PASS ] :: File foo should not exist
2168 :: [ 15:43:04 ] :: [ PASS ] :: Listing foo should now report an error (Expected 2, got 2)
2169 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2170 :: Duration: 0s
2171 :: Assertions: 6 good, 0 bad
2172 :: RESULT: PASS
2173 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2176 :: Cleanup
2177 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2178 :: [ 15:43:04 ] :: [ PASS ] :: Command 'popd' (Expected 0, got 0)
2180 :: [ 15:43:04 ] :: [ PASS ] :: Removing tmp directory (Expected 0, got 0)
2181 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2182 :: Duration: 0s
2183 :: Assertions: 2 good, 0 bad
2184 :: RESULT: PASS
2185 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2188 :: /examples/beakerlib/Sanity/phases
2189 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2190 :: [ 15:43:04 ] :: [ LOG ] :: JOURNAL XML: /var/tmp/beakerlib-pRiJfWE/journal.xml
2192 :: [ 15:43:04 ] :: [ LOG ] :: JOURNAL TXT: /var/tmp/beakerlib-pRiJfWE/journal.txt
2193 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2194 :: Duration: 1s
2195 :: Phases: 3 good, 0 bad
2196 :: OVERALL RESULT: PASS
2197 Note that the detailed test description is read from a separate file
2199 PURPOSE placed in the same directory as the test itself.
2200 A lot of useful debugging information is reported on the DEBUG level.
2202 You can run your test with "DEBUG=1 make run" to get them.
2203 Verbosity of the test logging may be altered also by setting the
2205 LOG_LEVEL variable. Possible values are "ERROR", "WARNING", "INFO" and
2206 "DEBUG". You will see messages like the ones below.
2207 :: [ WARNING ] :: rlGetArch: Update test to use rlGetPrimaryArch/rlGetSecondaryArch
2209 :: [ DEBUG ] :: rlGetArch: This is architecture 'x86_64'
2210 :: [ ERROR ] :: this function was dropped as its development is completely moved to the beaker library
2211 :: [ INFO ] :: if you realy on this function and you really need to have it present in core beakerlib, file a RFE, please
2212 Setting LOG_LEVEL="DEBUG" is equivalent to DEBUG=1.
2214 Set DEBUG_TO_CONSOLE_ONLY=1 in conjuction with DEBUG=1 to avoid storing
2216 debug messages in journal. This also speeds up the execution in debug
2217 mode as those messages are not fully processed than.
2218
2220 Description
2221 Bkrdoc is a documentation generator from tests written using
2222 BeakerLib library. This generator makes documentation from test
2223 code with and also without any documentation markup.
2224 What it's good for
2226 For fast, brief and reliable documentation creation. It`s good for
2227 quick start with unknown BeakerLib test. Created documentations
2228 provides information about the documentation credibility. Also
2229 created documentations shows environmental variables and helps
2230 reader to run test script from which was documentation created.
2231 Bkrdoc project page
2233 https://github.com/rh-lab-q/bkrdoc
2234
2236 Project Page
2237 https://github.com/beakerlib/beakerlib
2238 Manual
2240 https://github.com/beakerlib/beakerlib/wiki/man
2241 Issues list
2243 https://bugzilla.redhat.com/buglist.cgi?component=beakerlib&&order=bug_status%2Cassigned_to%2Cpriority
2244 https://github.com/beakerlib/beakerlib/issues
2246 Reporting issues
2248 https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora&component=beakerlib
2249 https://github.com/beakerlib/beakerlib/issues/new
2251
2253 • Petr Muller <pmuller@redhat.com>
2254 • Ondrej Hudlicky <ohudlick@redhat.com>
2256 • Jan Hutar <jhutar@redhat.com>
2258 • Petr Splichal <psplicha@redhat.com>
2260 • Ales Zelinka <azelinka@redhat.com>
2262 • Dalibor Pospisil <dapospis@redhat.com>
2264 • Martin Kyral <mkyral@redhat.com>
2266 • Jakub Prokes <jprokes@redhat.com>
2268 • Jakub Heger <jheger@redhat.com>
2270perl v5.34.0 2022-01-19 BEAKERLIB(1)