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. 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 you are 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". Note that the command is executed in a sub-shell so
733 modified environment (e.g. set variables) is not relfected in the test
734 environment.
735 rlWatchdog command timeout [signal] [callback]
737 command
739 Command to run.
740 timeout
742 Timeout to wait, in seconds.
743 signal
745 Signal to use (optional, default KILL).
746 callback
748 Callback function to be called before the signal is send (optional,
749 none by default). The callback function will have one argument
750 available -- PGID of the process group.
751 Returns 0 if the command ends normally, without need to be killed.
753 rlReport
755 Report test result to the test harness. The command to be used for
757 reporting is set by the respective plugin. You can also use the
758 $BEAKERLIB_COMMAND_REPORT_RESULT variable to use your custom command.
759 rlReport name result [score] [log]
761 name
763 Name of the test result.
764 result
766 Result (one of PASS, WARN, FAIL). If called with something else,
767 will use WARN.
768 score
770 Test score (optional).
771 log Optional log file to be submitted instead of default "OUTPUTFILE".
773 rlCmpVersion
775 Compare two given versions composed by numbers and letters divided by
777 dot (.), underscore (_), or dash (-).
778 rlCmpVersion ver1 ver2
780 If ver1 = ver2, sign '=' is printed to stdout and 0 is returned. If
782 ver1 > ver2, sign '>' is printed to stdout and 1 is returned. If ver1
783 < ver2, sign '<' is printed to stdout and 2 is returned.
784 rlTestVersion
786 Test releation between two given versions based on given operator.
788 rlTestVersion ver1 op ver2
790 op Operator defining the logical expression. It can be '=', '==',
792 '!=', '<', '<=', '=<', '>', '>=', or '=>'.
793 Returns 0 if the expresison ver1 op ver2 is true; 1 if the expression
795 is false and 2 if something went wrong.
796 Release Info
798 rlIsRHEL
799 rlIsRHEL [Num|opNum]
801 Num When used function returns 0 if the particular RHEL version is
803 running. Multiple arguments can be passed separated with space as
804 well as any particular release (5.1 5.2 5.3).
805 opNum
807 Argument consisting of operator and number written together as one
808 string. Operator can be '<', '<=', '=<', '=', '>', '>=' matching
809 whether the currently installed version is lesser, lesser or equal,
810 equal, equal or greater, greater than the version number supplied
811 as second half of the argument. Note that ie. '=5' (unlike just
812 '5') matches exactly 5 (5.0), not 5.N, where N > 0. Also note when
813 that using >/< operators you have to either put the argument in
814 quotes or escape the operators to avoid them being interpreted as
815 bash redirection operator.
816 Returns 0 when we're running on RHEL.
818 Note that
820 rlIsRHEL '<6.9' || rlIsRHEL '<7.5'
822 would also cover 6.10 as it is less than 7.5, which is not what you
824 want. So if you want to construct a condition for rhel<6.9 for rhel6
825 or rhel<7.5 for rhel7 you actually need to use following construct:
826 rlIsRHEL 6 && rlIsRHEL '<6.9' || rlIsRHEL 7 && rlIsRHEL '<7.5'
828 Prototype:
830 rlIsRHEL
832 Returns 0 if we are running on RHEL.
834 rlIsRHEL 4.8 5
836 Returns 0 if we are running RHEL 4.8 or any RHEL 5.
838 rlIsRHEL ">=6" or rlIsRHEL \>=6
840 Returns 0 if we are running RHEL 6 or higher.
842 rlIsFedora
844 rlIsFedora [Num|opNum]
846 Returns 0 when we're running on Fedora. With given number of version
848 as parameter returns 0 if the particular Fedora version is running.
849 Range matching can be used in the form used by rlIsRHEL.
850 rlIsFedora
852 Returns 0 if we are running on Fedora.
854 rlIsFedora 9 10
856 Returns 0 if we are running Fedora 9 or 10.
858 Release Info
860 rlIsCentOS
861 rlIsCentOS [Num|opNum]
863 Returns 0 when we're running on CentOS. With given number of version
865 as parameter returns 0 if the particular CentOS version is running.
866 Range matching can be used in the form used by rlIsRHEL.
867 rlIsCentOS
869 Returns 0 if we are running on CentOS.
871 rlIsCentOS 7.1 6
873 Returns 0 if we are running CentOS 7.1 or any CentOS 6.
875 Rpm Handling
877 rlCheckRpm
878 Check whether a package is installed.
880 rlCheckRpm name [version] [release] [arch]
882 name
884 Package name like "kernel"
885 version
887 Package version like 2.6.25.6
888 release
890 Package release like "55.fc9"
891 arch
893 Package architucture like "i386"
894 Returns 0 if the specified package is installed.
896 rlAssertRpm
898 Assertion making sure that a package is installed.
900 rlAssertRpm name [version] [release] [arch]>
902 rlAssertRpm --all
903 name
905 Package name like "kernel"
906 version
908 Package version like 2.6.25.6
909 release
911 Package release like "55.fc9"
912 arch
914 Package architucture like "i386"
915 --all
917 Assert all packages listed in the $PACKAGES $REQUIRES and
918 $COLLECTIONS environment variables.
919 Returns 0 and asserts PASS if the specified package is installed.
921 rlAssertNotRpm
923 Assertion making sure that a package is not installed. This is just
925 inverse of "rlAssertRpm".
926 rlAssertNotRpm name [version] [release] [arch]>
928 name
930 Package name like "kernel"
931 version
933 Package version like 2.6.25.6
934 release
936 Package release like "55.fc9"
937 arch
939 Package architucture like "i386"
940 Returns 0 and asserts PASS if the specified package is not installed.
942 Example
944 Function "rlAssertRpm" is useful especially in prepare phase where it
946 causes abort if a package is missing, while "rlCheckRpm" is handy when
947 doing something like:
948 if ! rlCheckRpm package; then
950 yum install package
951 rlAssertRpm package
952 fi
953 rlAssertBinaryOrigin
955 Assertion making sure that given binary is owned by (one of) the given
957 package(s).
958 rlAssertBinaryOrigin binary package [package2 [...]]
960 PACKAGES=... rlAssertBinaryOrigin binary
961 binary
963 Binary name like "ksh" or "/bin/ksh"
964 package
966 List of packages like "ksh mksh". The parameter is optional. If
967 missing, contents of environment variable $PACKAGES are taken into
968 account.
969 Returns 0 and asserts PASS if the specified binary belongs to (one of)
971 the given package(s). Returns 1 and asserts FAIL if the specified
972 binary does not belong to (any of) the given package(s). Returns 2 and
973 asserts FAIL if the specified binary is not found. Returns 3 and
974 asserts FAIL if no packages are given. Returns 100 and asserts FAIL if
975 invoked with no parameters.
976 Example
978 Function "rlAssertBinaryOrigin" is useful especially in prepare phase
980 where it causes abort if a binary is missing or is owned by different
981 package:
982 PACKAGES=mksh rlAssertBinaryOrigin ksh
984 or
985 rlAssertBinaryOrigin ksh mksh
986 Returns true if ksh is owned by the mksh package (in this case:
988 /bin/ksh is a symlink pointing to /bin/mksh).
989 rlGetMakefileRequires
991 Prints space separated list of requirements defined in Makefile using
993 'Requires' attribute.
994 Return 0 if success.
996 rlGetYAMLdeps
998 Prints space separated list of requirements defined in metadata.yaml
1000 using 'require' and / or 'recommend' attribute.
1001 Full fmf ids and library references are to be ignored.
1003 rlGetYAMLdeps DEP_TYPE [array_var_name]
1005 DEP_TYPE
1007 Dependency type defined as a regexp. Expected values are 'require',
1008 'recommend', or 'require|recommend'. The matching attribute values
1009 are then processed. Defaults to 'require'.
1010 array_var_name
1012 Name of the variable to put the output to in a form of an array.
1013 This can hold also dependencies with specific version. If used,
1014 the output to stdout is suppressed.
1015 Return 0 if success.
1017 rlCheckRequirements
1019 Check that all given requirements are covered eigther by installed
1021 package or by binary available in PATHs or by some package's provides.
1022 rlRun "rlCheckRequirements REQ..."
1024 REQ Requirement to be checked. It can be package name, provides string
1026 or binary name. Moreover, the requirement can be written the same
1027 way as the Require in the spec file, including the version
1028 specification, e.g. "bash >= 4.4". The comparsion operator may be
1029 any of supported by rlTestVersion(), see its manual.
1030 Returns number of unsatisfied requirements.
1032 rlCheckMakefileRequires
1034 This is just a bit smarted wrapper of
1036 "rlCheckRequirements $(rlGetYAMLdeps 'require|recommend') ||
1038 rlCheckRequirements $(rlGetMakefileRequires)"
1039 Example
1041 rlRun "rlCheckMakefileRequires"
1043 Return 255 if requirements could not be retrieved, 0 if all
1045 requirements are satisfied or number of unsatisfied requirements.
1046 rlAssertRequired
1048 Ensures that all requires and recommends specified in the metadata.yaml
1050 are installed. If no metadata.yaml is present a fallback to Makefile
1051 is done to check Requires specified in beakerlib-style beaker-wizard
1052 layout Makefile, are installed.
1053 rlAssertRequired
1055 Prints out a verbose list of installed/missing packages during
1057 operation.
1058 Returns 0 if all required packages are installed, 1 if one or more
1060 packages are missing or if no Makefile is present.
1061 Getting RPMs
1063 Download methods
1064 Functions handling rpm downloading/installing can use more methods for
1066 actual download of the rpm.
1067 Currently there are two download methonds available:
1069 direct
1071 Use use dirct download from build system (brew).
1072 yum Use yumdownloader or dnf download.
1074 The methods and their order are defined by
1076 BEAKERLIB_RPM_DOWNLOAD_METHODS variable as space separated list. By
1077 default it is 'direct yum'. This can be overridden by user. There may
1078 be done also additions or changes to the original value, e.g.
1079 BEAKERLIB_RPM_DOWNLOAD_METHODS='yum
1080 ${BEAKERLIB_RPM_DOWNLOAD_METHODS/yum/}'
1081 Beakerlib is prepared for more Koji-based sources of packages while
1085 usigng direct download method. By default packages are fetched from
1086 Koji, particularly from https://kojipkgs.fedoraproject.org/packages.
1087 rlRpmInstall
1089 Try to install specified package from local Red Hat sources.
1091 rlRpmInstall [--quiet] package version release arch
1093 --quiet
1095 Make the download and the install process be quiet.
1096 package
1098 Package name like "kernel"
1099 version
1101 Package version like 2.6.25.6
1102 release
1104 Package release like "55.fc9"
1105 arch
1107 Package arch like "i386"
1108 Returns 0 if specified package was installed successfully.
1110 rlRpmDownload
1112 Try to download specified package.
1114 rlRpmDownload [--quiet] {package version release arch|N-V-R.A}
1116 rlRpmDownload [--quiet] --source {package version release|N-V-R}
1117 --quiet
1119 Make the download process be quiet.
1120 package
1122 Package name like "kernel"
1123 version
1125 Package version like 2.6.25.6
1126 release
1128 Package release like "55.fc9"
1129 arch
1131 Package arch like "i386"
1132 Returns 0 if specified package was downloaded successfully.
1134 rlFetchSrcForInstalled
1136 Tries various ways to download source rpm for specified installed rpm.
1138 rlFetchSrcForInstalled [--quiet] package
1140 --quiet
1142 Make the download process be quiet.
1143 package
1145 Installed package name like "kernel". It accepts in-direct names.
1146 E.g. for the package name "krb5-libs" the function will download
1147 the "krb5" source rpm.
1148 Returns 0 if the source package was successfully downloaded.
1150 Mounting
1152 rlMount
1153 Create mount point (if neccessary) and mount a NFS share.
1155 rlMount [-o MOUNT_OPTS] server share mountpoint
1157 server
1159 NFS server hostname.
1160 share
1162 Shared directory name.
1163 mountpoint
1165 Local mount point.
1166 MOUNT_OPTS
1168 Mount options.
1169 Returns 0 if mounting the share was successful.
1171 rlCheckMount
1173 Check either if a directory is a mountpoint, if it is a mountpoint to a
1175 specific server, or if it is a mountpoint to a specific export on a
1176 specific server and if it uses specific mount options.
1177 rlCheckMount [-o MOUNT_OPTS] mountpoint
1179 rlCheckMount [-o MOUNT_OPTS] server mountpoint
1180 rlCheckMount [-o MOUNT_OPTS] server share mountpoint
1181 mountpoint
1183 Local mount point.
1184 server
1186 NFS server hostname
1187 share
1189 Shared directory name
1190 MOUNT_OPTS
1192 Mount options to check (comma separated list)
1193 With one parameter, returns 0 when specified directory exists and is a
1195 mountpoint. With two parameters, returns 0 when specific directory
1196 exists, is a mountpoint and an export from specific server is mounted
1197 there. With three parameters, returns 0 if a specific shared directory
1198 is mounted on a given server on a given mountpoint
1199 If the -o option is provided, returns 0 if the mountpoint uses all the
1201 given options, 2 otherwise.
1202 rlAssertMount
1204 Assertion making sure that given directory is a mount point, if it is a
1206 mountpoint to a specific server, or if it is a mountpoint to a specific
1207 export on a specific server and if it uses specific mount options.
1208 rlAssertMount [-o MOUNT_OPTS] mountpoint
1210 rlAssertMount [-o MOUNT_OPTS] server mountpoint
1211 rlAssertMount [-o MOUNT_OPTS] server share mountpoint
1212 mountpoint
1214 Local mount point.
1215 server
1217 NFS server hostname
1218 share
1220 Shared directory name
1221 MOUNT_OPTS
1223 Mount options to check (comma separated list)
1224 With one parameter, returns 0 when specified directory exists and is a
1226 mountpoint. With two parameters, returns 0 when specific directory
1227 exists, is a mountpoint and an export from specific server is mounted
1228 there. With three parameters, returns 0 if a specific shared directory
1229 is mounted on a given server on a given mountpoint. Asserts PASS when
1230 the condition is true.
1231 If the -o option is provided, asserts PASS if the above conditions are
1233 met and the mountpoint uses all the given options.
1234 rlHash, rlUnhash
1236 Hashes/Unhashes given string and prints the result to stdout.
1238 rlHash [--decode] [--algorithm HASH_ALG] --stdin|STRING
1240 rlUnhash [--algorithm HASH_ALG] --stdin|STRING
1241 --decode
1243 Unhash given string.
1244 --algorithm
1246 Use given hash algorithm. Currently supported algorithms:
1247 base64
1248 base64_ - this is standard base64 where '=' is replaced by '_'
1249 hex
1250 Defaults to hex. Default algorithm can be override using global
1252 variable rlHashAlgorithm.
1253 --stdin
1255 Get the string from stdin.
1256 STRING
1258 String to be hashed/unhashed.
1259 Returns 0 if success.
1261 Backup and Restore
1263 rlFileBackup
1264 Create a backup of files or directories (recursive). Can be used
1266 multiple times to add more files to backup. Backing up an already
1267 backed up file overwrites the original backup.
1268 rlFileBackup [--clean] [--namespace name] [--missing-ok|--no-missing-ok] file [file...]
1270 You can use "rlRun" for asserting the result but keep in mind meaning
1272 of exit codes, especialy exit code 8, if using without --clean option.
1273 --clean
1275 If this option is provided (has to be the first option of the
1276 command), then file/dir backed up using this command (provided in
1277 next options) will be (recursively) removed before we restore it.
1278 This option implies --missing-ok, which can be overridden by
1279 --no-missing-ok.
1280 --namespace name
1282 Specifies the namespace to use. Namespaces can be used to separate
1283 backups and their restoration.
1284 --missing-ok
1286 Do not raise an error in case of missing file to backup.
1287 --no-missing-ok
1289 Do raise an error in case of missing file to backup. This is
1290 useful with --clean. This behaviour can be globally set by global
1291 variable BEAKERLIB_FILEBACKUP_MISSING_OK=false.
1292 file
1294 Files and/or directories to be backed up.
1295 Returns 0 if the backup was successful. Returns 1 if parsing of
1297 parameters was not successful. Returns 2 if no files specification was
1298 provided. Returns 3 if BEAKERLIB_DIR variable is not set, e.g.
1299 rlJournalStart was not executed. Returns 4 if creating of main backup
1300 destination directories was not successful. Returns 5 if creating of
1301 file specific backup destination directories was not successful.
1302 Returns 6 if the copy of backed up files was not successful. Returns 7
1303 if attributes of backed up files were not successfuly copied. Returns
1304 8 if backed up files do not exist. This can be suppressed based on
1305 other options.
1306 Example with --clean:
1308 touch cleandir/aaa
1310 rlRun "rlFileBackup --clean cleandir/"
1311 touch cleandir/bbb
1312 ls cleandir/
1313 aaa bbb
1314 rlRun "rlFileRestore"
1315 ls cleandir/
1316 aaa
1317 rlFileRestore
1319 Restore backed up files to their original location. "rlFileRestore"
1321 does not remove new files appearing after backup has been made. If you
1322 don't want to leave anything behind just remove the whole original tree
1323 before running "rlFileRestore", or see "--clean" option of
1324 "rlFileBackup".
1325 rlFileRestore [--namespace name]
1327 You can use "rlRun" for asserting the result.
1329 --namespace name
1331 Specifies the namespace to use. Namespaces can be used to separate
1332 backups and their restoration.
1333 Returns 0 if backup dir is found and files are restored successfully.
1335 Return code bits meaning:
1337 XXXXX
1339 |||||
1340 ||||\_ error parsing parameters
1341 |||\__ could not find backup directory
1342 ||\___ files cleanup failed
1343 |\____ files restore failed
1344 \_____ no files were restored nor cleaned
1345 Services
1347 Following routines implement comfortable way how to start/stop system
1348 services with the possibility to restore them to their original state
1349 after testing.
1350 rlServiceStart
1352 Make sure the given "service" is running with fresh configuration.
1354 (Start it if it is stopped and restart if it is already running.) In
1355 addition, when called for the first time, the current state is saved so
1356 that the "service" can be restored to its original state when testing
1357 is finished, see "rlServiceRestore".
1358 rlServiceStart service [service...]
1360 service
1362 Name of the service(s) to start.
1363 Returns number of services which failed to start/restart; thus zero is
1365 returned when everything is OK.
1366 rlServiceStop
1368 Make sure the given "service" is stopped. Stop it if it is running and
1370 do nothing when it is already stopped. In addition, when called for the
1371 first time, the current state is saved so that the "service" can be
1372 restored to its original state when testing is finished, see
1373 "rlServiceRestore".
1374 rlServiceStop service [service...]
1376 service
1378 Name of the service(s) to stop.
1379 Returns number of services which failed to become stopped; thus zero is
1381 returned when everything is OK.
1382 rlServiceRestore
1384 Restore given "service" into its original state (before the first
1386 "rlServiceStart" or "rlServiceStop" was called). If "rlServiceStart"
1387 was called on already running "service", "rlServiceRestore" will
1388 restart the "service" when restoring its state.
1389 rlServiceRestore [service...]
1391 service
1393 Name of the service(s) to restore to original state. All services
1394 will be restored in reverse order if no service name is given.
1395 Returns number of services which failed to get back to their original
1397 state; thus zero is returned when everything is OK.
1398 rlServiceStatus
1400 Print status (output of `service SERVICE status` or `systemctl status
1402 SERVICE`) of given "SERVICE".
1403 rlServiceStatus SERVICE [SERVICE...]
1405 SERVICE
1407 The service to get the status of.
1408 Returns service status return code of the last provided SERVICE.
1410 rlServiceEnable
1412 Enables selected services if needed, or does nothing if already
1414 enabled. In addition, when called for the first time, the current
1415 state is saved so that the "service" can be restored to its original
1416 state when testing is finished, see "rlServiceRestore".
1417 rlServiceEnable service [service...]
1419 service
1421 Name of the service(s) to enable.
1422 Returns number of services which failed enablement; thus zero is
1424 returned when everything is OK.
1425 rlServiceDisable
1427 Disables selected services if needed, or does nothing if already
1429 disabled. In addition, when called for the first time, the current
1430 state is saved so that the "service" can be restored to its original
1431 state when testing is finished, see "rlServiceRestore".
1432 rlServiceDisable service [service...]
1434 service
1436 Name of the service(s) to disable.
1437 Returns number of services which failed disablement; thus zero is
1439 returned when everything is OK.
1440 Sockets
1442 Following routines implement comfortable way how to start/stop system
1443 sockets with the possibility to restore them to their original state
1444 after testing.
1445 rlSocketStart
1447 Make sure the given "socket" is running. (Start it if stopped, leave it
1449 if already running.) In addition, when called for the first time, the
1450 current state is saved so that the "socket" can be restored to its
1451 original state when testing is finished, see "rlSocketRestore".
1452 rlSocketStart socket [socket...]
1454 socket
1456 Name of the socket(s) to start.
1457 Returns number of sockets which failed to start/restart; thus zero is
1459 returned when everything is OK.
1460 rlSocketStop
1462 Make sure the given "socket" is stopped. Stop it if it is running and
1464 do nothing when it is already stopped. In addition, when called for the
1465 first time, the current state is saved so that the "socket" can be
1466 restored to its original state when testing is finished, see
1467 "rlSocketRestore".
1468 rlSocketStop socket [socket...]
1470 socket
1472 Name of the socket(s) to stop.
1473 Returns number of sockets which failed to become stopped; thus zero is
1475 returned when everything is OK.
1476 rlSocketRestore
1478 Restore given "socket" into its original state (before the first
1480 "rlSocketStart" or "rlSocketStop" was called).
1481 Warning !!! Xinetd process [even though it might have been used] is
1483 NOT restored. It is recommended to call rlServiceRestore xinetd as
1484 well.
1485 rlSocketRestore socket [socket...]
1487 socket
1489 Name of the socket(s) to restore to original state.
1490 Returns number of sockets which failed to get back to their original
1492 state; thus zero is returned when everything is OK.
1493 Cleanup management
1495 Cleanup management works with a so-called cleanup buffer, which is a
1496 temporary representation of what should be run at cleanup time, and a
1497 final cleanup script (executable), which is generated from this buffer
1498 and wraps it using BeakerLib essentials (journal initialization,
1499 cleanup phase, ...). The cleanup script must always be updated on an
1500 atomic basis (filesystem-wise) to allow an asynchronous execution by a
1501 third party (ie. test watcher).
1502 The test watcher usage is mandatory for the cleanup management system
1504 to work properly as it is the test watcher that executes the actual
1505 cleanup script. Limited, catastrophe-avoiding mechanism is in place
1506 even when the test is not run in test watcher, but that should be seen
1507 as a backup and such situation is to be avoided whenever possible.
1508 The cleanup script shares all environment (variables, exported or not,
1510 and functions) with the test itself - the cleanup append/prepend
1511 functions "sample" or "snapshot" the environment at the time of their
1512 call, IOW any changes to the test environment are synchronized to the
1513 cleanup script only upon calling append/prepend. When the
1514 append/prepend functions are called within a function which has local
1515 variables, these will appear as global in the cleanup.
1516 While the cleanup script receives $PWD from the test, its working dir
1518 is set to the initial test execution dir even if $PWD contains
1519 something else. It is impossible to use relative paths inside cleanup
1520 reliably - certain parts of the cleanup might have been added under
1521 different current directories (CWDs). Therefore always use absolute
1522 paths in append/prepend cleanup or make sure you never 'cd' elsewhere
1523 (ie. to a TmpDir).
1524 rlCleanupAppend
1526 Appends a string to the cleanup buffer and recreates the cleanup
1528 script.
1529 rlCleanupAppend string
1531 Returns 0 if the operation was successful, 1 otherwise.
1533 rlCleanupPrepend
1535 Prepends a string to the cleanup buffer and recreates the cleanup
1537 script.
1538 rlCleanupPrepend string
1540 Returns 0 if the operation was successful, 1 otherwise.
1542 Time Performance
1544 rlPerfTime_RunsInTime
1545 Measures, how many runs of some commands can be done in specified time.
1547 This approach is suitable for short-time running tasks (up to few
1548 seconds), where averaging few runs is not precise. This is done several
1549 times, and the final result is the average of all runs. It prints the
1550 number on stdout, so it has to be captured.
1551 rlPerfTime_RunsInTime command [time] [runs]
1553 command
1555 Command to run.
1556 time
1558 Time in seconds (optional, default=30).
1559 runs
1561 Number of averaged runs (optional, default=3).
1562 rlPerfTime_AvgFromRuns
1564 Measures the average time of running some task. This approach is
1566 suitable for long-time running tasks (tens of seconds and more), where
1567 it is precise enough. Measured runs can be preceded by dry run, which
1568 is not measured and it's purpose is to warm up various caches. It
1569 prints the number on stdout, so it has to be captured. Or, result is
1570 then stored in special rl_retval variable.
1571 rlPerfTime_AvgFromRuns command [count] [warmup]
1573 command
1575 Command to run.
1576 count
1578 Times to run (optional, default=3).
1579 warmup
1581 Warm-up run, run if this option is not "warmup" (optional,
1582 default="warmup")
1583 Analyze
1585 rlDejaSum
1586 TODO description
1588 rlDejaSum par1 par2
1590 par1
1592 TODO description
1593 par2
1595 TODO description
1596 Return 0 if... TODO
1598 rlImport
1600 Imports code provided by one or more libraries into the test namespace.
1602 The library search mechanism is based on Beaker test hierarchy system,
1603 i.e.:
1604 /component/type/test-name/test-file
1606 When test-file calls rlImport with 'foo/bar' parameter, the libraries
1608 are searched in following locations: these are the possible path
1609 prefixes
1610 - colon-separated paths from $BEAKERLIB_LIBRARY_PATH
1612 - /mnt/tests
1613 - /usr/share/beakerlib-libraries
1614 the next component of the path is one of the following:
1616 - /foo/Library/bar
1618 - /foo/bar
1619 - /libs/foo/bar
1620 - /*/foo/Library/bar
1621 - /libs/*/foo/Library/bar
1622 - /libs/*/foo/bar
1623 the directory path is then constructed as prefix/path/lib.sh If the
1625 library is still not found an upwards directory traversal is used, and
1626 a check for presence of the library in the above mentioned possible
1627 paths is to be performed. This means this function needs to be called
1628 from the test hierarchy, not e.g. the /tmp directory.
1629 Once library is found, it is sourced and a verifier function is called.
1631 The verifier function is cunstructed by composing the library prefix
1632 and LibraryLoaded. Library prefix can be defined in the library itself.
1633 If the verifier passes the library is ready to use. Also variable
1634 <PREFIX>LibraryDir is created and it points to the library folder.
1635 Usage:
1637 rlImport --all
1639 rlImport LIBRARY [LIBRARY2...]
1640 --all
1642 Read $BEAKERLIB_DIR/metadata.yaml or ./Makefile, pickup the library
1643 requirements and import them all.
1644 LIBRARY
1646 Must have 'component[/path]' format. Identifies the library to
1647 import.
1648 Returns 0 if the import of all libraries was successful. Returns non-
1650 zero if one or more library failed to import.
1651 Process Synchronisation
1653 rlWaitForCmd
1654 Pauses script execution until command exit status is the expeced value.
1656 Logs a WARNING and returns 1 if the command didn't exit successfully
1657 before timeout elapsed or a maximum number of invocations has been
1658 reached.
1659 rlWaitForCmd command [-p PID] [-t time] [-m count] [-d delay] [-r retval]
1661 command
1663 Command that will be executed until its return code is equal 0 or
1664 value speciefied as option to '-r'.
1665 -t time
1667 Timeout in seconds, default=120. If the command doesn't return 0
1668 before time elapses, the command will be killed.
1669 -p PID
1671 PID of the process to check before running command. If the process
1672 exits before the socket is opened, the command will log a WARNING.
1673 -m count
1675 Maximum number of 'command' executions before continuing anyway.
1676 Default is infite. Returns 1 if the maximum was reached.
1677 -d delay
1679 Delay between 'command' invocations. Default 1.
1680 -r retval
1682 Expected return value of command. Default 0.
1683 rlWaitForFile
1685 Pauses script execution until specified file or directory starts
1687 existing. Returns 0 if file started existing, 1 if timeout was reached
1688 or PID exited. Return code is greater than 1 in case of error.
1689 rlWaitForFile path [-p PID] [-t time] [-d delay]
1691 path
1693 Path to file that should start existing.
1694 -t time
1696 Timeout in seconds (optional, default=120). If the file isn't
1697 opened before the time elapses the command returns 1.
1698 -p PID
1700 PID of the process that should also be running. If the process
1701 exits before the file is created, the command returns with status
1702 code of 1.
1703 -d delay
1705 Delay between subsequent checks for existence of file. Default 1.
1706 rlWaitForSocket
1708 Pauses script execution until local socket starts listening. Returns 0
1710 if socket started listening, 1 if timeout was reached or PID exited.
1711 Return code is greater than 1 in case of error.
1712 rlWaitForSocket {port|path} [-p PID] [-t time] [-d delay] [--close] [--remote]
1714 port|path
1716 Network port to wait for opening or a path to UNIX socket. Regular
1717 expressions are also supported.
1718 -t time
1720 Timeout in seconds (optional, default=120). If the socket isn't
1721 opened before the time elapses the command returns 1.
1722 -p PID
1724 PID of the process that should also be running. If the process
1725 exits before the socket is opened, the command returns with status
1726 code of 1.
1727 -d delay
1729 Delay between subsequent checks for availability of socket. Default
1730 1.
1731 --close
1733 Wait for the socket to stop listening.
1734 --remote
1736 Wait for the remote socket to start listening instead of local one.
1737 rlWait
1739 Wrapper around bash builtin 'wait' command. See bash_builtins(1) man
1741 page. Kills the process and all its children if the timeout elapses.
1742 rlWaitFor [n ...] [-s SIGNAL] [-t time]
1744 n List of PIDs to wait for. They need to be background tasks of
1746 current shell. See bash_builtins(1) section for 'wait' command.
1747 -t time
1749 Timeout in seconds (optional, default=30). If the wait isn't
1750 successful before the time elapses then all specified tasks are
1751 killed.
1752 -s SIGNAL
1754 Signal used to kill the process, optional SIGTERM by default.
1755 Virtual X Server
1757 Functions providing simple way how to start and stop virtual X server.
1758 rlVirtualXStart
1760 Start a virtual X server on a first free display. Tries only first N
1762 displays, so you can run out of them.
1763 rlVirtualXStart name [N]
1765 name
1767 String identifying the X server.
1768 N Maximum number of displays to try. Defaults to 3.
1770 Returns 0 when the server is started successfully.
1772 rlVirtualXGetDisplay
1774 Get the DISPLAY variable for specified virtual X server.
1776 rlVirtualXGetDisplay name
1778 name
1780 String identifying the X server.
1781 Displays the number of display where specified virtual X server is
1783 running to standard output. Returns 0 on success.
1784 rlVirtualXStop
1786 Kill the specified X server.
1788 rlVirtualXStop name
1790 name
1792 String identifying the X server.
1793 Returns 0 when the server is stopped successfully.
1795 Example
1797 Below is a simple example of usage. Note that a lot of usefull
1799 debugging information is reported on the DEBUG level, so you can run
1800 your test with "DEBUG=1 make run" to get them.
1801 rlVirtualXStart $TEST
1803 rlAssert0 "Virtual X server started" $?
1804 export DISPLAY="$( rlVirtualXGetDisplay $TEST )"
1805 # ...your test which needs X...
1806 rlVirtualXStop $TEST
1807 rlAssert0 "Virtual X server killed" $?
1808 These are "Requires" lines for your scripts - note different package
1810 names for different RHEL versions:
1811 @echo "Requires: xorg-x11-server-Xvfb" >> $(METADATA) # RHEL-5
1813 @echo "Requires: xorg-x11-Xvfb" >> $(METADATA) # RHEL-4
1814 @echo "Requires: XFree86-Xvfb" >> $(METADATA) # RHEL-3
1815 rlYash_parse
1817 Parse yaml data to the associative array.
1819 rlYash_parse VAR_NAME YAML_DATA
1821 VAR_NAME
1823 Name of the variable to which the yaml structure will be saved.
1824 Note that the variable needs to be predeclared as an associative
1826 array.
1827 YAML_DATA
1829 The actual yaml data.
1830 Beakerlib Profiling
1832 Enable profiling
1833 Set environment variable BEAKERLIB_PROFILING=1
1835 BEAKERLIB_PROFILING=1 make run
1837 A file /dev/shm/beakerlib_profile will be created for later processing.
1839 Process the profile
1841 /usr/share/beakerlib/profiling.sh process > profile.csv
1843
1845 Location of test results related output files can be configured by
1846 setting BEAKERLIB_DIR variable before running the test. If it is not
1847 set, temporary directory is created.
1848 journal.txt
1850 Journal in human readable form.
1851 journal.xml
1853 Journal in XML format, requires python. This dependency can be avoided
1854 if the test is run with variable BEAKERLIB_JOURNAL set to 0 in which
1855 case journal.xml is not created.
1856 XSLT
1858 XML journal can be transformed through XSLT template. Which template is
1860 used is configurable by setting BEAKERLIB_JOURNAL variable. Value can
1861 be either filename in which case beakerlib will try to use
1862 $INSTALL_DIR/xslt-template/$filename (e.g.:
1863 /usr/share/beakerlib/xstl-templates/xunit.xsl) or it can be path to a
1864 template anywhere on the system.
1865 TestResults
1867 Overall results of the test in a 'sourceable' form. Each line contains
1868 a pair VAR=VALUE. All variable names have 'TESTRESULT_' prefix.
1869 List of variables:
1871 TESTRESULT_STATE - Current state of the test run; possible values:
1873 started, incomplete and complete.
1874 - 'started' is set after a Journal is opened.
1875 - 'incomplete' is set after a Phase is closed.
1876 - 'complete' is set after a Journal is closed.
1877 TESTRESULT_RESULT_STRING - Result of the test in a string, e.g.: PASS,
1879 FAIL, WARN.
1880 TESTRESULT_RESULT_ECODE - Result of the test as an integer, 0 equals to
1882 PASS.
1883 TESTRESULT_PHASES_PASSED - Number of phases that ended with PASS.
1885 TESTRESULT_PHASES_FAILED - Number of phases that ended with non-PASS
1887 result.
1888 TESTRESULT_PHASES_SKIPPED - Number of skipped phases.
1890 TESTRESULT_ASSERTS_FAILED - Number of asserts that ended with non-PASS
1892 result in the whole test.
1893 TESTRESULT_STARTTIME - Time when test started in seconds since epoch.
1895 TESTRESULT_ENDTIME - Time when test ended in seconds since epoch.
1897 TESTRESULT_DURATION - Duration of the test run in seconds.
1899 TESTRESULT_BEAKERLIB_DIR - Directory with test results files.
1901
1903 Simple
1904 A minimal BeakerLib test can look like this:
1905 . /usr/share/beakerlib/beakerlib.sh
1907 rlJournalStart
1909 rlPhaseStartTest
1910 rlAssertRpm "setup"
1911 rlAssertExists "/etc/passwd"
1912 rlAssertGrep "root" "/etc/passwd"
1913 rlPhaseEnd
1914 rlJournalEnd
1915 Phases
1917 Here comes a bit more interesting example of a test which sets all the
1918 recommended variables and makes use of the phases:
1919 # Include the BeakerLib environment
1921 . /usr/share/beakerlib/beakerlib.sh
1922 # Set the full test name
1924 TEST="/examples/beakerlib/Sanity/phases"
1925 # Package being tested
1927 PACKAGE="coreutils"
1928 rlJournalStart
1930 # Setup phase: Prepare test directory
1931 rlPhaseStartSetup
1932 rlAssertRpm $PACKAGE
1933 rlRun 'TmpDir=$(mktemp -d)' 0 'Creating tmp directory' # no-reboot
1934 rlRun "pushd $TmpDir"
1935 rlPhaseEnd
1936 # Test phase: Testing touch, ls and rm commands
1938 rlPhaseStartTest
1939 rlRun "touch foo" 0 "Creating the foo test file"
1940 rlAssertExists "foo"
1941 rlRun "ls -l foo" 0 "Listing the foo test file"
1942 rlRun "rm foo" 0 "Removing the foo test file"
1943 rlAssertNotExists "foo"
1944 rlRun "ls -l foo" 2 "Listing foo should now report an error"
1945 rlPhaseEnd
1946 # Cleanup phase: Remove test directory
1948 rlPhaseStartCleanup
1949 rlRun "popd"
1950 rlRun "rm -r $TmpDir" 0 "Removing tmp directory"
1951 rlPhaseEnd
1952 rlJournalEnd
1953 # Print the test report
1955 rlJournalPrintText
1956 The ouput of the rlJournalPrintText command would produce an output
1958 similar to the following:
1959 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
1961 :: TEST PROTOCOL
1962 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
1963 Package : coreutils
1965 Installed : coreutils-8.27-19.fc27.x86_64
1966 beakerlib RPM : beakerlib-1.17-6.fc27.noarch
1967 Test started : 2018-02-08 15:43:03 CET
1968 Test finished : 2018-02-08 15:43:04 CET
1969 Test duration : 1 seconds
1970 Test name : /examples/beakerlib/Sanity/phases
1971 Distro : Fedora release 27 (Twenty Seven)
1972 Hostname : localhost
1973 Architecture : x86_64
1974 CPUs : 4 x Intel Core Processor (Skylake)
1975 RAM size : 1992 MB
1976 HDD size : 17.55 GB
1977 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
1979 :: Test description
1980 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
1981 PURPOSE of /examples/beakerlib/Sanity/phases
1983 Description: Testing BeakerLib phases
1984 Author: Petr Splichal <psplicha@redhat.com>
1985 This example shows how the phases work in the BeakerLib on a
1987 trivial smoke test for the "touch", "ls" and "rm" commands from
1988 the coreutils package.
1989 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
1993 :: Setup
1994 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
1995 :: [ 15:43:03 ] :: [ PASS ] :: Checking for the presence of coreutils rpm
1997 :: [ 15:43:03 ] :: [ LOG ] :: Package versions:
1998 :: [ 15:43:03 ] :: [ LOG ] :: coreutils-8.27-19.fc27.x86_64
1999 :: [ 15:43:03 ] :: [ PASS ] :: Creating tmp directory (Expected 0, got 0)
2000 :: [ 15:43:03 ] :: [ PASS ] :: Command 'pushd /tmp/tmp.MMQf7dj9QV' (Expected 0, got 0)
2001 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2002 :: Duration: 1s
2003 :: Assertions: 3 good, 0 bad
2004 :: RESULT: PASS
2005 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2008 :: Test
2009 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2010 :: [ 15:43:04 ] :: [ PASS ] :: Creating the foo test file (Expected 0, got 0)
2012 :: [ 15:43:04 ] :: [ PASS ] :: File foo should exist
2013 :: [ 15:43:04 ] :: [ PASS ] :: Listing the foo test file (Expected 0, got 0)
2014 :: [ 15:43:04 ] :: [ PASS ] :: Removing the foo test file (Expected 0, got 0)
2015 :: [ 15:43:04 ] :: [ PASS ] :: File foo should not exist
2016 :: [ 15:43:04 ] :: [ PASS ] :: Listing foo should now report an error (Expected 2, got 2)
2017 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2018 :: Duration: 0s
2019 :: Assertions: 6 good, 0 bad
2020 :: RESULT: PASS
2021 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2024 :: Cleanup
2025 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2026 :: [ 15:43:04 ] :: [ PASS ] :: Command 'popd' (Expected 0, got 0)
2028 :: [ 15:43:04 ] :: [ PASS ] :: Removing tmp directory (Expected 0, got 0)
2029 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2030 :: Duration: 0s
2031 :: Assertions: 2 good, 0 bad
2032 :: RESULT: PASS
2033 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2036 :: /examples/beakerlib/Sanity/phases
2037 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2038 :: [ 15:43:04 ] :: [ LOG ] :: JOURNAL XML: /var/tmp/beakerlib-pRiJfWE/journal.xml
2040 :: [ 15:43:04 ] :: [ LOG ] :: JOURNAL TXT: /var/tmp/beakerlib-pRiJfWE/journal.txt
2041 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2042 :: Duration: 1s
2043 :: Phases: 3 good, 0 bad
2044 :: OVERALL RESULT: PASS
2045 Note that the detailed test description is read from a separate file
2047 PURPOSE placed in the same directory as the test itself.
2048 A lot of useful debugging information is reported on the DEBUG level.
2050 You can run your test with "DEBUG=1 make run" to get them.
2051 Verbosity of the test logging may be altered also by setting the
2053 LOG_LEVEL variable. Possible values are "ERROR", "WARNING", "INFO" and
2054 "DEBUG". You will see messages like the ones below.
2055 :: [ WARNING ] :: rlGetArch: Update test to use rlGetPrimaryArch/rlGetSecondaryArch
2057 :: [ DEBUG ] :: rlGetArch: This is architecture 'x86_64'
2058 :: [ ERROR ] :: this function was dropped as its development is completely moved to the beaker library
2059 :: [ INFO ] :: if you realy on this function and you really need to have it present in core beakerlib, file a RFE, please
2060 Setting LOG_LEVEL="DEBUG" is equivalent to DEBUG=1.
2062 Set DEBUG_TO_CONSOLE_ONLY=1 in conjuction with DEBUG=1 to avoid storing
2064 debug messages in journal. This also speeds up the execution in debug
2065 mode as those messages are not fully processed than.
2066
2068 Description
2069 Bkrdoc is a documentation generator from tests written using
2070 BeakerLib library. This generator makes documentation from test
2071 code with and also without any documentation markup.
2072 What it's good for
2074 For fast, brief and reliable documentation creation. It`s good for
2075 quick start with unknown BeakerLib test. Created documentations
2076 provides information about the documentation credibility. Also
2077 created documentations shows environmental variables and helps
2078 reader to run test script from which was documentation created.
2079 Bkrdoc project page
2081 https://github.com/rh-lab-q/bkrdoc
2082
2084 Project Page
2085 https://github.com/beakerlib/beakerlib
2086 Manual
2088 https://github.com/beakerlib/beakerlib/wiki/man
2089 Issues list
2091 https://bugzilla.redhat.com/buglist.cgi?component=beakerlib&&order=bug_status%2Cassigned_to%2Cpriority
2092 https://github.com/beakerlib/beakerlib/issues
2094 Reporting issues
2096 https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora&component=beakerlib
2097 https://github.com/beakerlib/beakerlib/issues/new
2099
2101 · Petr Muller <pmuller@redhat.com>
2102 · Ondrej Hudlicky <ohudlick@redhat.com>
2104 · Jan Hutar <jhutar@redhat.com>
2106 · Petr Splichal <psplicha@redhat.com>
2108 · Ales Zelinka <azelinka@redhat.com>
2110 · Dalibor Pospisil <dapospis@redhat.com>
2112 · Martin Kyral <mkyral@redhat.com>
2114 · Jakub Prokes <jprokes@redhat.com>
2116 · Jakub Heger <jheger@redhat.com>
2118perl v5.32.1 2021-03-25 BEAKERLIB(1)