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 options is now deprecated, has no effect and will be removed in
109 one of future versions.
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 in so far, 255 if there are more then
153 255 failures. The precise number is set to ECODE variable.
154 rlGetTestState
156 rlGetPhaseState
158 Returns number of failed asserts in current phase so far, 255 if there
160 are more then 255 failures. The precise number is set to ECODE
161 variable.
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 not existent 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 a part of the tar-ball name.
223 file
225 File(s) to be packed and submitted.
226 Returns result of submiting the tarball.
228 rlFileSubmit
230 Resolves absolute path to the file, replaces / for - 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 X 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 strigs '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 commands 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. Caller is responsible for removing the file. When -t
684 option is used, the content of the file becomes tagged too.
685 If the -s option is not used, $rlRun_LOG is not modified and keeps
687 its content from the last "rlRun -s".
688 command
690 Command to run.
691 status
693 Expected exit code(s). Optional, default 0. If you expect more exit
694 codes, separate them with comma (e.g. "0,1" when both 0 and 1 are
695 OK and expected), or use from-to notation (i.e. "2-5" for
696 "2,3,4,5"), or combine them (e.g. "2-4,26" for "2,3,4,26").
697 comment
699 Short summary describing the action (optional, but recommended -
700 explain what are you doing here).
701 Returns the exit code of the command run. Asserts PASS when command\'s
703 exit status is in the list of expected exit codes.
704 Note:
706 · The output of rlRun is buffered when using "-t", "-l" or "-s"
708 option (they use unix pipes, which are buffered by nature). If you
709 need an unbuffered output just make sure that "expect" package is
710 installed on your system (its "unbuffer" tool will automatically be
711 used to produce unbuffered output).
712 · Be aware that there are some variables which can collide with your
714 code executed within rlRun. You should avoid using
715 __INTERNAL_rlRun_* variables.
716 · When any of "-t" "-l", "-c", or "-s" option is used, special file
718 descriptors 111 and 112 are used to avoid the issue with incomplete
719 log file, bz1361246. As there might be an indefinite loop, there's
720 a timeout of two minutes implemented as a fix for bz1416796. Also
721 an error message is issued to signal the possibility of running
722 subprocess which keeps the file descriptors open.
723 Do not use these options if you expect process forking and
725 continuouse run. Try your own apropriate solution instead.
726 Warning: using "unbuffer" tool is now disabled because of bug 547686.
728 rlWatchdog
730 Run "command". If it does not finish in specified time, then kill it
732 using "signal".
733 rlWatchdog command timeout [signal] [callback]
735 command
737 Command to run.
738 timeout
740 Timeout to wait, in seconds.
741 signal
743 Signal to use (optional, default KILL).
744 callback
746 Callback function to be called before the signal is send (optional,
747 none by default). The callback function will have one argument
748 available -- PGID of the process group.
749 Returns 0 if the command ends normally, without need to be killed.
751 rlReport
753 Report test result to the test harness. The command to be used for
755 reporting is set by the respective plugin. You can also use the
756 $BEAKERLIB_COMMAND_REPORT_RESULT variable to use your custom command.
757 rlReport name result [score] [log]
759 name
761 Name of the test result.
762 result
764 Result (one of PASS, WARN, FAIL). If called with something else,
765 will use WARN.
766 score
768 Test score (optional).
769 log Optional log file to be submitted instead of default "OUTPUTFILE".
771 rlCmpVersion
773 Compare two given versions composed by numbers and letters divided by
775 dot (.), underscore (_), or dash (-).
776 rlCmpVersion ver1 ver2
778 If ver1 = ver2, sign '=' is printed to stdout and 0 is returned. If
780 ver1 > ver2, sign '>' is printed to stdout and 1 is returned. If ver1
781 < ver2, sign '<' is printed to stdout and 2 is returned.
782 rlTestVersion
784 Test releation between two given versions based on given operator.
786 rlTestVersion ver1 op ver2
788 op Operator defining the logical expression. It can be '=', '==',
790 '!=', '<', '<=', '=<', '>', '>=', or '=>'.
791 Returns 0 if the expresison ver1 op ver2 is true; 1 if the expression
793 is false and 2 if something went wrong.
794 Release Info
796 rlIsRHEL
797 rlIsRHEL [Num|opNum]
799 Num When used function returns 0 if the particular RHEL version is
801 running. Multiple arguments can be passed separated with space as
802 well as any particular release (5.1 5.2 5.3).
803 opNum
805 Argument consisting of operator and number written together as one
806 string. Operator can be '<', '<=', '=<', '=', '>', '>=' matching
807 whether the currently installed version is lesser, lesser or equal,
808 equal, equal or greater, greater than the version number supplied
809 as second half of the argument. Note that ie. '=5' (unlike just
810 '5') matches exactly 5 (5.0), not 5.N, where N > 0. Also note when
811 that using >/< operators you have to either put the argument in
812 quotes or escape the operators to avoid them being interpreted as
813 bash redirection operator.
814 Returns 0 when we're running on RHEL.
816 Note that
818 rlIsRHEL '<6.9' || rlIsRHEL '<7.5'
820 would also cover 6.10 as it is less than 7.5, which is not what you
822 want. So if you want to construct a condition for rhel<6.9 for rhel6
823 or rhel<7.5 for rhel7 you actually need to use following construct:
824 rlIsRHEL 6 && rlIsRHEL '<6.9' || rlIsRHEL 7 && rlIsRHEL '<7.5'
826 Prototype:
828 rlIsRHEL
830 Returns 0 if we are running on RHEL.
832 rlIsRHEL 4.8 5
834 Returns 0 if we are running RHEL 4.8 or any RHEL 5.
836 rlIsRHEL ">=6" or rlIsRHEL \>=6
838 Returns 0 if we are running RHEL 6 or higher.
840 rlIsFedora
842 rlIsFedora [Num|opNum]
844 Returns 0 when we're running on Fedora. With given number of version
846 as parameter returns 0 if the particular Fedora version is running.
847 Range matching can be used in the form used by rlIsRHEL.
848 rlIsFedora
850 Returns 0 if we are running on Fedora.
852 rlIsFedora 9 10
854 Returns 0 if we are running Fedora 9 or 10.
856 Release Info
858 rlIsCentOS
859 rlIsCentOS [Num|opNum]
861 Returns 0 when we're running on CentOS. With given number of version
863 as parameter returns 0 if the particular CentOS version is running.
864 Range matching can be used in the form used by rlIsRHEL.
865 rlIsCentOS
867 Returns 0 if we are running on CentOS.
869 rlIsCentOS 7.1 6
871 Returns 0 if we are running CentOS 7.1 or any CentOS 6.
873 Rpm Handling
875 rlCheckRpm
876 Check whether a package is installed.
878 rlCheckRpm name [version] [release] [arch]
880 name
882 Package name like "kernel"
883 version
885 Package version like 2.6.25.6
886 release
888 Package release like "55.fc9"
889 arch
891 Package architucture like "i386"
892 Returns 0 if the specified package is installed.
894 rlAssertRpm
896 Assertion making sure that a package is installed.
898 rlAssertRpm name [version] [release] [arch]>
900 rlAssertRpm --all
901 name
903 Package name like "kernel"
904 version
906 Package version like 2.6.25.6
907 release
909 Package release like "55.fc9"
910 arch
912 Package architucture like "i386"
913 --all
915 Assert all packages listed in the $PACKAGES $REQUIRES and
916 $COLLECTIONS environment variables.
917 Returns 0 and asserts PASS if the specified package is installed.
919 rlAssertNotRpm
921 Assertion making sure that a package is not installed. This is just
923 inverse of "rlAssertRpm".
924 rlAssertNotRpm name [version] [release] [arch]>
926 name
928 Package name like "kernel"
929 version
931 Package version like 2.6.25.6
932 release
934 Package release like "55.fc9"
935 arch
937 Package architucture like "i386"
938 Returns 0 and asserts PASS if the specified package is not installed.
940 Example
942 Function "rlAssertRpm" is useful especially in prepare phase where it
944 causes abort if a package is missing, while "rlCheckRpm" is handy when
945 doing something like:
946 if ! rlCheckRpm package; then
948 yum install package
949 rlAssertRpm package
950 fi
951 rlAssertBinaryOrigin
953 Assertion making sure that given binary is owned by (one of) the given
955 package(s).
956 rlAssertBinaryOrigin binary package [package2 [...]]
958 PACKAGES=... rlAssertBinaryOrigin binary
959 binary
961 Binary name like "ksh" or "/bin/ksh"
962 package
964 List of packages like "ksh mksh". The parameter is optional. If
965 missing, contents of environment variable $PACKAGES are taken into
966 account.
967 Returns 0 and asserts PASS if the specified binary belongs to (one of)
969 the given package(s). Returns 1 and asserts FAIL if the specified
970 binary does not belong to (any of) the given package(s). Returns 2 and
971 asserts FAIL if the specified binary is not found. Returns 3 and
972 asserts FAIL if no packages are given. Returns 100 and asserts FAIL if
973 invoked with no parameters.
974 Example
976 Function "rlAssertBinaryOrigin" is useful especially in prepare phase
978 where it causes abort if a binary is missing or is owned by different
979 package:
980 PACKAGES=mksh rlAssertBinaryOrigin ksh
982 or
983 rlAssertBinaryOrigin ksh mksh
984 Returns true if ksh is owned by the mksh package (in this case:
986 /bin/ksh is a symlink pointing to /bin/mksh).
987 rlGetMakefileRequires
989 Prints comma separated list of requirements defined in Makefile using
991 'Requires' attribute.
992 Return 0 if success.
994 rlCheckRequirements
996 Check that all given requirements are covered eigther by installed
998 package or by binary available in PATHs or by some package's provides.
999 rlRun "rlCheckRequirements REQ..."
1001 REQ Requirement to be checked. It can be package name, provides string
1003 or binary name.
1004 Returns number of unsatisfied requirements.
1006 rlCheckMakefileRequires
1008 This is just a bit smarted wrapper of
1010 "rlCheckRequirements $(rlGetMakefileRequires)"
1012 Example
1014 rlRun "rlCheckMakefileRequires"
1016 Return 255 if requirements could not be retrieved, 0 if all
1018 requirements are satisfied or number of unsatisfied requirements.
1019 rlAssertRequired
1021 Ensures that all Requires, specified in beakerlib-style beaker-wizard
1023 layout Makefile, are installed.
1024 rlAssertRequired
1026 Prints out a verbose list of installed/missing packages during
1028 operation.
1029 Returns 0 if all required packages are installed, 1 if one or more
1031 packages are missing or if no Makefile is present.
1032 Getting RPMs
1034 Download methods
1035 Functions handling rpm downloading/installing can use more methods for
1037 actual download of the rpm.
1038 Currently there are two download methonds available:
1040 direct
1042 Use use dirct download from build system (brew).
1043 yum Use yumdownloader or dnf download.
1045 The methods and their order are defined by
1047 BEAKERLIB_RPM_DOWNLOAD_METHODS variable as space separated list. By
1048 default it is 'direct yum'. This can be overridden by user. There may
1049 be done also additions or changes to the original value, e.g.
1050 BEAKERLIB_RPM_DOWNLOAD_METHODS='yum
1051 ${BEAKERLIB_RPM_DOWNLOAD_METHODS/yum/}'
1052 Beakerlib is prepared for more Koji-based sources of packages while
1056 usigng direct download method. By default packages are fetched from
1057 Koji, particularly from https://kojipkgs.fedoraproject.org/packages.
1058 rlRpmInstall
1060 Try to install specified package from local Red Hat sources.
1062 rlRpmInstall [--quiet] package version release arch
1064 --quiet
1066 Make the download and the install process be quiet.
1067 package
1069 Package name like "kernel"
1070 version
1072 Package version like 2.6.25.6
1073 release
1075 Package release like "55.fc9"
1076 arch
1078 Package arch like "i386"
1079 Returns 0 if specified package was installed succesfully.
1081 rlRpmDownload
1083 Try to download specified package.
1085 rlRpmDownload [--quiet] {package version release arch|N-V-R.A}
1087 rlRpmDownload [--quiet] --source {package version release|N-V-R}
1088 --quiet
1090 Make the download process be quiet.
1091 package
1093 Package name like "kernel"
1094 version
1096 Package version like 2.6.25.6
1097 release
1099 Package release like "55.fc9"
1100 arch
1102 Package arch like "i386"
1103 Returns 0 if specified package was downloaded succesfully.
1105 rlFetchSrcForInstalled
1107 Tries various ways to download source rpm for specified installed rpm.
1109 rlFetchSrcForInstalled [--quiet] package
1111 --quiet
1113 Make the download process be quiet.
1114 package
1116 Installed package name like "kernel". It accepts in-direct names.
1117 Eg for the package name "krb5-libs" will the function download the
1118 "krb5" source rpm.
1119 Returns 0 if the source package was succesfully downloaded.
1121 Mounting
1123 rlMount
1124 Create mount point (if neccessary) and mount a NFS share.
1126 rlMount [-o MOUNT_OPTS] server share mountpoint
1128 server
1130 NFS server hostname.
1131 share
1133 Shared directory name.
1134 mountpoint
1136 Local mount point.
1137 MOUNT_OPTS
1139 Mount options.
1140 Returns 0 if mounting the share was successful.
1142 rlCheckMount
1144 Check either if a directory is a mountpoint, if it is a mountpoint to a
1146 specific server, or if it is a mountpoint to a specific export on a
1147 specific server and if it uses specific mount options.
1148 rlCheckMount [-o MOUNT_OPTS] mountpoint
1150 rlCheckMount [-o MOUNT_OPTS] server mountpoint
1151 rlCheckMount [-o MOUNT_OPTS] server share mountpoint
1152 mountpoint
1154 Local mount point.
1155 server
1157 NFS server hostname
1158 share
1160 Shared directory name
1161 MOUNT_OPTS
1163 Mount options to check (comma separated list)
1164 With one parameter, returns 0 when specified directory exists and is a
1166 mountpoint. With two parameters, returns 0 when specific directory
1167 exists, is a mountpoint and an export from specific server is mounted
1168 there. With three parameters, returns 0 if a specific shared directory
1169 is mounted on a given server on a given mountpoint
1170 If the -o option is provided, returns 0 if the mountpoint uses all the
1172 given options, 2 otherwise.
1173 rlAssertMount
1175 Assertion making sure that given directory is a mount point, if it is a
1177 mountpoint to a specific server, or if it is a mountpoint to a specific
1178 export on a specific server and if it uses specific mount options.
1179 rlAssertMount [-o MOUNT_OPTS] mountpoint
1181 rlAssertMount [-o MOUNT_OPTS] server mountpoint
1182 rlAssertMount [-o MOUNT_OPTS] server share mountpoint
1183 mountpoint
1185 Local mount point.
1186 server
1188 NFS server hostname
1189 share
1191 Shared directory name
1192 MOUNT_OPTS
1194 Mount options to check (comma separated list)
1195 With one parameter, returns 0 when specified directory exists and is a
1197 mountpoint. With two parameters, returns 0 when specific directory
1198 exists, is a mountpoint and an export from specific server is mounted
1199 there. With three parameters, returns 0 if a specific shared directory
1200 is mounted on a given server on a given mountpoint. Asserts PASS when
1201 the condition is true.
1202 If the -o option is provided, asserts PASS if the above conditions are
1204 met and the mountpoint uses all the given options.
1205 rlHash, rlUnhash
1207 Hashes/Unhashes given string and prints the result to stdout.
1209 rlHash [--decode] [--algorithm HASH_ALG] --stdin|STRING
1211 rlUnhash [--algorithm HASH_ALG] --stdin|STRING
1212 --decode
1214 Unhash given string.
1215 --algorithm
1217 Use given hash algorithm. Currently supported algorithms:
1218 base64
1219 base64_ - this is standard base64 where '=' is replaced by '_'
1220 hex
1221 Defaults to hex. Default algorithm can be override using global
1223 variable rlHashAlgorithm.
1224 --stdin
1226 Get the string from stdin.
1227 STRING
1229 String to be hashed/unhashed.
1230 Returns 0 if success.
1232 Backup and Restore
1234 rlFileBackup
1235 Create a backup of files or directories (recursive). Can be used
1237 multiple times to add more files to backup. Backing up an already
1238 backed up file overwrites the original backup.
1239 rlFileBackup [--clean] [--namespace name] [--missing-ok|--no-missing-ok] file [file...]
1241 You can use "rlRun" for asserting the result but keep in mind meaning
1243 of exit codes, especialy exit code 8, if using without --clean option.
1244 --clean
1246 If this option is provided (have to be first option of the
1247 command), then file/dir backuped using this command (provided in
1248 next options) will be (recursively) removed before we will restore
1249 it. This option implies --missing-ok, this can be overridden by
1250 --no-missing-ok.
1251 --namespace name
1253 Specifies the namespace to use. Namespaces can be used to separate
1254 backups and their restoration.
1255 --missing-ok
1257 Do not raise an error in case of missing file to backup.
1258 --no-missing-ok
1260 Do raise an error in case of missing file to backup. This is
1261 useful with --clean. This behaviour can be globally set by global
1262 variable BEAKERLIB_FILEBACKUP_MISSING_OK=false.
1263 file
1265 Files and/or directories to be backed up.
1266 Returns 0 if the backup was successful. Returns 1 if parsing of
1268 parameters was not successful. Returns 2 if no files specification was
1269 provided. Returns 3 if BEAKERLIB_DIR variable is not set, e.g.
1270 rlJournalStart was not executed. Returns 4 if creating of main backup
1271 destination directories was not successful. Returns 5 if creating of
1272 file specific backup destination directories was not successful.
1273 Returns 6 if the copy of backed up files was not successful. Returns 7
1274 if attributes of backedup files were not successfuly copied. Returns 8
1275 if backed up files do not exist. This can be suppressed based on other
1276 options.
1277 Example with --clean:
1279 touch cleandir/aaa
1281 rlRun "rlFileBackup --clean cleandir/"
1282 touch cleandir/bbb
1283 ls cleandir/
1284 aaa bbb
1285 rlRun "rlFileRestore"
1286 ls cleandir/
1287 aaa
1288 rlFileRestore
1290 Restore backed up files to their original location. "rlFileRestore"
1292 does not remove new files appearing after backup has been made. If you
1293 don't want to leave anything behind just remove the whole original tree
1294 before running "rlFileRestore", or see "--clean" option of
1295 "rlFileBackup".
1296 rlFileRestore [--namespace name]
1298 You can use "rlRun" for asserting the result.
1300 --namespace name
1302 Specifies the namespace to use. Namespaces can be used to separate
1303 backups and their restoration.
1304 Returns 0 if backup dir is found and files are restored successfully.
1306 Return code bits meaning XXXXX
1308 |||||
1309 ||||\_ error parsing parameters
1310 |||\__ could not find backup directory
1311 ||\___ files cleanup failed
1312 |\____ files restore failed
1313 \_____ no files were restored nor cleaned
1314 Services
1316 Following routines implement comfortable way how to start/stop system
1317 services with the possibility to restore them to their original state
1318 after testing.
1319 rlServiceStart
1321 Make sure the given "service" is running with fresh configuration.
1323 (Start it if it is stopped and restart if it is already running.) In
1324 addition, when called for the first time, the current state is saved so
1325 that the "service" can be restored to its original state when testing
1326 is finished, see "rlServiceRestore".
1327 rlServiceStart service [service...]
1329 service
1331 Name of the service(s) to start.
1332 Returns number of services which failed to start/restart; thus zero is
1334 returned when everything is OK.
1335 rlServiceStop
1337 Make sure the given "service" is stopped. Stop it if it is running and
1339 do nothing when it is already stopped. In addition, when called for the
1340 first time, the current state is saved so that the "service" can be
1341 restored to its original state when testing is finished, see
1342 "rlServiceRestore".
1343 rlServiceStop service [service...]
1345 service
1347 Name of the service(s) to stop.
1348 Returns number of services which failed to become stopped; thus zero is
1350 returned when everything is OK.
1351 rlServiceRestore
1353 Restore given "service" into its original state (before the first
1355 "rlServiceStart" or "rlServiceStop" was called). If "rlServiceStart"
1356 was called on already running "service", "rlServiceRestore" will
1357 restart the "service" when restoring its state.
1358 rlServiceRestore [service...]
1360 service
1362 Name of the service(s) to restore to original state. All services
1363 will be restored in reverse order if no service name is given.
1364 Returns number of services which failed to get back to their original
1366 state; thus zero is returned when everything is OK.
1367 rlServiceEnable
1369 Enables selected services if needed, or does nothing if already
1371 enabled. In addition, when called for the first time, the current
1372 state is saved so that the "service" can be restored to its original
1373 state when testing is finished, see "rlServiceRestore".
1374 rlServiceEnable service [service...]
1376 service
1378 Name of the service(s) to enable.
1379 Returns number of services which failed enablement; thus zero is
1381 returned when everything is OK.
1382 rlServiceDisable
1384 Disables selected services if needed, or does nothing if already
1386 disabled. In addition, when called for the first time, the current
1387 state is saved so that the "service" can be restored to its original
1388 state when testing is finished, see "rlServiceRestore".
1389 rlServiceDisable service [service...]
1391 service
1393 Name of the service(s) to disable.
1394 Returns number of services which failed disablement; thus zero is
1396 returned when everything is OK.
1397 Sockets
1399 Following routines implement comfortable way how to start/stop system
1400 sockets with the possibility to restore them to their original state
1401 after testing.
1402 rlSocketStart
1404 Make sure the given "socket" is running. (Start it if stopped, leave it
1406 if already running.) In addition, when called for the first time, the
1407 current state is saved so that the "socket" can be restored to its
1408 original state when testing is finished, see "rlSocketRestore".
1409 rlSocketStart socket [socket...]
1411 socket
1413 Name of the socket(s) to start.
1414 Returns number of sockets which failed to start/restart; thus zero is
1416 returned when everything is OK.
1417 rlSocketStop
1419 Make sure the given "socket" is stopped. Stop it if it is running and
1421 do nothing when it is already stopped. In addition, when called for the
1422 first time, the current state is saved so that the "socket" can be
1423 restored to its original state when testing is finished, see
1424 "rlSocketRestore".
1425 rlSocketStop socket [socket...]
1427 socket
1429 Name of the socket(s) to stop.
1430 Returns number of sockets which failed to become stopped; thus zero is
1432 returned when everything is OK.
1433 rlSocketRestore
1435 Restore given "socket" into its original state (before the first
1437 "rlSocketStart" or "rlSocketStop" was called).
1438 Warning !!! Xinetd process [even though it might have been used] is
1440 NOT restored. It is recommended to call rlServiceRestore xinetd as
1441 well.
1442 rlSocketRestore socket [socket...]
1444 socket
1446 Name of the socket(s) to restore to original state.
1447 Returns number of sockets which failed to get back to their original
1449 state; thus zero is returned when everything is OK.
1450 Cleanup management
1452 Cleanup management works with a so-called cleanup buffer, which is a
1453 temporary representation of what should be run at cleanup time, and a
1454 final cleanup script (executable), which is generated from this buffer
1455 and wraps it using BeakerLib essentials (journal initialization,
1456 cleanup phase, ...). The cleanup script must always be updated on an
1457 atomic basis (filesystem-wise) to allow an asynchronous execution by a
1458 third party (ie. test watcher).
1459 The test watcher usage is mandatory for the cleanup management system
1461 to work properly as it is the test watcher that executes the actual
1462 cleanup script. Limited, catastrophe-avoiding mechanism is in place
1463 even when the test is not run in test watcher, but that should be seen
1464 as a backup and such situation is to be avoided whenever possible.
1465 The cleanup script shares all environment (variables, exported or not,
1467 and functions) with the test itself - the cleanup append/prepend
1468 functions "sample" or "snapshot" the environment at the time of their
1469 call, IOW any changes to the test environment are synchronized to the
1470 cleanup script only upon calling append/prepend. When the
1471 append/prepend functions are called within a function which has local
1472 variables, these will appear as global in the cleanup.
1473 While the cleanup script receives $PWD from the test, its working dir
1475 is set to the initial test execution dir even if $PWD contains
1476 something else. It is impossible to use relative paths inside cleanup
1477 reliably - certain parts of the cleanup might have been added under
1478 different current directories (CWDs). Therefore always use absolute
1479 paths in append/prepend cleanup or make sure you never 'cd' elsewhere
1480 (ie. to a TmpDir).
1481 rlCleanupAppend
1483 Appends a string to the cleanup buffer and recreates the cleanup
1485 script.
1486 rlCleanupAppend string
1488 Returns 0 if the operation was successful, 1 otherwise.
1490 rlCleanupPrepend
1492 Prepends a string to the cleanup buffer and recreates the cleanup
1494 script.
1495 rlCleanupPrepend string
1497 Returns 0 if the operation was successful, 1 otherwise.
1499 Time Performance
1501 rlPerfTime_RunsInTime
1502 Measures, how many runs of some commands can be done in specified time.
1504 This approach is suitable for short-time running tasks (up to few
1505 seconds), where averaging few runs is not precise. This is done several
1506 times, and the final result is the average of all runs. It prints the
1507 number on stdout, so it has to be captured.
1508 rlPerfTime_RunsInTime command [time] [runs]
1510 command
1512 Command to run.
1513 time
1515 Time in seconds (optional, default=30).
1516 runs
1518 Number of averaged runs (optional, default=3).
1519 rlPerfTime_AvgFromRuns
1521 Measures the average time of running some task. This approach is
1523 suitable for long-time running tasks (tens of seconds and more), where
1524 it is precise enough. Measured runs can be preceded by dry run, which
1525 is not measured and it's purpose is to warm up various caches. It
1526 prints the number on stdout, so it has to be captured. Or, result is
1527 then stored in special rl_retval variable.
1528 rlPerfTime_AvgFromRuns command [count] [warmup]
1530 command
1532 Command to run.
1533 count
1535 Times to run (optional, default=3).
1536 warmup
1538 Warm-up run, run if this option is not "warmup" (optional,
1539 default="warmup")
1540 Analyze
1542 rlDejaSum
1543 TODO description
1545 rlDejaSum par1 par2
1547 par1
1549 TODO description
1550 par2
1552 TODO description
1553 Return 0 if... TODO
1555 rlImport
1557 Imports code provided by one or more libraries into the test namespace.
1559 The library search mechanism is based on Beaker test hierarchy system,
1560 i.e.:
1561 /component/type/test-name/test-file
1563 When test-file calls rlImport with 'foo/bar' parameter, the directory
1565 path is traversed upwards, and a check for presence of the test
1566 /foo/Library/bar/ will be performed. This means this function needs to
1567 be called from the test hierarchy, not e.g. the /tmp directory.
1568 Once library is found, it is sourced and a verifier function is called.
1570 The verifier function is cunstructed by composing the library prefix
1571 and LibraryLoaded. Library prefix can be defined in the library itself.
1572 If the verifier passes the library is ready to use. Also variable
1573 <PREFIX>LibraryDir is created and it points to the library folder.
1574 Usage:
1576 rlImport --all
1578 rlImport LIBRARY [LIBRARY2...]
1579 --all
1581 Read Makefile in current/original directory, pick library
1582 requirements up and import them all.
1583 LIBRARY
1585 Must have 'component/library' format. Identifies the library to
1586 import.
1587 Returns 0 if the import of all libraries was successful. Returns non-
1589 zero if one or more library failed to import.
1590 Process Synchronisation
1592 rlWaitForCmd
1593 Pauses script execution until command exit status is the expeced value.
1595 Logs a WARNING and returns 1 if the command didn't exit successfully
1596 before timeout elapsed or a maximum number of invocations has been
1597 reached.
1598 rlWaitForCmd command [-p PID] [-t time] [-m count] [-d delay] [-r retval]
1600 command
1602 Command that will be executed until its return code is equal 0 or
1603 value speciefied as option to `-r'.
1604 -t time
1606 Timeout in seconds, default=120. If the command doesn't return 0
1607 before time elapses, the command will be killed.
1608 -p PID
1610 PID of the process to check before running command. If the process
1611 exits before the socket is opened, the command will log a WARNING.
1612 -m count
1614 Maximum number of `command' executions before continuing anyway.
1615 Default is infite. Returns 1 if the maximum was reached.
1616 -d delay
1618 Delay between `command' invocations. Default 1.
1619 -r retval
1621 Expected return value of command. Default 0.
1622 rlWaitForFile
1624 Pauses script execution until specified file or directory starts
1626 existing. Returns 0 if file started existing, 1 if timeout was reached
1627 or PID exited. Return code is greater than 1 in case of error.
1628 rlWaitForFile path [-p PID] [-t time] [-d delay]
1630 path
1632 Path to file that should start existing.
1633 -t time
1635 Timeout in seconds (optional, default=120). If the file isn't
1636 opened before the time elapses the command returns 1.
1637 -p PID
1639 PID of the process that should also be running. If the process
1640 exits before the file is created, the command returns with status
1641 code of 1.
1642 -d delay
1644 Delay between subsequent checks for existence of file. Default 1.
1645 rlWaitForSocket
1647 Pauses script execution until local socket starts listening. Returns 0
1649 if socket started listening, 1 if timeout was reached or PID exited.
1650 Return code is greater than 1 in case of error.
1651 rlWaitForSocket {port|path} [-p PID] [-t time] [-d delay] [--close] [--remote]
1653 port|path
1655 Network port to wait for opening or a path to UNIX socket. Regular
1656 expressions are also supported.
1657 -t time
1659 Timeout in seconds (optional, default=120). If the socket isn't
1660 opened before the time elapses the command returns 1.
1661 -p PID
1663 PID of the process that should also be running. If the process
1664 exits before the socket is opened, the command returns with status
1665 code of 1.
1666 -d delay
1668 Delay between subsequent checks for availability of socket. Default
1669 1.
1670 --close
1672 Wait for the socket to stop listening.
1673 --remote
1675 Wait for the remote socket to start listening instead of local one.
1676 rlWait
1678 Wrapper around bash builtin `wait' command. See bash_builtins(1) man
1680 page. Kills the process and all its children if the timeout elapses.
1681 rlWaitFor [n ...] [-s SIGNAL] [-t time]
1683 n List of PIDs to wait for. They need to be background tasks of
1685 current shell. See bash_builtins(1) section for `wait' command/
1686 -t time
1688 Timeout in seconds (optional, default=30). If the wait isn't
1689 successful before the time elapses then all specified tasks are
1690 killed.
1691 -s SIGNAL
1693 Signal used to kill the process, optional SIGTERM by default.
1694 Virtual X Server
1696 Functions providing simple way how to start and stop virtual X server.
1697 rlVirtualXStart
1699 Start a virtual X server on a first free display. Tries only first N
1701 displays, so you can run out of them.
1702 rlVirtualXStart name
1704 name
1706 String identifying the X server.
1707 Returns 0 when the server is started successfully.
1709 rlVirtualXGetDisplay
1711 Get the DISPLAY variable for specified virtual X server.
1713 rlVirtualXGetDisplay name
1715 name
1717 String identifying the X server.
1718 Displays the number of display where specified virtual X server is
1720 running to standard output. Returns 0 on success.
1721 rlVirtualXStop
1723 Kill the specified X server.
1725 rlVirtualXStop name
1727 name
1729 String identifying the X server.
1730 Returns 0 when the server is stopped successfully.
1732 Example
1734 Below is a simple example of usage. Note that a lot of usefull
1736 debugging information is reported on the DEBUG level, so you can run
1737 your test with "DEBUG=1 make run" to get them.
1738 rlVirtualXStart $TEST
1740 rlAssert0 "Virtual X server started" $?
1741 export DISPLAY="$( rlVirtualXGetDisplay $TEST )"
1742 # ...your test which needs X...
1743 rlVirtualXStop $TEST
1744 rlAssert0 "Virtual X server killed" $?
1745 These are "Requires" lines for your scripts - note different package
1747 names for different RHEL versions:
1748 @echo "Requires: xorg-x11-server-Xvfb" >> $(METADATA) # RHEL-5
1750 @echo "Requires: xorg-x11-Xvfb" >> $(METADATA) # RHEL-4
1751 @echo "Requires: XFree86-Xvfb" >> $(METADATA) # RHEL-3
1752
1754 Location of test results related output files can be configured by
1755 setting BEAKERLIB_DIR variable before running the test. If it is not
1756 set, temporary directory is created.
1757 journal.txt
1759 Journal in human readable form.
1760 journal.xml
1762 Journal in XML format, requires python. This dependency can be avoided
1763 if the test is run with variable BEAKERLIB_JOURNAL set to 0 in which
1764 case journal.xml is not created.
1765 XSLT
1767 XML journal can be transformed through XSLT template. Which template is
1769 used is configurable by setting BEAKERLIB_JOURNAL variable. Value can
1770 be either filename in which case beakerlib will try to use
1771 $INSTALL_DIR/xslt-template/$filename (e.g.:
1772 /usr/share/beakerlib/xstl-templates/xunit.xsl) or it can be path to a
1773 template anywhere on the system.
1774 TestResults
1776 Overall results of the test in a 'sourceable' form. Each line contains
1777 a pair VAR=VALUE. All variable names have 'TESTRESULT_' prefix.
1778 List of variables:
1780 TESTRESULT_RESULT_STRING - Result of the test in a string, e.g.: PASS,
1782 FAIL, WARN.
1783 TESTRESULT_RESULT_ECODE - Result of the test as an integer, 0 equals to
1785 PASS.
1786 TESTRESULT_PHASES_PASSED - Number of phases that ended with PASS.
1788 TESTRESULT_PHASES_FAILED - Number of phases that ended with non-PASS
1790 result.
1791 TESTRESULT_PHASES_SKIPPED - Number of skipped phases.
1793 TESTRESULT_ASSERTS_FAILED - Number of asserts that ended with non-PASS
1795 result in the whole test.
1796 TESTRESULT_STARTTIME - Time when test started in seconds since epoch.
1798 TESTRESULT_ENDTIME - Time when test ended in seconds since epoch.
1800 TESTRESULT_DURATION - Duration of the test run in seconds.
1802 TESTRESULT_BEAKERLIB_DIR - Directory with test results files.
1804
1806 Simple
1807 A minimal BeakerLib test can look like this:
1808 . /usr/share/beakerlib/beakerlib.sh
1810 rlJournalStart
1812 rlPhaseStartTest
1813 rlAssertRpm "setup"
1814 rlAssertExists "/etc/passwd"
1815 rlAssertGrep "root" "/etc/passwd"
1816 rlPhaseEnd
1817 rlJournalEnd
1818 Phases
1820 Here comes a bit more interesting example of a test which sets all the
1821 recommended variables and makes use of the phases:
1822 # Include the BeakerLib environment
1824 . /usr/share/beakerlib/beakerlib.sh
1825 # Set the full test name
1827 TEST="/examples/beakerlib/Sanity/phases"
1828 # Package being tested
1830 PACKAGE="coreutils"
1831 rlJournalStart
1833 # Setup phase: Prepare test directory
1834 rlPhaseStartSetup
1835 rlAssertRpm $PACKAGE
1836 rlRun 'TmpDir=$(mktemp -d)' 0 'Creating tmp directory' # no-reboot
1837 rlRun "pushd $TmpDir"
1838 rlPhaseEnd
1839 # Test phase: Testing touch, ls and rm commands
1841 rlPhaseStartTest
1842 rlRun "touch foo" 0 "Creating the foo test file"
1843 rlAssertExists "foo"
1844 rlRun "ls -l foo" 0 "Listing the foo test file"
1845 rlRun "rm foo" 0 "Removing the foo test file"
1846 rlAssertNotExists "foo"
1847 rlRun "ls -l foo" 2 "Listing foo should now report an error"
1848 rlPhaseEnd
1849 # Cleanup phase: Remove test directory
1851 rlPhaseStartCleanup
1852 rlRun "popd"
1853 rlRun "rm -r $TmpDir" 0 "Removing tmp directory"
1854 rlPhaseEnd
1855 rlJournalEnd
1856 # Print the test report
1858 rlJournalPrintText
1859 The ouput of the rlJournalPrintText command would produce an output
1861 similar to the following:
1862 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
1864 :: TEST PROTOCOL
1865 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
1866 Package : coreutils
1868 Installed : coreutils-8.27-19.fc27.x86_64
1869 beakerlib RPM : beakerlib-1.17-6.fc27.noarch
1870 Test started : 2018-02-08 15:43:03 CET
1871 Test finished : 2018-02-08 15:43:04 CET
1872 Test duration : 1 seconds
1873 Test name : /examples/beakerlib/Sanity/phases
1874 Distro : Fedora release 27 (Twenty Seven)
1875 Hostname : localhost
1876 Architecture : x86_64
1877 CPUs : 4 x Intel Core Processor (Skylake)
1878 RAM size : 1992 MB
1879 HDD size : 17.55 GB
1880 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
1882 :: Test description
1883 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
1884 PURPOSE of /examples/beakerlib/Sanity/phases
1886 Description: Testing BeakerLib phases
1887 Author: Petr Splichal <psplicha@redhat.com>
1888 This example shows how the phases work in the BeakerLib on a
1890 trivial smoke test for the "touch", "ls" and "rm" commands from
1891 the coreutils package.
1892 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
1896 :: Setup
1897 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
1898 :: [ 15:43:03 ] :: [ PASS ] :: Checking for the presence of coreutils rpm
1900 :: [ 15:43:03 ] :: [ LOG ] :: Package versions:
1901 :: [ 15:43:03 ] :: [ LOG ] :: coreutils-8.27-19.fc27.x86_64
1902 :: [ 15:43:03 ] :: [ PASS ] :: Creating tmp directory (Expected 0, got 0)
1903 :: [ 15:43:03 ] :: [ PASS ] :: Command 'pushd /tmp/tmp.MMQf7dj9QV' (Expected 0, got 0)
1904 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
1905 :: Duration: 1s
1906 :: Assertions: 3 good, 0 bad
1907 :: RESULT: PASS
1908 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
1911 :: Test
1912 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
1913 :: [ 15:43:04 ] :: [ PASS ] :: Creating the foo test file (Expected 0, got 0)
1915 :: [ 15:43:04 ] :: [ PASS ] :: File foo should exist
1916 :: [ 15:43:04 ] :: [ PASS ] :: Listing the foo test file (Expected 0, got 0)
1917 :: [ 15:43:04 ] :: [ PASS ] :: Removing the foo test file (Expected 0, got 0)
1918 :: [ 15:43:04 ] :: [ PASS ] :: File foo should not exist
1919 :: [ 15:43:04 ] :: [ PASS ] :: Listing foo should now report an error (Expected 2, got 2)
1920 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
1921 :: Duration: 0s
1922 :: Assertions: 6 good, 0 bad
1923 :: RESULT: PASS
1924 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
1927 :: Cleanup
1928 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
1929 :: [ 15:43:04 ] :: [ PASS ] :: Command 'popd' (Expected 0, got 0)
1931 :: [ 15:43:04 ] :: [ PASS ] :: Removing tmp directory (Expected 0, got 0)
1932 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
1933 :: Duration: 0s
1934 :: Assertions: 2 good, 0 bad
1935 :: RESULT: PASS
1936 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
1939 :: /examples/beakerlib/Sanity/phases
1940 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
1941 :: [ 15:43:04 ] :: [ LOG ] :: JOURNAL XML: /var/tmp/beakerlib-pRiJfWE/journal.xml
1943 :: [ 15:43:04 ] :: [ LOG ] :: JOURNAL TXT: /var/tmp/beakerlib-pRiJfWE/journal.txt
1944 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
1945 :: Duration: 1s
1946 :: Phases: 3 good, 0 bad
1947 :: OVERALL RESULT: PASS
1948 Note that the detailed test description is read from a separate file
1950 PURPOSE placed in the same directory as the test itself.
1951 A lot of useful debugging information is reported on the DEBUG level.
1953 You can run your test with "DEBUG=1 make run" to get them.
1954 Verbosity of the test logging may be altered also by setting the
1956 LOG_LEVEL variable. Possible values are "ERROR", "WARNING", "INFO" and
1957 "DEBUG". You will see messages like the ones below.
1958 :: [ WARNING ] :: rlGetArch: Update test to use rlGetPrimaryArch/rlGetSecondaryArch
1960 :: [ DEBUG ] :: rlGetArch: This is architecture 'x86_64'
1961 :: [ ERROR ] :: this function was dropped as its development is completely moved to the beaker library
1962 :: [ INFO ] :: if you realy on this function and you really need to have it present in core beakerlib, file a RFE, please
1963 Setting LOG_LEVEL="DEBUG" is equivalent to DEBUG=1.
1965 Set DEBUG_TO_CONSOLE_ONLY=1 in conjuction with DEBUG=1 to avoid storing
1967 debug messages in journal. This also speeds up the execution in debug
1968 mode as those messages are not fully processed than.
1969
1971 Description
1972 Bkrdoc is a documentation generator from tests written using
1973 BeakerLib library. This generator makes documentation from test
1974 code with and also without any documentation markup.
1975 What it's good for
1977 For fast, brief and reliable documentation creation. It`s good for
1978 quick start with unknown BeakerLib test. Created documentations
1979 provides information about the documentation credibility. Also
1980 created documentations shows environmental variables and helps
1981 reader to run test script from which was documentation created.
1982 Bkrdoc project page
1984 https://github.com/rh-lab-q/bkrdoc
1985
1987 Project Page
1988 https://github.com/beakerlib/beakerlib
1989 Manual
1991 https://github.com/beakerlib/beakerlib/wiki/man
1992 Issues list
1994 https://bugzilla.redhat.com/buglist.cgi?component=beakerlib&&order=bug_status%2Cassigned_to%2Cpriority
1995 https://github.com/beakerlib/beakerlib/issues
1997 Reporting issues
1999 https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora&component=beakerlib
2000 https://github.com/beakerlib/beakerlib/issues/new
2002
2004 · Petr Muller <pmuller@redhat.com>
2005 · Ondrej Hudlicky <ohudlick@redhat.com>
2007 · Jan Hutar <jhutar@redhat.com>
2009 · Petr Splichal <psplicha@redhat.com>
2011 · Ales Zelinka <azelinka@redhat.com>
2013 · Dalibor Pospisil <dapospis@redhat.com>
2015 · Martin Kyral <mkyral@redhat.com>
2017 · Jakub Prokes <jprokes@redhat.com>
2019 · Jakub Heger <jheger@redhat.com>
2021perl v5.28.1 2019-04-05 BEAKERLIB(1)