1BEAKERLIB(1)          User Contributed Perl Documentation         BEAKERLIB(1)
2
3
4

NAME

6       BeakerLib - a shell-level integration testing library
7

DESCRIPTION

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
13       The essential features include:
14
15Journal - uniform logging mechanism (logs & results saved in
16           flexible XML format, easy to compare results & generate reports)
17
18Phases - logical grouping of test actions, clear separation of
19           setup / test / cleanup (preventing false fails)
20
21Asserts - common checks affecting the overall results of the
22           individual phases (checking for exit codes, file existence &
23           content...)
24
25Helpers - convenience functions for common operations such as
26           managing services, backup & restore
27
28       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
32           . /usr/share/beakerlib/beakerlib.sh
33
34       See the EXAMPLES section for quick start inspiration.
35
36       See the BKRDOC section for more information about Automated
37       documentation generator for BeakerLib tests.
38

FUNCTIONS

40   Journalling
41       rlJournalStart
42
43       Initialize the journal file.
44
45           rlJournalStart
46
47       Run on the very beginning of your script to initialize journalling
48       functionality.
49
50       rlJournalEnd
51
52       Summarize the test run and upload the journal file.
53
54           rlJournalEnd
55
56       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
59       rlJournalPrint
60
61       Print the content of the journal in pretty xml format.
62
63           rlJournalPrint [type]
64
65       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
70       Example:
71
72           <?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 &lt;psplicha@redhat.com&gt;
86
87               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
101       rlJournalPrintText
102
103       Print the content of the journal in pretty text format.
104
105           rlJournalPrintText [--full-journal]
106
107       --full-journal
108           The option is now deprecated, has no effect and will be removed in
109           a future version.
110
111       Example:
112
113           ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
114           :: [   LOG    ] :: TEST PROTOCOL
115           ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
116
117           :: [   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
126           ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
127           :: [   LOG    ] :: Test description
128           ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
129
130           PURPOSE of /examples/beakerlib/Sanity/simple
131           Description: Minimal BeakerLib sanity test
132           Author: Petr Splichal <psplicha@redhat.com>
133
134           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
138
139           ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
140           :: [   LOG    ] :: Test
141           ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
142
143           :: [   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
150       rlGetTestState
151
152       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
155           rlGetTestState
156
157       rlGetPhaseState
158
159       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
163           rlGetPhaseState
164
165   Logging
166       rlLog
167
168       rlLogDebug
169
170       rlLogInfo
171
172       rlLogWarning
173
174       rlLogError
175
176       rlLogFatal
177
178       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
183           rlLog message [logfile] [priority] [label]
184
185       message
186           Message you want to show (use quotes when invoking).
187
188       logfile
189           Log file. If not supplied, OUTPUTFILE is assumed.
190
191       priority
192           Priority of the log.
193
194       label
195           Print this text instead of time in log label.
196
197       rlDie
198
199       Create a time-labelled message in the log, report test result, upload
200       logs, close unfinished phase and terminate the test.
201
202           rlDie message [file...]
203
204       message
205           Message you want to show (use quotes when invoking) - this option
206           is mandatory.
207
208       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
214       rlBundleLogs
215
216       Create a tarball of files (e.g. logs) and attach them to the test
217       result.
218
219           rlBundleLogs package file [file...]
220
221       package
222           Name of the package. Will be used as part of the tarball name.
223
224       file
225           File(s) to be packed and submitted.
226
227       Returns result of submitting the tarball.
228
229       rlFileSubmit
230
231       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
235           rlFileSubmit [-s sep] path_to_file [required_name]
236
237       -s sep
238           Sets separator (i.e. the replacement of the /) to sep.
239
240       path_to_file
241           Either absolute or relative path to file. Relative path is
242           converted to absolute.
243
244       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
249           Examples:
250
251           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
256   Info
257       rlShowPackageVersion
258
259       Shows a message about version of packages.
260
261           rlShowPackageVersion package [package...]
262
263       package
264           Name of a package(s) you want to log.
265
266       rlGetArch
267
268       Sanitize architecture for simplier matching.
269
270       Return base arch for the current system (good when you need base arch
271       on a multilib system).
272
273           rlGetArch
274
275       On any 32-bit Intel (i386, i486, i586, ...) system you will get i386.
276
277       rlGetPrimaryArch
278
279       Return primary arch for the current system (good when you need base
280       arch on a multilib system).
281
282           rlGetPrimaryArch
283
284       On non-RHEL systems if the primary/secondary sedicision fails a
285       fallback to rlGetArch is done.
286
287       rlGetSecondaryArch
288
289       Return base arch for the current system (good when you need base arch
290       on a multilib system).
291
292           rlGetSecondaryArch
293
294       rlGetDistroRelease
295
296       rlGetDistroVariant
297
298       Return release or variant of the distribution on the system.
299
300           rlGetDistroRelease
301           rlGetDistroVariant
302
303       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
306       rlShowRunningKernel
307
308       Log a message with version of the currently running kernel.
309
310           rlShowRunningKernel
311
312   Phases
313       rlPhaseStart
314
315       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
319           rlPhaseStart type [name]
320
321       type
322           Type of the phase, one of the following:
323
324           FAIL
325               When assert fails here, phase will report a FAIL.
326
327           WARN
328               When assert fails here, phase will report a WARN.
329
330       name
331           Optional name of the phase (if not provided, one will be
332           generated).
333
334       If all asserts included in the phase pass, phase reports PASS.
335
336       rlPhaseEnd
337
338       End current phase, summarize asserts included and report phase result.
339
340           rlPhaseEnd
341
342       Final phase result is based on included asserts and phase type.
343
344       rlPhaseStartSetup
345
346       rlPhaseStartTest
347
348       rlPhaseStartCleanup
349
350       Start a phase of the specified type: Setup -> WARN, Test -> FAIL,
351       Cleanup -> WARN.
352
353           rlPhaseStartSetup [name]
354           rlPhaseStartTest [name]
355           rlPhaseStartCleanup [name]
356
357       name
358           Optional name of the phase. If not specified, default
359           Setup/Test/Cleanup are used.
360
361       If you do not want these shortcuts, use plain "rlPhaseStart" function.
362
363   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
368   Metric
369       rlLogMetricLow
370
371       Log a metric, which should be as low as possible to the journal.
372       (Example: memory consumption, run time)
373
374           rlLogMetricLow name value [tolerance]
375
376       name
377           Name of the metric. It has to be unique in a phase.
378
379       value
380           Value of the metric.
381
382       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
386       When comparing FIRST, SECOND, then:
387
388           FIRST >= SECOND means PASS
389           FIRST+FIRST*tolerance >= SECOND means WARN
390           FIRST+FIRST*tolerance < SECOND means FAIL
391
392       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
395           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
401       rlLogMetricHigh
402
403       Log a metric, which should be as high as possible to the journal.
404       (Example: number of executions per second)
405
406           rlLogMetricHigh name value [tolerance]
407
408       name
409           Name of the metric. It has to be unique in a phase.
410
411       value
412           Value of the metric.
413
414       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
418       When comparing FIRST, SECOND, then:
419
420           FIRST <= SECOND means PASS
421           FIRST+FIRST*tolerance <= SECOND means WARN
422           FIRST+FIRST*tolerance > SECOND means FAIL
423
424   Manual Asserts
425       rlPass
426
427       Manual assertion, asserts and logs PASS.
428
429           rlPass comment
430
431       comment
432           Short test summary.
433
434       Returns 0 and asserts PASS.
435
436       rlFail
437
438       Manual assertion, asserts and logs FAIL.
439
440           rlFail comment
441
442       comment
443           Short test summary.
444
445       Returns 1 and asserts FAIL.
446
447   Arithmetic Asserts
448       rlAssert0
449
450       Assertion checking for the equality of parameter to zero.
451
452           rlAssert0 comment value
453
454       comment
455           Short test summary, e.g. "Test if compilation ended successfully".
456
457       value
458           Integer value (usually return code of a command).
459
460       Returns 0 and asserts PASS when "value == 0".
461
462       rlAssertEquals
463
464       Assertion checking for the equality of two parameters.
465
466           rlAssertEquals comment value1 value2
467
468       comment
469           Short test summary, e.g. "Test if all 3 packages have been
470           downloaded".
471
472       value1
473           First parameter to compare, can be a number or a string
474
475       value2
476           Second parameter to compare, can be a number or a string
477
478       Returns 0 and asserts PASS when "value1 == value2".
479
480       rlAssertNotEquals
481
482       Assertion checking for the non-equality of two parameters.
483
484           rlAssertNotEquals comment value1 value2
485
486       comment
487           Short test summary, e.g. "Test if return code is not 139".
488
489       value1
490           First parameter to compare, can be a number or a string
491
492       value2
493           Second parameter to compare, can be a number or a string
494
495       Returns 0 and asserts PASS when "value1 != value2".
496
497       rlAssertGreater
498
499       Assertion checking whether first parameter is greater than the second
500       one.
501
502           rlAssertGreater comment value1 value2
503
504       comment
505           Short test summary, e.g. "Test whether there are running more
506           instances of program."
507
508       value1
509           Integer value.
510
511       value2
512           Integer value.
513
514       Returns 0 and asserts PASS when "value1 > value2".
515
516       rlAssertGreaterOrEqual
517
518       Assertion checking whether first parameter is greater or equal to the
519       second one.
520
521           rlAssertGreaterOrEqual comment value1 value2
522
523       comment
524           Short test summary (e.g. "There should present at least one...")
525
526       value1
527           Integer value.
528
529       value2
530           Integer value.
531
532       Returns 0 and asserts PASS when "value1 X= value2".
533
534       rlAssertLesser
535
536       Assertion checking whether first parameter is lesser than the second
537       one.
538
539           rlAssertLesser comment value1 value2
540
541       comment
542           Short test summary, e.g. "Test whether there are running more
543           instances of program."
544
545       value1
546           Integer value.
547
548       value2
549           Integer value.
550
551       Returns 0 and asserts PASS when "value1 < value2".
552
553       rlAssertLesserOrEqual
554
555       Assertion checking whether first parameter is lesser or equal to the
556       second one.
557
558           rlAssertLesserOrEqual comment value1 value2
559
560       comment
561           Short test summary (e.g. "There should present at least one...")
562
563       value1
564           Integer value.
565
566       value2
567           Integer value.
568
569       Returns 0 and asserts PASS when "value1 X= value2".
570
571   File Asserts
572       rlAssertExists
573
574       Assertion checking for the existence of a file or a directory.
575
576           rlAssertExists file|directory
577
578       file|directory
579           Path to the file or directory.
580
581       Returns 0 and asserts PASS when "file" exists.
582
583       rlAssertNotExists
584
585       Assertion checking for the non-existence of a file or a directory.
586
587           rlAssertNotExists file|directory
588
589       file|directory
590           Path to the file or directory.
591
592       Returns 0 and asserts PASS when "file" does not exist.
593
594       rlAssertGrep
595
596       Assertion checking if the file contains a pattern.
597
598           rlAssertGrep pattern file [options]
599
600       pattern
601           Regular expression to be searched for.
602
603       file
604           Path to the file.
605
606       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
611       Returns 0 and asserts PASS when "file" exists and contains given
612       "pattern".
613
614       rlAssertNotGrep
615
616       Assertion checking that the file does not contain a pattern.
617
618           rlAssertNotGrep pattern file [options]
619
620       pattern
621           Regular expression to be searched for.
622
623       file
624           Path to the file.
625
626       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
631       Returns 0 and asserts PASS when "file" exists and does not contain
632       given "pattern".
633
634       rlAssertDiffer
635
636       Assertion checking that two files differ (are not identical).
637
638           rlAssertDiffer file1 file2
639
640       file1
641           Path to first file1
642
643       file2
644           Path to second file
645
646       Returns 0 and asserts PASS when "file1" and "file2" differs.
647
648       rlAssertNotDiffer
649
650       Assertion checking that two files do not differ (are identical).
651
652           rlAssertNotDiffer file1 file2
653
654       file1
655           Path to first file1
656
657       file2
658           Path to second file
659
660       Returns 0 and asserts PASS when "file1" and "file2" do not differ.
661
662   Run, Watch, Report
663       rlRun
664
665       Run command with optional comment and make sure its exit code matches
666       expectations.
667
668           rlRun [-t] [-l] [-c] [-s] command [status[,status...] [comment]]
669
670       -t  If specified, stdout and stderr of the command output will be
671           tagged with strings 'STDOUT: ' and 'STDERR: '.
672
673       -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
679       -c  Same as "-l", but only log the command output if it failed.
680
681       -s  Store stdout and stderr to a file (mixed together, as the user
682           would see it on a terminal) and set $rlRun_LOG variable to name of
683           the file. $rlRun_LOG is now actually an array where the first index
684           holds the last reference to the file.  Thus its behavior is not
685           changed if used without an index. The array is consumed by the
686           rlJournalEnd function to remove the leftover files, so no manual
687           files removal is needed anymore.  Note that if you need to use such
688           a file after calling the rlJournalEnd function you need to create
689           your own copy of the respective file.  When -t option is used, the
690           content of the file becomes tagged too.
691
692           If the -s option is not used, $rlRun_LOG is not modified and keeps
693           its content from the last "rlRun -s".
694
695       command
696           Command to run.
697
698       status
699           Expected exit code(s). Optional, default 0. If you expect more exit
700           codes, separate them with comma (e.g. "0,1" when both 0 and 1 are
701           OK and expected), or use from-to notation (i.e. "2-5" for
702           "2,3,4,5"), or combine them (e.g. "2-4,26" for "2,3,4,26").
703
704       comment
705           Short summary describing the action (optional, but recommended -
706           explain what you are doing here).
707
708       Returns the exit code of the command run. Asserts PASS when command\'s
709       exit status is in the list of expected exit codes.
710
711       Note:
712
713       •   The output of rlRun is buffered when using "-t", "-l" or "-s"
714           option (they use unix pipes, which are buffered by nature). If you
715           need an unbuffered output just make sure that "expect" package is
716           installed on your system (its "unbuffer" tool will automatically be
717           used to produce unbuffered output).
718
719       •   Be aware that there are some variables which can collide with your
720           code executed within rlRun. You should avoid using
721           __INTERNAL_rlRun_* variables.
722
723       •   When any of "-t" "-l", "-c", or "-s" option is used, special file
724           descriptors 111 and 112 are used to avoid the issue with incomplete
725           log file, bz1361246. As there might be an indefinite loop, there's
726           a timeout of two minutes implemented as a fix for bz1416796. Also
727           an error message is issued to signal the possibility of running
728           subprocess which keeps the file descriptors open.
729
730           Do not use these options if you expect process forking and
731           continuouse run. Try your own apropriate solution instead.
732
733       Warning: using "unbuffer" tool is now disabled because of bug 547686.
734
735       rlWatchdog
736
737       Run "command". If it does not finish in specified time, then kill it
738       using "signal".  Note that the command is executed in a sub-shell so
739       modified environment (e.g. set variables) is not relfected in the test
740       environment.
741
742           rlWatchdog command timeout [signal] [callback]
743
744       command
745           Command to run.
746
747       timeout
748           Timeout to wait, in seconds.
749
750       signal
751           Signal to use (optional, default KILL).
752
753       callback
754           Callback function to be called before the signal is send (optional,
755           none by default). The callback function will have one argument
756           available -- PGID of the process group.
757
758       Returns 0 if the command ends normally, without need to be killed.
759
760       rlReport
761
762       Report test result to the test harness. The command to be used for
763       reporting is set by the respective plugin. You can also use the
764       $BEAKERLIB_COMMAND_REPORT_RESULT variable to use your custom command.
765
766           rlReport name result [score] [log]
767
768       name
769           Name of the test result.
770
771       result
772           Result (one of PASS, WARN, FAIL). If called with something else,
773           will use WARN.
774
775       score
776           Test score (optional).
777
778       log Optional log file to be submitted instead of default "OUTPUTFILE".
779
780       rlCmpVersion
781
782       Compare two given versions composed by numbers and letters divided by
783       dot (.), underscore (_), or dash (-).
784
785           rlCmpVersion ver1 ver2
786
787       If ver1 = ver2, sign '=' is printed to stdout and 0 is returned.  If
788       ver1 > ver2, sign '>' is printed to stdout and 1 is returned.  If ver1
789       < ver2, sign '<' is printed to stdout and 2 is returned.
790
791       rlTestVersion
792
793       Test releation between two given versions based on given operator.
794
795           rlTestVersion ver1 op ver2
796
797       op  Operator defining the logical expression.  It can be '=', '==',
798           '!=', '<', '<=', '=<', '>', '>=', or '=>'.
799
800       Returns 0 if the expresison ver1 op ver2 is true; 1 if the expression
801       is false and 2 if something went wrong.
802
803   Release Info
804       rlIsRHEL
805
806           rlIsRHEL [VERSION_SPEC]...
807
808       VERSION_SPEC
809           Argument specifies version of particular RHEL distribution, eg. 8,
810           8.4 ">8.4".
811
812           For more details see description of "rlIsOSVersion".
813
814       Returns 0 when we're running on RHEL.  With given version specification
815       in arguments returns 0 if the particular RHEL version is running.
816
817       Prototype:
818
819           rlIsRHEL
820
821         Returns 0 if we are running on RHEL.
822
823           rlIsRHEL 7 '>=8.5'
824
825         Returns 0 if we are running any RHEL 7 or RHEL 8.5 and higher.
826
827       rlIsFedora
828
829           rlIsFedora [VERSION_SPEC]...
830
831       VERSION_SPEC
832           Argument specifies version of particular Fedora distribution, eg.
833           30, ">30".
834
835           For more details see description of "rlIsOSVersion".
836
837       Returns 0 when we're running on Fedora.  With given version
838       specification in arguments returns 0 if the particular Fedora version
839       is running.
840
841       Prototype:
842
843           rlIsFedora
844
845         Returns 0 if we are running on Fedora.
846
847           rlIsFedora 30 32
848
849         Returns 0 if we are running Fedora 30 or 32.
850
851       rlIsCentOS
852
853           rlIsCentOS [VERSION_SPEC]...
854
855       VERSION_SPEC
856           Argument specifies version of particular CentOS distribution, eg.
857           7, ">7".
858
859           For more details see description of "rlIsOSVersion".
860
861       Returns 0 when we're running on CentOS.  With given version
862       specification in arguments returns 0 if the particular CentOS version
863       is running.
864
865       Prototype:
866
867           rlIsCentOS
868
869         Returns 0 if we are running on CentOS.
870
871           rlIsCentOS 7.1 6
872
873         Returns 0 if we are running CentOS 7.1 or any CentOS 6.
874
875       rlIsOS
876
877           rlIsOS ID
878
879       ID  Argument is based on contents of /etc/os-release.  Possible options
880           of ID are e.g. fedora, rhel, centos, ol.
881
882       Returns 0 when we're running on system with respective ID.  Returns 1
883       when parameter does not match with ID in os-release.  Returns 2 when
884       there is no ID defined.  Returns 3 when no argument is given.
885
886       Prototype:
887
888           rlIsOS rhel
889
890         Returns 0 if we are running on RHEL.
891
892       rlIsOSLike
893
894           rlIsOSLike ID_LIKE
895
896       ID_LIKE
897           Argument is based on contents of /etc/os-release.  Possible options
898           of ID_LIKE are e.g. fedora, rhel.
899
900       Returns 0 when we're running on system with requested ID_LIKE.  Returns
901       1 when parameter does not match with ID nor ID_LIKE in os-release.
902       Returns 2 when there is no ID or ID_LIKE defined.  Returns 3 when no
903       argument is given.
904
905       Prototype:
906
907           rlIsOSLike rhel
908
909         Returns 0 if we are running on RHEL, CentOS, Rocky Linux, etc..
910
911           rlIsOSLike fedora
912
913         Returns 0 if we are running on Fedora, RHEL, CentOS, Oracle Linux, etc..
914
915       rlIsOSVersion
916
917           rlIsOsVersion VERSION_SPEC...
918
919       VERSION_SPEC
920           Parameter is based on VERSION_ID in /etc/os-release.  It consists
921           of either "major" or "major"."minor" refering to a particular
922           release.
923
924           It accepts multiple arguments separated by space (8.1 8.2 8.3 9).
925
926           To specify a group of distributions optional operator can be passed
927           in argument together with the version number as one string
928           ('>8.5').  Operator can be '<', '<=', '=<', '=', '>', '>=' matching
929           whether the currently installed version is lesser, lesser or equal,
930           equal, equal or greater, greater than the version number supplied
931           as second half of the argument.
932
933           Note that when using >/< operators you have to either put the
934           argument in quotes or escape the operators to avoid them being
935           interpreted as bash redirection operator.
936
937       Returns 0 when we're running distribution of the particular version
938       requested by the argument.
939
940       It usually follows after "rlIsOS" and "rlIsOSLike".
941
942       Be cautious when using together with "rlIsOSLike" as different
943       distributions may use different versioning schema.
944
945       Prototype:
946
947          rlIsOSVersion 6 7 9
948
949         Returns 0 if we are running distribution with VERSION_ID 6, 7 or 9.
950
951           rlIsOSVersion 7.8 8
952
953         Returns 0 if we are running distribution 7.8 or any 8.
954
955           rlIsOSVersion ">=7.5" or rlIsOSVersion \>=7.5
956
957         Returns 0 if we are running distribution 7.5 or higher (both minors or majors).
958
959       Note:
960
961           rlIsOSVersion '<7.5' || rlIsOSVersion '<8.5'
962
963         would also cover 7.9 as it is less than 8.5, which is not what you want.
964         So if you want to construct a condition for a distribution <7.5 within the major 7 or
965         a distribution <8.5 within the major 8 you actually need to use following construct:
966
967           rlIsOSVersion 7 && rlIsOSVersion '<7.5' || rlIsOSVersion 8 && rlIsOSVersion '<8.5'
968
969         This returns 0 when running distribution less than 7.5 and less then 8.5, but not 7.9 (nor 6.9).
970
971       rlIsRHELLike
972
973           rlIsRHELLike [VERSION_SPEC]...
974
975       VERSION_SPEC
976           Argument specifies version of particular RHEL distribution, eg. 8,
977           8.4 ">8.4".
978
979           For more details see description of "rlIsOSVersion".
980
981       Returns 0 when we're running on RHEL-like distribution.  These are
982       considered to be RHEL, CentOS, Rocky Linux, etc..  With given version
983       specification in arguments returns 0 if the particular version of RHEL-
984       like distribution is running.
985
986       Prototype:
987
988           rlIsRHELLike
989
990         Returns 0 if we are running on RHEL-like system.
991
992           rlIsRHELLike ">=6"
993
994         Returns 0 if we are running on RHEL-like distribution of version 6.0 or higher.
995
996   Rpm Handling
997       rlCheckRpm
998
999       Check whether a package is installed.
1000
1001           rlCheckRpm name [version] [release] [arch]
1002
1003       name
1004           Package name like "kernel"
1005
1006       version
1007           Package version like 2.6.25.6
1008
1009       release
1010           Package release like "55.fc9"
1011
1012       arch
1013           Package architucture like "i386"
1014
1015       Returns 0 if the specified package is installed.
1016
1017       rlAssertRpm
1018
1019       Assertion making sure that a package is installed.
1020
1021           rlAssertRpm name [version] [release] [arch]>
1022           rlAssertRpm --all
1023
1024       name
1025           Package name like "kernel"
1026
1027       version
1028           Package version like 2.6.25.6
1029
1030       release
1031           Package release like "55.fc9"
1032
1033       arch
1034           Package architucture like "i386"
1035
1036       --all
1037           Assert all packages listed in the $PACKAGES $REQUIRES and
1038           $COLLECTIONS environment variables.
1039
1040       Returns 0 and asserts PASS if the specified package is installed.
1041
1042       rlAssertNotRpm
1043
1044       Assertion making sure that a package is not installed. This is just
1045       inverse of "rlAssertRpm".
1046
1047           rlAssertNotRpm name [version] [release] [arch]>
1048
1049       name
1050           Package name like "kernel"
1051
1052       version
1053           Package version like 2.6.25.6
1054
1055       release
1056           Package release like "55.fc9"
1057
1058       arch
1059           Package architucture like "i386"
1060
1061       Returns 0 and asserts PASS if the specified package is not installed.
1062
1063       Example
1064
1065       Function "rlAssertRpm" is useful especially in prepare phase where it
1066       causes abort if a package is missing, while "rlCheckRpm" is handy when
1067       doing something like:
1068
1069           if ! rlCheckRpm package; then
1070                yum install package
1071                rlAssertRpm package
1072           fi
1073
1074       rlAssertBinaryOrigin
1075
1076       Assertion making sure that given binary is owned by (one of) the given
1077       package(s).
1078
1079           rlAssertBinaryOrigin binary package [package2 [...]]
1080           PACKAGES=... rlAssertBinaryOrigin binary
1081
1082       binary
1083           Binary name like "ksh" or "/bin/ksh"
1084
1085       package
1086           List of packages like "ksh mksh". The parameter is optional. If
1087           missing, contents of environment variable $PACKAGES are taken into
1088           account.
1089
1090       Returns 0 and asserts PASS if the specified binary belongs to (one of)
1091       the given package(s).  Returns 1 and asserts FAIL if the specified
1092       binary does not belong to (any of) the given package(s).  Returns 2 and
1093       asserts FAIL if the specified binary is not found.  Returns 3 and
1094       asserts FAIL if no packages are given.  Returns 100 and asserts FAIL if
1095       invoked with no parameters.
1096
1097       Example
1098
1099       Function "rlAssertBinaryOrigin" is useful especially in prepare phase
1100       where it causes abort if a binary is missing or is owned by different
1101       package:
1102
1103           PACKAGES=mksh rlAssertBinaryOrigin ksh
1104           or
1105           rlAssertBinaryOrigin ksh mksh
1106
1107       Returns true if ksh is owned by the mksh package (in this case:
1108       /bin/ksh is a symlink pointing to /bin/mksh).
1109
1110       rlGetMakefileRequires
1111
1112       Prints space separated list of requirements defined in Makefile using
1113       'Requires' attribute.
1114
1115       Return 0 if success.
1116
1117       rlGetYAMLdeps
1118
1119       Prints space separated list of requirements defined in metadata.yaml
1120       using 'require' and / or 'recommend' attribute.
1121
1122       Full fmf ids and library references are to be ignored.
1123
1124           rlGetYAMLdeps DEP_TYPE [array_var_name]
1125
1126       DEP_TYPE
1127           Dependency type defined as a regexp. Expected values are 'require',
1128           'recommend', or 'require|recommend'. The matching attribute values
1129           are then processed.  Defaults to 'require'.
1130
1131       array_var_name
1132           Name of the variable to put the output to in a form of an array.
1133           This can hold also dependencies with specific version.  If used,
1134           the output to stdout is suppressed.
1135
1136       Return 0 if success.
1137
1138       rlCheckRequirements
1139
1140       Check that all given requirements are covered eigther by installed
1141       package or by binary available in PATHs or by some package's provides.
1142
1143           rlRun "rlCheckRequirements REQ..."
1144
1145       REQ Requirement to be checked. It can be package name, provides string
1146           or binary name. Moreover, the requirement can be written the same
1147           way as the Require in the spec file, including the version
1148           specification, e.g. "bash >= 4.4".  The comparsion operator may be
1149           any of supported by rlTestVersion(), see its manual.
1150
1151       Returns number of unsatisfied requirements.
1152
1153       rlCheckMakefileRequires
1154
1155       Check presence of required packages / binaries defined in metadata.yaml
1156       provided by "tmt" or Makefile of the test.
1157
1158       Also check presence of recommended packages / binaries defined in
1159       metadata.yaml provided by "tmt". These however do not participate on
1160       the return code, these are just informative.
1161
1162       Example
1163
1164           rlRun "rlCheckMakefileRequires"
1165
1166       Return 255 if requirements could not be retrieved, 0 if all
1167       requirements are satisfied or number of unsatisfied requirements.
1168
1169       rlGetRequired =head3 rlGetRecommended
1170
1171       Get a list of required or recommended packages / binaries defined in
1172       metadata.yaml provided by "tmt" or in a Makefile of the test.
1173
1174           rlGetRequired [ARRAY_VAR_NAME]
1175           rlGetRecommended [ARRAY_VAR_NAME]
1176
1177       ARRAY_VAR_NAME
1178           If provided the variable is populated as an array with the
1179           respective dependencies. Otherwise the dependencies are printed out
1180           to the STDOUT.
1181
1182       Return 255 if requirements could not be retrieved, 0 otherwise.
1183
1184       rlCheckRequired =head3 rlCheckRecommended =head3 rlCheckDependencies
1185
1186       Check presence of required, recommended or both packages / binaries
1187       defined in metadata.yaml provided by "tmt" or in a Makefile of the
1188       test.
1189
1190       Example
1191
1192           rlRun "rlCheckRequired"
1193           rlRun "rlCheckRecommended"
1194           rlRun "rlCheckDependencies"
1195
1196       Return 255 if requirements could not be retrieved, 0 if all
1197       requirements are satisfied or number of unsatisfied requirements.
1198
1199       rlAssertRequired
1200
1201       Ensures that all required packages provided in either metadata.yaml or
1202       Makefile are installed.
1203
1204           rlAssertRequired
1205
1206       Prints out a verbose list of installed/missing packages during
1207       operation.
1208
1209       Returns 0 if all required packages are installed, 1 if one or more
1210       packages are missing or if no Makefile is present.
1211
1212   Getting RPMs
1213       Download methods
1214
1215       Functions handling rpm downloading/installing can use more methods for
1216       actual download of the rpm.
1217
1218       Currently there are two download methonds available:
1219
1220       direct
1221           Use use dirct download from build system (brew).
1222
1223       yum Use yumdownloader or dnf download.
1224
1225       The methods and their order are defined by
1226       BEAKERLIB_RPM_DOWNLOAD_METHODS variable as space separated list. By
1227       default it is 'direct yum'. This can be overridden by user.  There may
1228       be done also additions  or changes to the original value, e.g.
1229       BEAKERLIB_RPM_DOWNLOAD_METHODS='yum
1230       ${BEAKERLIB_RPM_DOWNLOAD_METHODS/yum/}'
1231
1232
1233
1234       Beakerlib is prepared for more Koji-based sources of packages while
1235       usigng direct download method. By default packages are fetched from
1236       Koji, particularly from https://kojipkgs.fedoraproject.org/packages.
1237
1238       rlRpmInstall
1239
1240       Try to install specified package from local Red Hat sources.
1241
1242           rlRpmInstall [--quiet] package version release arch
1243
1244       --quiet
1245           Make the download and the install process be quiet.
1246
1247       package
1248           Package name like "kernel"
1249
1250       version
1251           Package version like 2.6.25.6
1252
1253       release
1254           Package release like "55.fc9"
1255
1256       arch
1257           Package arch like "i386"
1258
1259       Returns 0 if specified package was installed successfully.
1260
1261       rlRpmDownload
1262
1263       Try to download specified package.
1264
1265           rlRpmDownload [--quiet] {package version release arch|N-V-R.A}
1266           rlRpmDownload [--quiet] --source {package version release|N-V-R}
1267
1268       --quiet
1269           Make the download process be quiet.
1270
1271       package
1272           Package name like "kernel"
1273
1274       version
1275           Package version like 2.6.25.6
1276
1277       release
1278           Package release like "55.fc9"
1279
1280       arch
1281           Package arch like "i386"
1282
1283       Returns 0 if specified package was downloaded successfully.
1284
1285       rlFetchSrcForInstalled
1286
1287       Tries various ways to download source rpm for specified installed rpm.
1288
1289           rlFetchSrcForInstalled [--quiet] package
1290
1291       --quiet
1292           Make the download process be quiet.
1293
1294       package
1295           Installed package name like "kernel". It accepts in-direct names.
1296           E.g. for the package name "krb5-libs" the function will download
1297           the "krb5" source rpm.
1298
1299       Returns 0 if the source package was successfully downloaded.
1300
1301   Mounting
1302       rlMount
1303
1304       Create mount point (if neccessary) and mount a NFS share.
1305
1306           rlMount [-o MOUNT_OPTS] server share mountpoint
1307
1308       server
1309           NFS server hostname.
1310
1311       share
1312           Shared directory name.
1313
1314       mountpoint
1315           Local mount point.
1316
1317       MOUNT_OPTS
1318           Mount options.
1319
1320       Returns 0 if mounting the share was successful.
1321
1322       rlCheckMount
1323
1324       Check either if a directory is a mountpoint, if it is a mountpoint to a
1325       specific server, or if it is a mountpoint to a specific export on a
1326       specific server and if it uses specific mount options.
1327
1328           rlCheckMount [-o MOUNT_OPTS] mountpoint
1329           rlCheckMount [-o MOUNT_OPTS] server mountpoint
1330           rlCheckMount [-o MOUNT_OPTS] server share mountpoint
1331
1332       mountpoint
1333           Local mount point.
1334
1335       server
1336           NFS server hostname
1337
1338       share
1339           Shared directory name
1340
1341       MOUNT_OPTS
1342           Mount options to check (comma separated list)
1343
1344       With one parameter, returns 0 when specified directory exists and is a
1345       mountpoint. With two parameters, returns 0 when specific directory
1346       exists, is a mountpoint and an export from specific server is mounted
1347       there. With three parameters, returns 0 if a specific shared directory
1348       is mounted on a given server on a given mountpoint
1349
1350       If the -o option is provided, returns 0 if the mountpoint uses all the
1351       given options, 2 otherwise.
1352
1353       rlAssertMount
1354
1355       Assertion making sure that given directory is a mount point, if it is a
1356       mountpoint to a specific server, or if it is a mountpoint to a specific
1357       export on a specific server and if it uses specific mount options.
1358
1359           rlAssertMount [-o MOUNT_OPTS]  mountpoint
1360           rlAssertMount [-o MOUNT_OPTS]  server mountpoint
1361           rlAssertMount [-o MOUNT_OPTS]  server share mountpoint
1362
1363       mountpoint
1364           Local mount point.
1365
1366       server
1367           NFS server hostname
1368
1369       share
1370           Shared directory name
1371
1372       MOUNT_OPTS
1373           Mount options to check (comma separated list)
1374
1375       With one parameter, returns 0 when specified directory exists and is a
1376       mountpoint. With two parameters, returns 0 when specific directory
1377       exists, is a mountpoint and an export from specific server is mounted
1378       there. With three parameters, returns 0 if a specific shared directory
1379       is mounted on a given server on a given mountpoint. Asserts PASS when
1380       the condition is true.
1381
1382       If the -o option is provided, asserts PASS if the above conditions are
1383       met and the mountpoint uses all the given options.
1384
1385       rlHash, rlUnhash
1386
1387       Hashes/Unhashes given string and prints the result to stdout.
1388
1389           rlHash [--decode] [--algorithm HASH_ALG] --stdin|STRING
1390           rlUnhash [--algorithm HASH_ALG] --stdin|STRING
1391
1392       --decode
1393           Unhash given string.
1394
1395       --algorithm
1396           Use given hash algorithm.  Currently supported algorithms:
1397             base64
1398             base64_ - this is standard base64 where '=' is replaced by '_'
1399             hex
1400
1401           Defaults to hex.  Default algorithm can be override using global
1402           variable rlHashAlgorithm.
1403
1404       --stdin
1405           Get the string from stdin.
1406
1407       STRING
1408           String to be hashed/unhashed.
1409
1410       Returns 0 if success.
1411
1412   Backup and Restore
1413       rlFileBackup
1414
1415       Create a backup of files or directories (recursive). Can be used
1416       multiple times to add more files to backup. Backing up an already
1417       backed up file overwrites the original backup.
1418
1419           rlFileBackup [--clean] [--namespace name] [--missing-ok|--no-missing-ok] file [file...]
1420
1421       You can use "rlRun" for asserting the result but keep in mind meaning
1422       of exit codes, especialy exit code 8, if using without --clean option.
1423
1424       --clean
1425           If this option is provided (has to be the first option of the
1426           command), then file/dir backed up using this command (provided in
1427           next options) will be (recursively) removed before we restore it.
1428           This option implies --missing-ok, which can be overridden by
1429           --no-missing-ok.
1430
1431       --namespace name
1432           Specifies the namespace to use.  Namespaces can be used to separate
1433           backups and their restoration.
1434
1435       --missing-ok
1436           Do not raise an error in case of missing file to backup.
1437
1438       --no-missing-ok
1439           Do raise an error in case of missing file to backup.  This is
1440           useful with --clean. This behaviour can be globally set by global
1441           variable BEAKERLIB_FILEBACKUP_MISSING_OK=false.
1442
1443       file
1444           Files and/or directories to be backed up.
1445
1446       Returns 0 if the backup was successful.  Returns 1 if parsing of
1447       parameters was not successful.  Returns 2 if no files specification was
1448       provided.  Returns 3 if BEAKERLIB_DIR variable is not set, e.g.
1449       rlJournalStart was not executed.  Returns 4 if creating of main backup
1450       destination directories was not successful.  Returns 5 if creating of
1451       file specific backup destination directories was not successful.
1452       Returns 6 if the copy of backed up files was not successful.  Returns 7
1453       if attributes of backed up files were not successfuly copied.  Returns
1454       8 if backed up files do not exist. This can be suppressed based on
1455       other options.
1456
1457       Example with --clean:
1458
1459           touch cleandir/aaa
1460           rlRun "rlFileBackup --clean cleandir/"
1461           touch cleandir/bbb
1462           ls cleandir/
1463           aaa   bbb
1464           rlRun "rlFileRestore"
1465           ls cleandir/
1466           aaa
1467
1468       rlFileRestore
1469
1470       Restore backed up files to their original location.  "rlFileRestore"
1471       does not remove new files appearing after backup has been made.  If you
1472       don't want to leave anything behind just remove the whole original tree
1473       before running "rlFileRestore", or see "--clean" option of
1474       "rlFileBackup".
1475
1476           rlFileRestore [--namespace name]
1477
1478       You can use "rlRun" for asserting the result.
1479
1480       --namespace name
1481           Specifies the namespace to use.  Namespaces can be used to separate
1482           backups and their restoration.
1483
1484       Returns 0 if backup dir is found and files are restored successfully.
1485
1486       Return code bits meaning:
1487
1488           XXXXX
1489           |||||
1490           ||||\_ error parsing parameters
1491           |||\__ could not find backup directory
1492           ||\___ files cleanup failed
1493           |\____ files restore failed
1494           \_____ no files were restored nor cleaned
1495
1496   Services
1497       Following routines implement comfortable way how to start/stop system
1498       services with the possibility to restore them to their original state
1499       after testing.
1500
1501       rlServiceStart
1502
1503       Make sure the given "service" is running with fresh configuration.
1504       (Start it if it is stopped and restart if it is already running.) In
1505       addition, when called for the first time, the current state is saved so
1506       that the "service" can be restored to its original state when testing
1507       is finished, see "rlServiceRestore".
1508
1509           rlServiceStart service [service...]
1510
1511       service
1512           Name of the service(s) to start.
1513
1514       Returns number of services which failed to start/restart; thus zero is
1515       returned when everything is OK.
1516
1517       rlServiceStop
1518
1519       Make sure the given "service" is stopped. Stop it if it is running and
1520       do nothing when it is already stopped. In addition, when called for the
1521       first time, the current state is saved so that the "service" can be
1522       restored to its original state when testing is finished, see
1523       "rlServiceRestore".
1524
1525           rlServiceStop service [service...]
1526
1527       service
1528           Name of the service(s) to stop.
1529
1530       Returns number of services which failed to become stopped; thus zero is
1531       returned when everything is OK.
1532
1533       rlServiceRestore
1534
1535       Restore given "service" into its original state (before the first
1536       "rlServiceStart" or "rlServiceStop" was called). If "rlServiceStart"
1537       was called on already running "service", "rlServiceRestore" will
1538       restart the "service" when restoring its state.
1539
1540           rlServiceRestore [service...]
1541
1542       service
1543           Name of the service(s) to restore to original state.  All services
1544           will be restored in reverse order if no service name is given.
1545
1546       Returns number of services which failed to get back to their original
1547       state; thus zero is returned when everything is OK.
1548
1549       rlServiceStatus
1550
1551       Print status (output of `service SERVICE status` or `systemctl status
1552       SERVICE`) of given "SERVICE".
1553
1554           rlServiceStatus SERVICE [SERVICE...]
1555
1556       SERVICE
1557           The service to get the status of.
1558
1559       Returns service status return code of the last provided SERVICE.
1560
1561       rlServiceEnable
1562
1563       Enables selected services if needed, or does nothing if already
1564       enabled.  In addition, when called for the first time, the current
1565       state is saved so that the "service" can be restored to its original
1566       state when testing is finished, see "rlServiceRestore".
1567
1568           rlServiceEnable service [service...]
1569
1570       service
1571           Name of the service(s) to enable.
1572
1573       Returns number of services which failed enablement; thus zero is
1574       returned when everything is OK.
1575
1576       rlServiceDisable
1577
1578       Disables selected services if needed, or does nothing if already
1579       disabled.  In addition, when called for the first time, the current
1580       state is saved so that the "service" can be restored to its original
1581       state when testing is finished, see "rlServiceRestore".
1582
1583           rlServiceDisable service [service...]
1584
1585       service
1586           Name of the service(s) to disable.
1587
1588       Returns number of services which failed disablement; thus zero is
1589       returned when everything is OK.
1590
1591   Sockets
1592       Following routines implement comfortable way how to start/stop system
1593       sockets with the possibility to restore them to their original state
1594       after testing.
1595
1596       rlSocketStart
1597
1598       Make sure the given "socket" is running. (Start it if stopped, leave it
1599       if already running.) In addition, when called for the first time, the
1600       current state is saved so that the "socket" can be restored to its
1601       original state when testing is finished, see "rlSocketRestore".
1602
1603           rlSocketStart socket [socket...]
1604
1605       socket
1606           Name of the socket(s) to start.
1607
1608       Returns number of sockets which failed to start/restart; thus zero is
1609       returned when everything is OK.
1610
1611       rlSocketStop
1612
1613       Make sure the given "socket" is stopped. Stop it if it is running and
1614       do nothing when it is already stopped. In addition, when called for the
1615       first time, the current state is saved so that the "socket" can be
1616       restored to its original state when testing is finished, see
1617       "rlSocketRestore".
1618
1619           rlSocketStop socket [socket...]
1620
1621       socket
1622           Name of the socket(s) to stop.
1623
1624       Returns number of sockets which failed to become stopped; thus zero is
1625       returned when everything is OK.
1626
1627       rlSocketRestore
1628
1629       Restore given "socket" into its original state (before the first
1630       "rlSocketStart" or "rlSocketStop" was called).
1631
1632       Warning !!!  Xinetd process [even though it might have been used] is
1633       NOT restored. It is recommended to call rlServiceRestore xinetd as
1634       well.
1635
1636           rlSocketRestore socket [socket...]
1637
1638       socket
1639           Name of the socket(s) to restore to original state.
1640
1641       Returns number of sockets which failed to get back to their original
1642       state; thus zero is returned when everything is OK.
1643
1644   Cleanup management
1645       Cleanup management works with a so-called cleanup buffer, which is a
1646       temporary representation of what should be run at cleanup time, and a
1647       final cleanup script (executable), which is generated from this buffer
1648       and wraps it using BeakerLib essentials (journal initialization,
1649       cleanup phase, ...).  The cleanup script must always be updated on an
1650       atomic basis (filesystem-wise) to allow an asynchronous execution by a
1651       third party (ie. test watcher).
1652
1653       The test watcher usage is mandatory for the cleanup management system
1654       to work properly as it is the test watcher that executes the actual
1655       cleanup script.  Limited, catastrophe-avoiding mechanism is in place
1656       even when the test is not run in test watcher, but that should be seen
1657       as a backup and such situation is to be avoided whenever possible.
1658
1659       The cleanup script shares all environment (variables, exported or not,
1660       and functions) with the test itself - the cleanup append/prepend
1661       functions "sample" or "snapshot" the environment at the time of their
1662       call, IOW any changes to the test environment are synchronized to the
1663       cleanup script only upon calling append/prepend.  When the
1664       append/prepend functions are called within a function which has local
1665       variables, these will appear as global in the cleanup.
1666
1667       While the cleanup script receives $PWD from the test, its working dir
1668       is set to the initial test execution dir even if $PWD contains
1669       something else. It is impossible to use relative paths inside cleanup
1670       reliably - certain parts of the cleanup might have been added under
1671       different current directories (CWDs).  Therefore always use absolute
1672       paths in append/prepend cleanup or make sure you never 'cd' elsewhere
1673       (ie. to a TmpDir).
1674
1675       rlCleanupAppend
1676
1677       Appends a string to the cleanup buffer and recreates the cleanup
1678       script.
1679
1680           rlCleanupAppend string
1681
1682       Returns 0 if the operation was successful, 1 otherwise.
1683
1684       rlCleanupPrepend
1685
1686       Prepends a string to the cleanup buffer and recreates the cleanup
1687       script.
1688
1689           rlCleanupPrepend string
1690
1691       Returns 0 if the operation was successful, 1 otherwise.
1692
1693   Time Performance
1694       rlPerfTime_RunsInTime
1695
1696       Measures, how many runs of some commands can be done in specified time.
1697       This approach is suitable for short-time running tasks (up to few
1698       seconds), where averaging few runs is not precise. This is done several
1699       times, and the final result is the average of all runs. It prints the
1700       number on stdout, so it has to be captured.
1701
1702           rlPerfTime_RunsInTime command [time] [runs]
1703
1704       command
1705           Command to run.
1706
1707       time
1708           Time in seconds (optional, default=30).
1709
1710       runs
1711           Number of averaged runs (optional, default=3).
1712
1713       rlPerfTime_AvgFromRuns
1714
1715       Measures the average time of running some task. This approach is
1716       suitable for long-time running tasks (tens of seconds and more), where
1717       it is precise enough. Measured runs can be preceded by dry run, which
1718       is not measured and it's purpose is to warm up various caches.  It
1719       prints the number on stdout, so it has to be captured.  Or, result is
1720       then stored in special rl_retval variable.
1721
1722           rlPerfTime_AvgFromRuns command [count] [warmup]
1723
1724       command
1725           Command to run.
1726
1727       count
1728           Times to run (optional, default=3).
1729
1730       warmup
1731           Warm-up run, run if this option is not "warmup" (optional,
1732           default="warmup")
1733
1734   Analyze
1735       rlDejaSum
1736
1737       TODO description
1738
1739           rlDejaSum par1 par2
1740
1741       par1
1742           TODO description
1743
1744       par2
1745           TODO description
1746
1747       Return 0 if... TODO
1748
1749       rlImport
1750
1751       Imports code provided by one or more libraries into the test namespace.
1752       The library search mechanism is based on Beaker test hierarchy system,
1753       i.e.:
1754
1755       /component/type/test-name/test-file
1756
1757       When test-file calls rlImport with 'foo/bar' parameter, the libraries
1758       are searched in following locations: these are the possible path
1759       prefixes
1760
1761           - colon-separated paths from $BEAKERLIB_LIBRARY_PATH
1762           - /mnt/tests
1763           - /usr/share/beakerlib-libraries
1764
1765       the next component of the path is one of the following:
1766
1767           - /foo/Library/bar
1768           - /foo/bar
1769           - /libs/foo/bar
1770           - /*/foo/Library/bar
1771           - /libs/*/foo/Library/bar
1772           - /libs/*/foo/bar
1773
1774       the directory path is then constructed as prefix/path/lib.sh If the
1775       library is still not found an upwards directory traversal is used, and
1776       a check for presence of the library in the above mentioned possible
1777       paths is to be performed. This means this function needs to be called
1778       from the test hierarchy, not e.g. the /tmp directory.
1779
1780       Once library is found, it is sourced and a verifier function is called.
1781       The verifier function is cunstructed by composing the library prefix
1782       and LibraryLoaded. Library prefix must be defined in the library
1783       itself.  It should be part of lib.sh header in format: '#   library-
1784       prefix = <PREFIX>'.  If the verifier passes the library is ready to
1785       use. Also variable <PREFIX>LibraryDir is created and it points to the
1786       library folder.
1787
1788       Usage:
1789
1790           rlImport --all
1791           rlImport LIBRARY [LIBRARY2...]
1792
1793       --all
1794           Read $BEAKERLIB_DIR/metadata.yaml or ./Makefile, pickup the library
1795           requirements and import them all.
1796
1797       LIBRARY
1798           Must have 'component[/path]' format. Identifies the library to
1799           import.
1800
1801       Returns 0 if the import of all libraries was successful. Returns non-
1802       zero if one or more library failed to import.
1803
1804   Process Synchronisation
1805       rlWaitForCmd
1806
1807       Pauses script execution until command exit status is the expeced value.
1808       Logs a WARNING and returns 1 if the command didn't exit successfully
1809       before timeout elapsed or a maximum number of invocations has been
1810       reached.
1811
1812           rlWaitForCmd command [-p PID] [-t time] [-m count] [-d delay] [-r retval]
1813
1814       command
1815           Command that will be executed until its return code is equal 0 or
1816           value speciefied as option to '-r'.
1817
1818       -t time
1819           Timeout in seconds, default=120. If the command doesn't return 0
1820           before time elapses, the command will be killed.
1821
1822       -p PID
1823           PID of the process to check before running command. If the process
1824           exits before the socket is opened, the command will log a WARNING.
1825
1826       -m count
1827           Maximum number of 'command' executions before continuing anyway.
1828           Default is infite. Returns 1 if the maximum was reached.
1829
1830       -d delay
1831           Delay between 'command' invocations. Default 1.
1832
1833       -r retval
1834           Expected return value of command. Default 0.
1835
1836       rlWaitForFile
1837
1838       Pauses script execution until specified file or directory starts
1839       existing.  Returns 0 if file started existing, 1 if timeout was reached
1840       or PID exited.  Return code is greater than 1 in case of error.
1841
1842           rlWaitForFile path [-p PID] [-t time] [-d delay]
1843
1844       path
1845           Path to file that should start existing.
1846
1847       -t time
1848           Timeout in seconds (optional, default=120). If the file isn't
1849           opened before the time elapses the command returns 1.
1850
1851       -p PID
1852           PID of the process that should also be running. If the process
1853           exits before the file is created, the command returns with status
1854           code of 1.
1855
1856       -d delay
1857           Delay between subsequent checks for existence of file. Default 1.
1858
1859       rlWaitForSocket
1860
1861       Pauses script execution until local socket starts listening.  Returns 0
1862       if socket started listening, 1 if timeout was reached or PID exited.
1863       Return code is greater than 1 in case of error.
1864
1865           rlWaitForSocket {port|path} [-p PID] [-t time] [-d delay] [--close] [--remote]
1866
1867       port|path
1868           Network port to wait for opening or a path to UNIX socket.  Regular
1869           expressions are also supported.
1870
1871       -t time
1872           Timeout in seconds (optional, default=120). If the socket isn't
1873           opened before the time elapses the command returns 1.
1874
1875       -p PID
1876           PID of the process that should also be running. If the process
1877           exits before the socket is opened, the command returns with status
1878           code of 1.
1879
1880       -d delay
1881           Delay between subsequent checks for availability of socket. Default
1882           1.
1883
1884       --close
1885           Wait for the socket to stop listening.
1886
1887       --remote
1888           Wait for the remote socket to start listening instead of local one.
1889
1890       rlWait
1891
1892       Wrapper around bash builtin 'wait' command. See bash_builtins(1) man
1893       page.  Kills the process and all its children if the timeout elapses.
1894
1895           rlWaitFor [n ...] [-s SIGNAL] [-t time]
1896
1897       n   List of PIDs to wait for. They need to be background tasks of
1898           current shell.  See bash_builtins(1) section for 'wait' command.
1899
1900       -t time
1901           Timeout in seconds (optional, default=30). If the wait isn't
1902           successful before the time elapses then all specified tasks are
1903           killed.
1904
1905       -s SIGNAL
1906           Signal used to kill the process, optional SIGTERM by default.
1907
1908   Virtual X Server
1909       Functions providing simple way how to start and stop virtual X server.
1910
1911       rlVirtualXStart
1912
1913       Start a virtual X server on a first free display. Tries only first N
1914       displays, so you can run out of them.
1915
1916           rlVirtualXStart name [N]
1917
1918       name
1919           String identifying the X server.
1920
1921       N   Maximum number of displays to try. Defaults to 3.
1922
1923       Returns 0 when the server is started successfully.
1924
1925       rlVirtualXGetDisplay
1926
1927       Get the DISPLAY variable for specified virtual X server.
1928
1929           rlVirtualXGetDisplay name
1930
1931       name
1932           String identifying the X server.
1933
1934       Displays the number of display where specified virtual X server is
1935       running to standard output. Returns 0 on success.
1936
1937       rlVirtualXStop
1938
1939       Kill the specified X server.
1940
1941           rlVirtualXStop name
1942
1943       name
1944           String identifying the X server.
1945
1946       Returns 0 when the server is stopped successfully.
1947
1948       Example
1949
1950       Below is a simple example of usage. Note that a lot of usefull
1951       debugging information is reported on the DEBUG level, so you can run
1952       your test with "DEBUG=1 make run" to get them.
1953
1954           rlVirtualXStart $TEST
1955           rlAssert0 "Virtual X server started" $?
1956           export DISPLAY="$( rlVirtualXGetDisplay $TEST )"
1957           # ...your test which needs X...
1958           rlVirtualXStop $TEST
1959           rlAssert0 "Virtual X server killed" $?
1960
1961       These are "Requires" lines for your scripts - note different package
1962       names for different RHEL versions:
1963
1964           @echo "Requires: xorg-x11-server-Xvfb" >> $(METADATA) # RHEL-5
1965           @echo "Requires: xorg-x11-Xvfb"        >> $(METADATA) # RHEL-4
1966           @echo "Requires: XFree86-Xvfb"         >> $(METADATA) # RHEL-3
1967
1968       rlYash_parse
1969
1970       Parse yaml data to the associative array.
1971
1972           rlYash_parse VAR_NAME YAML_DATA
1973
1974       VAR_NAME
1975           Name of the variable to which the yaml structure will be saved.
1976
1977           Note that the variable needs to be predeclared as an associative
1978           array.
1979
1980       YAML_DATA
1981           The actual yaml data.
1982
1983   Beakerlib Profiling
1984       Enable profiling
1985
1986       Set environment variable BEAKERLIB_PROFILING=1
1987
1988           BEAKERLIB_PROFILING=1 make run
1989
1990       A file /dev/shm/beakerlib_profile will be created for later processing.
1991
1992       Process the profile
1993
1994           /usr/share/beakerlib/profiling.sh process > profile.csv
1995

OUTPUT FILES

1997       Location of test results related output files can be configured by
1998       setting BEAKERLIB_DIR variable before running the test. If it is not
1999       set, temporary directory is created.
2000
2001   journal.txt
2002       Journal in human readable form.
2003
2004   journal.xml
2005       Journal in XML format, requires python. This dependency can be avoided
2006       if the test is run with variable BEAKERLIB_JOURNAL set to 0 in which
2007       case journal.xml is not created.
2008
2009       XSLT
2010
2011       XML journal can be transformed through XSLT template. Which template is
2012       used is configurable by setting BEAKERLIB_JOURNAL variable. Value can
2013       be either filename in which case beakerlib will try to use
2014       $INSTALL_DIR/xslt-template/$filename (e.g.:
2015       /usr/share/beakerlib/xstl-templates/xunit.xsl) or it can be path to a
2016       template anywhere on the system.
2017
2018   TestResults
2019       Overall results of the test in a 'sourceable' form. Each line contains
2020       a pair VAR=VALUE. All variable names have 'TESTRESULT_' prefix.
2021
2022       List of variables:
2023
2024       TESTRESULT_STATE - Current state of the test run; possible values:
2025       started, incomplete and complete.
2026                        - 'started' is set after a Journal is opened.
2027                        - 'incomplete' is set after a Phase is closed.
2028                        - 'complete' is set after a Journal is closed.
2029
2030       TESTRESULT_RESULT_STRING - Result of the test in a string, e.g.: PASS,
2031       FAIL, WARN.
2032
2033       TESTRESULT_RESULT_ECODE - Result of the test as an integer, 0 equals to
2034       PASS.
2035
2036       TESTRESULT_PHASES_PASSED - Number of phases that ended with PASS.
2037
2038       TESTRESULT_PHASES_FAILED - Number of phases that ended with non-PASS
2039       result.
2040
2041       TESTRESULT_PHASES_SKIPPED - Number of skipped phases.
2042
2043       TESTRESULT_ASSERTS_FAILED - Number of asserts that ended with non-PASS
2044       result in the whole test.
2045
2046       TESTRESULT_STARTTIME - Time when test started in seconds since epoch.
2047
2048       TESTRESULT_ENDTIME - Time when test ended in seconds since epoch.
2049
2050       TESTRESULT_DURATION - Duration of the test run in seconds.
2051
2052       TESTRESULT_BEAKERLIB_DIR - Directory with test results files.
2053

EXAMPLES

2055   Simple
2056       A minimal BeakerLib test can look like this:
2057
2058           . /usr/share/beakerlib/beakerlib.sh
2059
2060           rlJournalStart
2061               rlPhaseStartTest
2062                   rlAssertRpm "setup"
2063                   rlAssertExists "/etc/passwd"
2064                   rlAssertGrep "root" "/etc/passwd"
2065               rlPhaseEnd
2066           rlJournalEnd
2067
2068   Phases
2069       Here comes a bit more interesting example of a test which sets all the
2070       recommended variables and makes use of the phases:
2071
2072           # Include the BeakerLib environment
2073           . /usr/share/beakerlib/beakerlib.sh
2074
2075           # Set the full test name
2076           TEST="/examples/beakerlib/Sanity/phases"
2077
2078           # Package being tested
2079           PACKAGE="coreutils"
2080
2081           rlJournalStart
2082               # Setup phase: Prepare test directory
2083               rlPhaseStartSetup
2084                   rlAssertRpm $PACKAGE
2085                   rlRun 'TmpDir=$(mktemp -d)' 0 'Creating tmp directory' # no-reboot
2086                   rlRun "pushd $TmpDir"
2087               rlPhaseEnd
2088
2089               # Test phase: Testing touch, ls and rm commands
2090               rlPhaseStartTest
2091                   rlRun "touch foo" 0 "Creating the foo test file"
2092                   rlAssertExists "foo"
2093                   rlRun "ls -l foo" 0 "Listing the foo test file"
2094                   rlRun "rm foo" 0 "Removing the foo test file"
2095                   rlAssertNotExists "foo"
2096                   rlRun "ls -l foo" 2 "Listing foo should now report an error"
2097               rlPhaseEnd
2098
2099               # Cleanup phase: Remove test directory
2100               rlPhaseStartCleanup
2101                   rlRun "popd"
2102                   rlRun "rm -r $TmpDir" 0 "Removing tmp directory"
2103               rlPhaseEnd
2104           rlJournalEnd
2105
2106           # Print the test report
2107           rlJournalPrintText
2108
2109       The ouput of the rlJournalPrintText command would produce an output
2110       similar to the following:
2111
2112           ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2113           ::   TEST PROTOCOL
2114           ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2115
2116               Package       : coreutils
2117               Installed     : coreutils-8.27-19.fc27.x86_64
2118               beakerlib RPM : beakerlib-1.17-6.fc27.noarch
2119               Test started  : 2018-02-08 15:43:03 CET
2120               Test finished : 2018-02-08 15:43:04 CET
2121               Test duration : 1 seconds
2122               Test name     : /examples/beakerlib/Sanity/phases
2123               Distro        : Fedora release 27 (Twenty Seven)
2124               Hostname      : localhost
2125               Architecture  : x86_64
2126               CPUs          : 4 x Intel Core Processor (Skylake)
2127               RAM size      : 1992 MB
2128               HDD size      : 17.55 GB
2129
2130           ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2131           ::   Test description
2132           ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2133
2134           PURPOSE of /examples/beakerlib/Sanity/phases
2135           Description: Testing BeakerLib phases
2136           Author: Petr Splichal <psplicha@redhat.com>
2137
2138           This example shows how the phases work in the BeakerLib on a
2139           trivial smoke test for the "touch", "ls" and "rm" commands from
2140           the coreutils package.
2141
2142
2143
2144           ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2145           ::   Setup
2146           ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2147
2148           :: [ 15:43:03 ] :: [   PASS   ] :: Checking for the presence of coreutils rpm
2149           :: [ 15:43:03 ] :: [   LOG    ] :: Package versions:
2150           :: [ 15:43:03 ] :: [   LOG    ] ::   coreutils-8.27-19.fc27.x86_64
2151           :: [ 15:43:03 ] :: [   PASS   ] :: Creating tmp directory (Expected 0, got 0)
2152           :: [ 15:43:03 ] :: [   PASS   ] :: Command 'pushd /tmp/tmp.MMQf7dj9QV' (Expected 0, got 0)
2153           ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2154           ::   Duration: 1s
2155           ::   Assertions: 3 good, 0 bad
2156           ::   RESULT: PASS
2157
2158
2159           ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2160           ::   Test
2161           ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2162
2163           :: [ 15:43:04 ] :: [   PASS   ] :: Creating the foo test file (Expected 0, got 0)
2164           :: [ 15:43:04 ] :: [   PASS   ] :: File foo should exist
2165           :: [ 15:43:04 ] :: [   PASS   ] :: Listing the foo test file (Expected 0, got 0)
2166           :: [ 15:43:04 ] :: [   PASS   ] :: Removing the foo test file (Expected 0, got 0)
2167           :: [ 15:43:04 ] :: [   PASS   ] :: File foo should not exist
2168           :: [ 15:43:04 ] :: [   PASS   ] :: Listing foo should now report an error (Expected 2, got 2)
2169           ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2170           ::   Duration: 0s
2171           ::   Assertions: 6 good, 0 bad
2172           ::   RESULT: PASS
2173
2174
2175           ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2176           ::   Cleanup
2177           ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2178
2179           :: [ 15:43:04 ] :: [   PASS   ] :: Command 'popd' (Expected 0, got 0)
2180           :: [ 15:43:04 ] :: [   PASS   ] :: Removing tmp directory (Expected 0, got 0)
2181           ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2182           ::   Duration: 0s
2183           ::   Assertions: 2 good, 0 bad
2184           ::   RESULT: PASS
2185
2186
2187           ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2188           ::   /examples/beakerlib/Sanity/phases
2189           ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2190
2191           :: [ 15:43:04 ] :: [   LOG    ] :: JOURNAL XML: /var/tmp/beakerlib-pRiJfWE/journal.xml
2192           :: [ 15:43:04 ] :: [   LOG    ] :: JOURNAL TXT: /var/tmp/beakerlib-pRiJfWE/journal.txt
2193           ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2194           ::   Duration: 1s
2195           ::   Phases: 3 good, 0 bad
2196           ::   OVERALL RESULT: PASS
2197
2198       Note that the detailed test description is read from a separate file
2199       PURPOSE placed in the same directory as the test itself.
2200
2201       A lot of useful debugging information is reported on the DEBUG level.
2202       You can run your test with "DEBUG=1 make run" to get them.
2203
2204       Verbosity of the test logging may be altered also by setting the
2205       LOG_LEVEL variable. Possible values are "ERROR", "WARNING", "INFO" and
2206       "DEBUG". You will see messages like the ones below.
2207
2208           :: [ WARNING  ] :: rlGetArch: Update test to use rlGetPrimaryArch/rlGetSecondaryArch
2209           :: [  DEBUG   ] :: rlGetArch: This is architecture 'x86_64'
2210           :: [  ERROR   ] :: this function was dropped as its development is completely moved to the beaker library
2211           :: [   INFO   ] :: if you realy on this function and you really need to have it present in core beakerlib, file a RFE, please
2212
2213       Setting LOG_LEVEL="DEBUG" is equivalent to DEBUG=1.
2214
2215       Set DEBUG_TO_CONSOLE_ONLY=1 in conjuction with DEBUG=1 to avoid storing
2216       debug messages in journal. This also speeds up the execution in debug
2217       mode as those messages are not fully processed than.
2218

BKRDOC

2220       Description
2221           Bkrdoc is a documentation generator from tests written using
2222           BeakerLib library. This generator makes documentation from test
2223           code with and also without any documentation markup.
2224
2225       What it's good for
2226           For fast, brief and reliable documentation creation. It`s good for
2227           quick start with unknown BeakerLib test. Created documentations
2228           provides information about the documentation credibility. Also
2229           created documentations shows environmental variables and helps
2230           reader to run test script from which was documentation created.
2231
2232       Bkrdoc project page
2233           https://github.com/rh-lab-q/bkrdoc
2234
2236       Project Page
2237           https://github.com/beakerlib/beakerlib
2238
2239       Manual
2240           https://github.com/beakerlib/beakerlib/wiki/man
2241
2242       Issues list
2243           https://bugzilla.redhat.com/buglist.cgi?component=beakerlib&&order=bug_status%2Cassigned_to%2Cpriority
2244
2245           https://github.com/beakerlib/beakerlib/issues
2246
2247       Reporting issues
2248           https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora&component=beakerlib
2249
2250           https://github.com/beakerlib/beakerlib/issues/new
2251

AUTHORS

2253       •   Petr Muller <pmuller@redhat.com>
2254
2255       •   Ondrej Hudlicky <ohudlick@redhat.com>
2256
2257       •   Jan Hutar <jhutar@redhat.com>
2258
2259       •   Petr Splichal <psplicha@redhat.com>
2260
2261       •   Ales Zelinka <azelinka@redhat.com>
2262
2263       •   Dalibor Pospisil <dapospis@redhat.com>
2264
2265       •   Martin Kyral <mkyral@redhat.com>
2266
2267       •   Jakub Prokes <jprokes@redhat.com>
2268
2269       •   Jakub Heger <jheger@redhat.com>
2270
2271
2272
2273perl v5.34.0                      2022-01-19                      BEAKERLIB(1)
Impressum