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
15       ·   Journal - uniform logging mechanism (logs & results saved in
16           flexible XML format, easy to compare results & generate reports)
17
18       ·   Phases - logical grouping of test actions, clear separation of
19           setup / test / cleanup (preventing false fails)
20
21       ·   Asserts - common checks affecting the overall results of the
22           individual phases (checking for exit codes, file existence &
23           content...)
24
25       ·   Helpers - 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 options is now deprecated, has no effect and will be removed in
109           one of future versions.
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 in so far, 255 if there are more then
153       255 failures.  The precise number is set to ECODE variable.
154
155           rlGetTestState
156
157       rlGetPhaseState
158
159       Returns number of failed asserts in current phase so far, 255 if there
160       are more then 255 failures.  The precise number is set to ECODE
161       variable.
162
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           not existent 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 a part of the tar-ball name.
223
224       file
225           File(s) to be packed and submitted.
226
227       Returns result of submiting the tarball.
228
229       rlFileSubmit
230
231       Resolves absolute path to the file, replaces / for - and uploads this
232       renamed file using rhts-submit-log.  It also allows you to specify your
233       custom name for the uploaded file.
234
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 X 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 strigs '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 commands 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. Caller is responsible for removing the file. When -t
684           option is used, the content of the file becomes tagged too.
685
686           If the -s option is not used, $rlRun_LOG is not modified and keeps
687           its content from the last "rlRun -s".
688
689       command
690           Command to run.
691
692       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
698       comment
699           Short summary describing the action (optional, but recommended -
700           explain what are you doing here).
701
702       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
705       Note:
706
707       ·   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
713       ·   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
717       ·   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
724           Do not use these options if you expect process forking and
725           continuouse run. Try your own apropriate solution instead.
726
727       Warning: using "unbuffer" tool is now disabled because of bug 547686.
728
729       rlWatchdog
730
731       Run "command". If it does not finish in specified time, then kill it
732       using "signal".
733
734           rlWatchdog command timeout [signal] [callback]
735
736       command
737           Command to run.
738
739       timeout
740           Timeout to wait, in seconds.
741
742       signal
743           Signal to use (optional, default KILL).
744
745       callback
746           Callback function to be called before the signal is send (optional,
747           none by default). The callback function will have one argument
748           available -- PGID of the process group.
749
750       Returns 0 if the command ends normally, without need to be killed.
751
752       rlReport
753
754       Report test result to the test harness. The command to be used for
755       reporting is set by the respective plugin. You can also use the
756       $BEAKERLIB_COMMAND_REPORT_RESULT variable to use your custom command.
757
758           rlReport name result [score] [log]
759
760       name
761           Name of the test result.
762
763       result
764           Result (one of PASS, WARN, FAIL). If called with something else,
765           will use WARN.
766
767       score
768           Test score (optional).
769
770       log Optional log file to be submitted instead of default "OUTPUTFILE".
771
772       rlCmpVersion
773
774       Compare two given versions composed by numbers and letters divided by
775       dot (.), underscore (_), or dash (-).
776
777           rlCmpVersion ver1 ver2
778
779       If ver1 = ver2, sign '=' is printed to stdout and 0 is returned.  If
780       ver1 > ver2, sign '>' is printed to stdout and 1 is returned.  If ver1
781       < ver2, sign '<' is printed to stdout and 2 is returned.
782
783       rlTestVersion
784
785       Test releation between two given versions based on given operator.
786
787           rlTestVersion ver1 op ver2
788
789       op  Operator defining the logical expression.  It can be '=', '==',
790           '!=', '<', '<=', '=<', '>', '>=', or '=>'.
791
792       Returns 0 if the expresison ver1 op ver2 is true; 1 if the expression
793       is false and 2 if something went wrong.
794
795   Release Info
796       rlIsRHEL
797
798           rlIsRHEL [Num|opNum]
799
800       Num When used function returns 0 if the particular RHEL version is
801           running.  Multiple arguments can be passed separated with space as
802           well as any particular release (5.1 5.2 5.3).
803
804       opNum
805           Argument consisting of operator and number written together as one
806           string.  Operator can be '<', '<=', '=<', '=', '>', '>=' matching
807           whether the currently installed version is lesser, lesser or equal,
808           equal, equal or greater, greater than the version number supplied
809           as second half of the argument.  Note that ie. '=5' (unlike just
810           '5') matches exactly 5 (5.0), not 5.N, where N > 0.  Also note when
811           that using >/< operators you have to either put the argument in
812           quotes or escape the operators to avoid them being interpreted as
813           bash redirection operator.
814
815       Returns 0 when we're running on RHEL.
816
817       Note that
818
819           rlIsRHEL '<6.9' || rlIsRHEL '<7.5'
820
821       would also cover 6.10 as it is less than 7.5, which is not what you
822       want.  So if you want to construct a condition for rhel<6.9 for rhel6
823       or rhel<7.5 for rhel7 you actually need to use following construct:
824
825           rlIsRHEL 6 && rlIsRHEL '<6.9' || rlIsRHEL 7 && rlIsRHEL '<7.5'
826
827       Prototype:
828
829           rlIsRHEL
830
831       Returns 0 if we are running on RHEL.
832
833           rlIsRHEL 4.8 5
834
835       Returns 0 if we are running RHEL 4.8 or any RHEL 5.
836
837           rlIsRHEL ">=6" or rlIsRHEL \>=6
838
839       Returns 0 if we are running RHEL 6 or higher.
840
841       rlIsFedora
842
843           rlIsFedora [Num|opNum]
844
845       Returns 0 when we're running on Fedora.  With given number of version
846       as parameter returns 0 if the particular Fedora version is running.
847       Range matching can be used in the form used by rlIsRHEL.
848
849           rlIsFedora
850
851       Returns 0 if we are running on Fedora.
852
853           rlIsFedora 9 10
854
855       Returns 0 if we are running Fedora 9 or 10.
856
857   Release Info
858       rlIsCentOS
859
860           rlIsCentOS [Num|opNum]
861
862       Returns 0 when we're running on CentOS.  With given number of version
863       as parameter returns 0 if the particular CentOS version is running.
864       Range matching can be used in the form used by rlIsRHEL.
865
866           rlIsCentOS
867
868       Returns 0 if we are running on CentOS.
869
870           rlIsCentOS 7.1 6
871
872       Returns 0 if we are running CentOS 7.1 or any CentOS 6.
873
874   Rpm Handling
875       rlCheckRpm
876
877       Check whether a package is installed.
878
879           rlCheckRpm name [version] [release] [arch]
880
881       name
882           Package name like "kernel"
883
884       version
885           Package version like 2.6.25.6
886
887       release
888           Package release like "55.fc9"
889
890       arch
891           Package architucture like "i386"
892
893       Returns 0 if the specified package is installed.
894
895       rlAssertRpm
896
897       Assertion making sure that a package is installed.
898
899           rlAssertRpm name [version] [release] [arch]>
900           rlAssertRpm --all
901
902       name
903           Package name like "kernel"
904
905       version
906           Package version like 2.6.25.6
907
908       release
909           Package release like "55.fc9"
910
911       arch
912           Package architucture like "i386"
913
914       --all
915           Assert all packages listed in the $PACKAGES $REQUIRES and
916           $COLLECTIONS environment variables.
917
918       Returns 0 and asserts PASS if the specified package is installed.
919
920       rlAssertNotRpm
921
922       Assertion making sure that a package is not installed. This is just
923       inverse of "rlAssertRpm".
924
925           rlAssertNotRpm name [version] [release] [arch]>
926
927       name
928           Package name like "kernel"
929
930       version
931           Package version like 2.6.25.6
932
933       release
934           Package release like "55.fc9"
935
936       arch
937           Package architucture like "i386"
938
939       Returns 0 and asserts PASS if the specified package is not installed.
940
941       Example
942
943       Function "rlAssertRpm" is useful especially in prepare phase where it
944       causes abort if a package is missing, while "rlCheckRpm" is handy when
945       doing something like:
946
947           if ! rlCheckRpm package; then
948                yum install package
949                rlAssertRpm package
950           fi
951
952       rlAssertBinaryOrigin
953
954       Assertion making sure that given binary is owned by (one of) the given
955       package(s).
956
957           rlAssertBinaryOrigin binary package [package2 [...]]
958           PACKAGES=... rlAssertBinaryOrigin binary
959
960       binary
961           Binary name like "ksh" or "/bin/ksh"
962
963       package
964           List of packages like "ksh mksh". The parameter is optional. If
965           missing, contents of environment variable $PACKAGES are taken into
966           account.
967
968       Returns 0 and asserts PASS if the specified binary belongs to (one of)
969       the given package(s).  Returns 1 and asserts FAIL if the specified
970       binary does not belong to (any of) the given package(s).  Returns 2 and
971       asserts FAIL if the specified binary is not found.  Returns 3 and
972       asserts FAIL if no packages are given.  Returns 100 and asserts FAIL if
973       invoked with no parameters.
974
975       Example
976
977       Function "rlAssertBinaryOrigin" is useful especially in prepare phase
978       where it causes abort if a binary is missing or is owned by different
979       package:
980
981           PACKAGES=mksh rlAssertBinaryOrigin ksh
982           or
983           rlAssertBinaryOrigin ksh mksh
984
985       Returns true if ksh is owned by the mksh package (in this case:
986       /bin/ksh is a symlink pointing to /bin/mksh).
987
988       rlGetMakefileRequires
989
990       Prints comma separated list of requirements defined in Makefile using
991       'Requires' attribute.
992
993       Return 0 if success.
994
995       rlCheckRequirements
996
997       Check that all given requirements are covered eigther by installed
998       package or by binary available in PATHs or by some package's provides.
999
1000           rlRun "rlCheckRequirements REQ..."
1001
1002       REQ Requirement to be checked. It can be package name, provides string
1003           or binary name.
1004
1005       Returns number of unsatisfied requirements.
1006
1007       rlCheckMakefileRequires
1008
1009       This is just a bit smarted wrapper of
1010
1011       "rlCheckRequirements $(rlGetMakefileRequires)"
1012
1013       Example
1014
1015           rlRun "rlCheckMakefileRequires"
1016
1017       Return 255 if requirements could not be retrieved, 0 if all
1018       requirements are satisfied or number of unsatisfied requirements.
1019
1020       rlAssertRequired
1021
1022       Ensures that all Requires, specified in beakerlib-style beaker-wizard
1023       layout Makefile, are installed.
1024
1025           rlAssertRequired
1026
1027       Prints out a verbose list of installed/missing packages during
1028       operation.
1029
1030       Returns 0 if all required packages are installed, 1 if one or more
1031       packages are missing or if no Makefile is present.
1032
1033   Getting RPMs
1034       Download methods
1035
1036       Functions handling rpm downloading/installing can use more methods for
1037       actual download of the rpm.
1038
1039       Currently there are two download methonds available:
1040
1041       direct
1042           Use use dirct download from build system (brew).
1043
1044       yum Use yumdownloader or dnf download.
1045
1046       The methods and their order are defined by
1047       BEAKERLIB_RPM_DOWNLOAD_METHODS variable as space separated list. By
1048       default it is 'direct yum'. This can be overridden by user.  There may
1049       be done also additions  or changes to the original value, e.g.
1050       BEAKERLIB_RPM_DOWNLOAD_METHODS='yum
1051       ${BEAKERLIB_RPM_DOWNLOAD_METHODS/yum/}'
1052
1053
1054
1055       Beakerlib is prepared for more Koji-based sources of packages while
1056       usigng direct download method. By default packages are fetched from
1057       Koji, particularly from https://kojipkgs.fedoraproject.org/packages.
1058
1059       rlRpmInstall
1060
1061       Try to install specified package from local Red Hat sources.
1062
1063           rlRpmInstall [--quiet] package version release arch
1064
1065       --quiet
1066           Make the download and the install process be quiet.
1067
1068       package
1069           Package name like "kernel"
1070
1071       version
1072           Package version like 2.6.25.6
1073
1074       release
1075           Package release like "55.fc9"
1076
1077       arch
1078           Package arch like "i386"
1079
1080       Returns 0 if specified package was installed succesfully.
1081
1082       rlRpmDownload
1083
1084       Try to download specified package.
1085
1086           rlRpmDownload [--quiet] {package version release arch|N-V-R.A}
1087           rlRpmDownload [--quiet] --source {package version release|N-V-R}
1088
1089       --quiet
1090           Make the download process be quiet.
1091
1092       package
1093           Package name like "kernel"
1094
1095       version
1096           Package version like 2.6.25.6
1097
1098       release
1099           Package release like "55.fc9"
1100
1101       arch
1102           Package arch like "i386"
1103
1104       Returns 0 if specified package was downloaded succesfully.
1105
1106       rlFetchSrcForInstalled
1107
1108       Tries various ways to download source rpm for specified installed rpm.
1109
1110           rlFetchSrcForInstalled [--quiet] package
1111
1112       --quiet
1113           Make the download process be quiet.
1114
1115       package
1116           Installed package name like "kernel". It accepts in-direct names.
1117           Eg for the package name "krb5-libs" will the function download the
1118           "krb5" source rpm.
1119
1120       Returns 0 if the source package was succesfully downloaded.
1121
1122   Mounting
1123       rlMount
1124
1125       Create mount point (if neccessary) and mount a NFS share.
1126
1127           rlMount [-o MOUNT_OPTS] server share mountpoint
1128
1129       server
1130           NFS server hostname.
1131
1132       share
1133           Shared directory name.
1134
1135       mountpoint
1136           Local mount point.
1137
1138       MOUNT_OPTS
1139           Mount options.
1140
1141       Returns 0 if mounting the share was successful.
1142
1143       rlCheckMount
1144
1145       Check either if a directory is a mountpoint, if it is a mountpoint to a
1146       specific server, or if it is a mountpoint to a specific export on a
1147       specific server and if it uses specific mount options.
1148
1149           rlCheckMount [-o MOUNT_OPTS] mountpoint
1150           rlCheckMount [-o MOUNT_OPTS] server mountpoint
1151           rlCheckMount [-o MOUNT_OPTS] server share mountpoint
1152
1153       mountpoint
1154           Local mount point.
1155
1156       server
1157           NFS server hostname
1158
1159       share
1160           Shared directory name
1161
1162       MOUNT_OPTS
1163           Mount options to check (comma separated list)
1164
1165       With one parameter, returns 0 when specified directory exists and is a
1166       mountpoint. With two parameters, returns 0 when specific directory
1167       exists, is a mountpoint and an export from specific server is mounted
1168       there. With three parameters, returns 0 if a specific shared directory
1169       is mounted on a given server on a given mountpoint
1170
1171       If the -o option is provided, returns 0 if the mountpoint uses all the
1172       given options, 2 otherwise.
1173
1174       rlAssertMount
1175
1176       Assertion making sure that given directory is a mount point, if it is a
1177       mountpoint to a specific server, or if it is a mountpoint to a specific
1178       export on a specific server and if it uses specific mount options.
1179
1180           rlAssertMount [-o MOUNT_OPTS]  mountpoint
1181           rlAssertMount [-o MOUNT_OPTS]  server mountpoint
1182           rlAssertMount [-o MOUNT_OPTS]  server share mountpoint
1183
1184       mountpoint
1185           Local mount point.
1186
1187       server
1188           NFS server hostname
1189
1190       share
1191           Shared directory name
1192
1193       MOUNT_OPTS
1194           Mount options to check (comma separated list)
1195
1196       With one parameter, returns 0 when specified directory exists and is a
1197       mountpoint. With two parameters, returns 0 when specific directory
1198       exists, is a mountpoint and an export from specific server is mounted
1199       there. With three parameters, returns 0 if a specific shared directory
1200       is mounted on a given server on a given mountpoint. Asserts PASS when
1201       the condition is true.
1202
1203       If the -o option is provided, asserts PASS if the above conditions are
1204       met and the mountpoint uses all the given options.
1205
1206       rlHash, rlUnhash
1207
1208       Hashes/Unhashes given string and prints the result to stdout.
1209
1210           rlHash [--decode] [--algorithm HASH_ALG] --stdin|STRING
1211           rlUnhash [--algorithm HASH_ALG] --stdin|STRING
1212
1213       --decode
1214           Unhash given string.
1215
1216       --algorithm
1217           Use given hash algorithm.  Currently supported algorithms:
1218             base64
1219             base64_ - this is standard base64 where '=' is replaced by '_'
1220             hex
1221
1222           Defaults to hex.  Default algorithm can be override using global
1223           variable rlHashAlgorithm.
1224
1225       --stdin
1226           Get the string from stdin.
1227
1228       STRING
1229           String to be hashed/unhashed.
1230
1231       Returns 0 if success.
1232
1233   Backup and Restore
1234       rlFileBackup
1235
1236       Create a backup of files or directories (recursive). Can be used
1237       multiple times to add more files to backup. Backing up an already
1238       backed up file overwrites the original backup.
1239
1240           rlFileBackup [--clean] [--namespace name] [--missing-ok|--no-missing-ok] file [file...]
1241
1242       You can use "rlRun" for asserting the result but keep in mind meaning
1243       of exit codes, especialy exit code 8, if using without --clean option.
1244
1245       --clean
1246           If this option is provided (have to be first option of the
1247           command), then file/dir backuped using this command (provided in
1248           next options) will be (recursively) removed before we will restore
1249           it.  This option implies --missing-ok, this can be overridden by
1250           --no-missing-ok.
1251
1252       --namespace name
1253           Specifies the namespace to use.  Namespaces can be used to separate
1254           backups and their restoration.
1255
1256       --missing-ok
1257           Do not raise an error in case of missing file to backup.
1258
1259       --no-missing-ok
1260           Do raise an error in case of missing file to backup.  This is
1261           useful with --clean. This behaviour can be globally set by global
1262           variable BEAKERLIB_FILEBACKUP_MISSING_OK=false.
1263
1264       file
1265           Files and/or directories to be backed up.
1266
1267       Returns 0 if the backup was successful.  Returns 1 if parsing of
1268       parameters was not successful.  Returns 2 if no files specification was
1269       provided.  Returns 3 if BEAKERLIB_DIR variable is not set, e.g.
1270       rlJournalStart was not executed.  Returns 4 if creating of main backup
1271       destination directories was not successful.  Returns 5 if creating of
1272       file specific backup destination directories was not successful.
1273       Returns 6 if the copy of backed up files was not successful.  Returns 7
1274       if attributes of backedup files were not successfuly copied.  Returns 8
1275       if backed up files do not exist. This can be suppressed based on other
1276       options.
1277
1278       Example with --clean:
1279
1280           touch cleandir/aaa
1281           rlRun "rlFileBackup --clean cleandir/"
1282           touch cleandir/bbb
1283           ls cleandir/
1284           aaa   bbb
1285           rlRun "rlFileRestore"
1286           ls cleandir/
1287           aaa
1288
1289       rlFileRestore
1290
1291       Restore backed up files to their original location.  "rlFileRestore"
1292       does not remove new files appearing after backup has been made.  If you
1293       don't want to leave anything behind just remove the whole original tree
1294       before running "rlFileRestore", or see "--clean" option of
1295       "rlFileBackup".
1296
1297           rlFileRestore [--namespace name]
1298
1299       You can use "rlRun" for asserting the result.
1300
1301       --namespace name
1302           Specifies the namespace to use.  Namespaces can be used to separate
1303           backups and their restoration.
1304
1305       Returns 0 if backup dir is found and files are restored successfully.
1306
1307       Return code bits meaning XXXXX
1308                                |||||
1309                                ||||\_ error parsing parameters
1310                                |||\__ could not find backup directory
1311                                ||\___ files cleanup failed
1312                                |\____ files restore failed
1313                                \_____ no files were restored nor cleaned
1314
1315   Services
1316       Following routines implement comfortable way how to start/stop system
1317       services with the possibility to restore them to their original state
1318       after testing.
1319
1320       rlServiceStart
1321
1322       Make sure the given "service" is running with fresh configuration.
1323       (Start it if it is stopped and restart if it is already running.) In
1324       addition, when called for the first time, the current state is saved so
1325       that the "service" can be restored to its original state when testing
1326       is finished, see "rlServiceRestore".
1327
1328           rlServiceStart service [service...]
1329
1330       service
1331           Name of the service(s) to start.
1332
1333       Returns number of services which failed to start/restart; thus zero is
1334       returned when everything is OK.
1335
1336       rlServiceStop
1337
1338       Make sure the given "service" is stopped. Stop it if it is running and
1339       do nothing when it is already stopped. In addition, when called for the
1340       first time, the current state is saved so that the "service" can be
1341       restored to its original state when testing is finished, see
1342       "rlServiceRestore".
1343
1344           rlServiceStop service [service...]
1345
1346       service
1347           Name of the service(s) to stop.
1348
1349       Returns number of services which failed to become stopped; thus zero is
1350       returned when everything is OK.
1351
1352       rlServiceRestore
1353
1354       Restore given "service" into its original state (before the first
1355       "rlServiceStart" or "rlServiceStop" was called). If "rlServiceStart"
1356       was called on already running "service", "rlServiceRestore" will
1357       restart the "service" when restoring its state.
1358
1359           rlServiceRestore [service...]
1360
1361       service
1362           Name of the service(s) to restore to original state.  All services
1363           will be restored in reverse order if no service name is given.
1364
1365       Returns number of services which failed to get back to their original
1366       state; thus zero is returned when everything is OK.
1367
1368       rlServiceEnable
1369
1370       Enables selected services if needed, or does nothing if already
1371       enabled.  In addition, when called for the first time, the current
1372       state is saved so that the "service" can be restored to its original
1373       state when testing is finished, see "rlServiceRestore".
1374
1375           rlServiceEnable service [service...]
1376
1377       service
1378           Name of the service(s) to enable.
1379
1380       Returns number of services which failed enablement; thus zero is
1381       returned when everything is OK.
1382
1383       rlServiceDisable
1384
1385       Disables selected services if needed, or does nothing if already
1386       disabled.  In addition, when called for the first time, the current
1387       state is saved so that the "service" can be restored to its original
1388       state when testing is finished, see "rlServiceRestore".
1389
1390           rlServiceDisable service [service...]
1391
1392       service
1393           Name of the service(s) to disable.
1394
1395       Returns number of services which failed disablement; thus zero is
1396       returned when everything is OK.
1397
1398   Sockets
1399       Following routines implement comfortable way how to start/stop system
1400       sockets with the possibility to restore them to their original state
1401       after testing.
1402
1403       rlSocketStart
1404
1405       Make sure the given "socket" is running. (Start it if stopped, leave it
1406       if already running.) In addition, when called for the first time, the
1407       current state is saved so that the "socket" can be restored to its
1408       original state when testing is finished, see "rlSocketRestore".
1409
1410           rlSocketStart socket [socket...]
1411
1412       socket
1413           Name of the socket(s) to start.
1414
1415       Returns number of sockets which failed to start/restart; thus zero is
1416       returned when everything is OK.
1417
1418       rlSocketStop
1419
1420       Make sure the given "socket" is stopped. Stop it if it is running and
1421       do nothing when it is already stopped. In addition, when called for the
1422       first time, the current state is saved so that the "socket" can be
1423       restored to its original state when testing is finished, see
1424       "rlSocketRestore".
1425
1426           rlSocketStop socket [socket...]
1427
1428       socket
1429           Name of the socket(s) to stop.
1430
1431       Returns number of sockets which failed to become stopped; thus zero is
1432       returned when everything is OK.
1433
1434       rlSocketRestore
1435
1436       Restore given "socket" into its original state (before the first
1437       "rlSocketStart" or "rlSocketStop" was called).
1438
1439       Warning !!!  Xinetd process [even though it might have been used] is
1440       NOT restored. It is recommended to call rlServiceRestore xinetd as
1441       well.
1442
1443           rlSocketRestore socket [socket...]
1444
1445       socket
1446           Name of the socket(s) to restore to original state.
1447
1448       Returns number of sockets which failed to get back to their original
1449       state; thus zero is returned when everything is OK.
1450
1451   Cleanup management
1452       Cleanup management works with a so-called cleanup buffer, which is a
1453       temporary representation of what should be run at cleanup time, and a
1454       final cleanup script (executable), which is generated from this buffer
1455       and wraps it using BeakerLib essentials (journal initialization,
1456       cleanup phase, ...).  The cleanup script must always be updated on an
1457       atomic basis (filesystem-wise) to allow an asynchronous execution by a
1458       third party (ie. test watcher).
1459
1460       The test watcher usage is mandatory for the cleanup management system
1461       to work properly as it is the test watcher that executes the actual
1462       cleanup script.  Limited, catastrophe-avoiding mechanism is in place
1463       even when the test is not run in test watcher, but that should be seen
1464       as a backup and such situation is to be avoided whenever possible.
1465
1466       The cleanup script shares all environment (variables, exported or not,
1467       and functions) with the test itself - the cleanup append/prepend
1468       functions "sample" or "snapshot" the environment at the time of their
1469       call, IOW any changes to the test environment are synchronized to the
1470       cleanup script only upon calling append/prepend.  When the
1471       append/prepend functions are called within a function which has local
1472       variables, these will appear as global in the cleanup.
1473
1474       While the cleanup script receives $PWD from the test, its working dir
1475       is set to the initial test execution dir even if $PWD contains
1476       something else. It is impossible to use relative paths inside cleanup
1477       reliably - certain parts of the cleanup might have been added under
1478       different current directories (CWDs).  Therefore always use absolute
1479       paths in append/prepend cleanup or make sure you never 'cd' elsewhere
1480       (ie. to a TmpDir).
1481
1482       rlCleanupAppend
1483
1484       Appends a string to the cleanup buffer and recreates the cleanup
1485       script.
1486
1487           rlCleanupAppend string
1488
1489       Returns 0 if the operation was successful, 1 otherwise.
1490
1491       rlCleanupPrepend
1492
1493       Prepends a string to the cleanup buffer and recreates the cleanup
1494       script.
1495
1496           rlCleanupPrepend string
1497
1498       Returns 0 if the operation was successful, 1 otherwise.
1499
1500   Time Performance
1501       rlPerfTime_RunsInTime
1502
1503       Measures, how many runs of some commands can be done in specified time.
1504       This approach is suitable for short-time running tasks (up to few
1505       seconds), where averaging few runs is not precise. This is done several
1506       times, and the final result is the average of all runs. It prints the
1507       number on stdout, so it has to be captured.
1508
1509           rlPerfTime_RunsInTime command [time] [runs]
1510
1511       command
1512           Command to run.
1513
1514       time
1515           Time in seconds (optional, default=30).
1516
1517       runs
1518           Number of averaged runs (optional, default=3).
1519
1520       rlPerfTime_AvgFromRuns
1521
1522       Measures the average time of running some task. This approach is
1523       suitable for long-time running tasks (tens of seconds and more), where
1524       it is precise enough. Measured runs can be preceded by dry run, which
1525       is not measured and it's purpose is to warm up various caches.  It
1526       prints the number on stdout, so it has to be captured.  Or, result is
1527       then stored in special rl_retval variable.
1528
1529           rlPerfTime_AvgFromRuns command [count] [warmup]
1530
1531       command
1532           Command to run.
1533
1534       count
1535           Times to run (optional, default=3).
1536
1537       warmup
1538           Warm-up run, run if this option is not "warmup" (optional,
1539           default="warmup")
1540
1541   Analyze
1542       rlDejaSum
1543
1544       TODO description
1545
1546           rlDejaSum par1 par2
1547
1548       par1
1549           TODO description
1550
1551       par2
1552           TODO description
1553
1554       Return 0 if... TODO
1555
1556       rlImport
1557
1558       Imports code provided by one or more libraries into the test namespace.
1559       The library search mechanism is based on Beaker test hierarchy system,
1560       i.e.:
1561
1562       /component/type/test-name/test-file
1563
1564       When test-file calls rlImport with 'foo/bar' parameter, the directory
1565       path is traversed upwards, and a check for presence of the test
1566       /foo/Library/bar/ will be performed. This means this function needs to
1567       be called from the test hierarchy, not e.g. the /tmp directory.
1568
1569       Once library is found, it is sourced and a verifier function is called.
1570       The verifier function is cunstructed by composing the library prefix
1571       and LibraryLoaded. Library prefix can be defined in the library itself.
1572       If the verifier passes the library is ready to use. Also variable
1573       <PREFIX>LibraryDir is created and it points to the library folder.
1574
1575       Usage:
1576
1577           rlImport --all
1578           rlImport LIBRARY [LIBRARY2...]
1579
1580       --all
1581           Read Makefile in current/original directory, pick library
1582           requirements up and import them all.
1583
1584       LIBRARY
1585           Must have 'component/library' format. Identifies the library to
1586           import.
1587
1588       Returns 0 if the import of all libraries was successful. Returns non-
1589       zero if one or more library failed to import.
1590
1591   Process Synchronisation
1592       rlWaitForCmd
1593
1594       Pauses script execution until command exit status is the expeced value.
1595       Logs a WARNING and returns 1 if the command didn't exit successfully
1596       before timeout elapsed or a maximum number of invocations has been
1597       reached.
1598
1599           rlWaitForCmd command [-p PID] [-t time] [-m count] [-d delay] [-r retval]
1600
1601       command
1602           Command that will be executed until its return code is equal 0 or
1603           value speciefied as option to `-r'.
1604
1605       -t time
1606           Timeout in seconds, default=120. If the command doesn't return 0
1607           before time elapses, the command will be killed.
1608
1609       -p PID
1610           PID of the process to check before running command. If the process
1611           exits before the socket is opened, the command will log a WARNING.
1612
1613       -m count
1614           Maximum number of `command' executions before continuing anyway.
1615           Default is infite. Returns 1 if the maximum was reached.
1616
1617       -d delay
1618           Delay between `command' invocations. Default 1.
1619
1620       -r retval
1621           Expected return value of command. Default 0.
1622
1623       rlWaitForFile
1624
1625       Pauses script execution until specified file or directory starts
1626       existing.  Returns 0 if file started existing, 1 if timeout was reached
1627       or PID exited.  Return code is greater than 1 in case of error.
1628
1629           rlWaitForFile path [-p PID] [-t time] [-d delay]
1630
1631       path
1632           Path to file that should start existing.
1633
1634       -t time
1635           Timeout in seconds (optional, default=120). If the file isn't
1636           opened before the time elapses the command returns 1.
1637
1638       -p PID
1639           PID of the process that should also be running. If the process
1640           exits before the file is created, the command returns with status
1641           code of 1.
1642
1643       -d delay
1644           Delay between subsequent checks for existence of file. Default 1.
1645
1646       rlWaitForSocket
1647
1648       Pauses script execution until local socket starts listening.  Returns 0
1649       if socket started listening, 1 if timeout was reached or PID exited.
1650       Return code is greater than 1 in case of error.
1651
1652           rlWaitForSocket {port|path} [-p PID] [-t time] [-d delay] [--close] [--remote]
1653
1654       port|path
1655           Network port to wait for opening or a path to UNIX socket.  Regular
1656           expressions are also supported.
1657
1658       -t time
1659           Timeout in seconds (optional, default=120). If the socket isn't
1660           opened before the time elapses the command returns 1.
1661
1662       -p PID
1663           PID of the process that should also be running. If the process
1664           exits before the socket is opened, the command returns with status
1665           code of 1.
1666
1667       -d delay
1668           Delay between subsequent checks for availability of socket. Default
1669           1.
1670
1671       --close
1672           Wait for the socket to stop listening.
1673
1674       --remote
1675           Wait for the remote socket to start listening instead of local one.
1676
1677       rlWait
1678
1679       Wrapper around bash builtin `wait' command. See bash_builtins(1) man
1680       page.  Kills the process and all its children if the timeout elapses.
1681
1682           rlWaitFor [n ...] [-s SIGNAL] [-t time]
1683
1684       n   List of PIDs to wait for. They need to be background tasks of
1685           current shell.  See bash_builtins(1) section for `wait' command/
1686
1687       -t time
1688           Timeout in seconds (optional, default=30). If the wait isn't
1689           successful before the time elapses then all specified tasks are
1690           killed.
1691
1692       -s SIGNAL
1693           Signal used to kill the process, optional SIGTERM by default.
1694
1695   Virtual X Server
1696       Functions providing simple way how to start and stop virtual X server.
1697
1698       rlVirtualXStart
1699
1700       Start a virtual X server on a first free display. Tries only first N
1701       displays, so you can run out of them.
1702
1703           rlVirtualXStart name
1704
1705       name
1706           String identifying the X server.
1707
1708       Returns 0 when the server is started successfully.
1709
1710       rlVirtualXGetDisplay
1711
1712       Get the DISPLAY variable for specified virtual X server.
1713
1714           rlVirtualXGetDisplay name
1715
1716       name
1717           String identifying the X server.
1718
1719       Displays the number of display where specified virtual X server is
1720       running to standard output. Returns 0 on success.
1721
1722       rlVirtualXStop
1723
1724       Kill the specified X server.
1725
1726           rlVirtualXStop name
1727
1728       name
1729           String identifying the X server.
1730
1731       Returns 0 when the server is stopped successfully.
1732
1733       Example
1734
1735       Below is a simple example of usage. Note that a lot of usefull
1736       debugging information is reported on the DEBUG level, so you can run
1737       your test with "DEBUG=1 make run" to get them.
1738
1739           rlVirtualXStart $TEST
1740           rlAssert0 "Virtual X server started" $?
1741           export DISPLAY="$( rlVirtualXGetDisplay $TEST )"
1742           # ...your test which needs X...
1743           rlVirtualXStop $TEST
1744           rlAssert0 "Virtual X server killed" $?
1745
1746       These are "Requires" lines for your scripts - note different package
1747       names for different RHEL versions:
1748
1749           @echo "Requires: xorg-x11-server-Xvfb" >> $(METADATA) # RHEL-5
1750           @echo "Requires: xorg-x11-Xvfb"        >> $(METADATA) # RHEL-4
1751           @echo "Requires: XFree86-Xvfb"         >> $(METADATA) # RHEL-3
1752

OUTPUT FILES

1754       Location of test results related output files can be configured by
1755       setting BEAKERLIB_DIR variable before running the test. If it is not
1756       set, temporary directory is created.
1757
1758   journal.txt
1759       Journal in human readable form.
1760
1761   journal.xml
1762       Journal in XML format, requires python. This dependency can be avoided
1763       if the test is run with variable BEAKERLIB_JOURNAL set to 0 in which
1764       case journal.xml is not created.
1765
1766       XSLT
1767
1768       XML journal can be transformed through XSLT template. Which template is
1769       used is configurable by setting BEAKERLIB_JOURNAL variable. Value can
1770       be either filename in which case beakerlib will try to use
1771       $INSTALL_DIR/xslt-template/$filename (e.g.:
1772       /usr/share/beakerlib/xstl-templates/xunit.xsl) or it can be path to a
1773       template anywhere on the system.
1774
1775   TestResults
1776       Overall results of the test in a 'sourceable' form. Each line contains
1777       a pair VAR=VALUE. All variable names have 'TESTRESULT_' prefix.
1778
1779       List of variables:
1780
1781       TESTRESULT_RESULT_STRING - Result of the test in a string, e.g.: PASS,
1782       FAIL, WARN.
1783
1784       TESTRESULT_RESULT_ECODE - Result of the test as an integer, 0 equals to
1785       PASS.
1786
1787       TESTRESULT_PHASES_PASSED - Number of phases that ended with PASS.
1788
1789       TESTRESULT_PHASES_FAILED - Number of phases that ended with non-PASS
1790       result.
1791
1792       TESTRESULT_PHASES_SKIPPED - Number of skipped phases.
1793
1794       TESTRESULT_ASSERTS_FAILED - Number of asserts that ended with non-PASS
1795       result in the whole test.
1796
1797       TESTRESULT_STARTTIME - Time when test started in seconds since epoch.
1798
1799       TESTRESULT_ENDTIME - Time when test ended in seconds since epoch.
1800
1801       TESTRESULT_DURATION - Duration of the test run in seconds.
1802
1803       TESTRESULT_BEAKERLIB_DIR - Directory with test results files.
1804

EXAMPLES

1806   Simple
1807       A minimal BeakerLib test can look like this:
1808
1809           . /usr/share/beakerlib/beakerlib.sh
1810
1811           rlJournalStart
1812               rlPhaseStartTest
1813                   rlAssertRpm "setup"
1814                   rlAssertExists "/etc/passwd"
1815                   rlAssertGrep "root" "/etc/passwd"
1816               rlPhaseEnd
1817           rlJournalEnd
1818
1819   Phases
1820       Here comes a bit more interesting example of a test which sets all the
1821       recommended variables and makes use of the phases:
1822
1823           # Include the BeakerLib environment
1824           . /usr/share/beakerlib/beakerlib.sh
1825
1826           # Set the full test name
1827           TEST="/examples/beakerlib/Sanity/phases"
1828
1829           # Package being tested
1830           PACKAGE="coreutils"
1831
1832           rlJournalStart
1833               # Setup phase: Prepare test directory
1834               rlPhaseStartSetup
1835                   rlAssertRpm $PACKAGE
1836                   rlRun 'TmpDir=$(mktemp -d)' 0 'Creating tmp directory' # no-reboot
1837                   rlRun "pushd $TmpDir"
1838               rlPhaseEnd
1839
1840               # Test phase: Testing touch, ls and rm commands
1841               rlPhaseStartTest
1842                   rlRun "touch foo" 0 "Creating the foo test file"
1843                   rlAssertExists "foo"
1844                   rlRun "ls -l foo" 0 "Listing the foo test file"
1845                   rlRun "rm foo" 0 "Removing the foo test file"
1846                   rlAssertNotExists "foo"
1847                   rlRun "ls -l foo" 2 "Listing foo should now report an error"
1848               rlPhaseEnd
1849
1850               # Cleanup phase: Remove test directory
1851               rlPhaseStartCleanup
1852                   rlRun "popd"
1853                   rlRun "rm -r $TmpDir" 0 "Removing tmp directory"
1854               rlPhaseEnd
1855           rlJournalEnd
1856
1857           # Print the test report
1858           rlJournalPrintText
1859
1860       The ouput of the rlJournalPrintText command would produce an output
1861       similar to the following:
1862
1863           ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
1864           ::   TEST PROTOCOL
1865           ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
1866
1867               Package       : coreutils
1868               Installed     : coreutils-8.27-19.fc27.x86_64
1869               beakerlib RPM : beakerlib-1.17-6.fc27.noarch
1870               Test started  : 2018-02-08 15:43:03 CET
1871               Test finished : 2018-02-08 15:43:04 CET
1872               Test duration : 1 seconds
1873               Test name     : /examples/beakerlib/Sanity/phases
1874               Distro        : Fedora release 27 (Twenty Seven)
1875               Hostname      : localhost
1876               Architecture  : x86_64
1877               CPUs          : 4 x Intel Core Processor (Skylake)
1878               RAM size      : 1992 MB
1879               HDD size      : 17.55 GB
1880
1881           ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
1882           ::   Test description
1883           ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
1884
1885           PURPOSE of /examples/beakerlib/Sanity/phases
1886           Description: Testing BeakerLib phases
1887           Author: Petr Splichal <psplicha@redhat.com>
1888
1889           This example shows how the phases work in the BeakerLib on a
1890           trivial smoke test for the "touch", "ls" and "rm" commands from
1891           the coreutils package.
1892
1893
1894
1895           ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
1896           ::   Setup
1897           ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
1898
1899           :: [ 15:43:03 ] :: [   PASS   ] :: Checking for the presence of coreutils rpm
1900           :: [ 15:43:03 ] :: [   LOG    ] :: Package versions:
1901           :: [ 15:43:03 ] :: [   LOG    ] ::   coreutils-8.27-19.fc27.x86_64
1902           :: [ 15:43:03 ] :: [   PASS   ] :: Creating tmp directory (Expected 0, got 0)
1903           :: [ 15:43:03 ] :: [   PASS   ] :: Command 'pushd /tmp/tmp.MMQf7dj9QV' (Expected 0, got 0)
1904           ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
1905           ::   Duration: 1s
1906           ::   Assertions: 3 good, 0 bad
1907           ::   RESULT: PASS
1908
1909
1910           ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
1911           ::   Test
1912           ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
1913
1914           :: [ 15:43:04 ] :: [   PASS   ] :: Creating the foo test file (Expected 0, got 0)
1915           :: [ 15:43:04 ] :: [   PASS   ] :: File foo should exist
1916           :: [ 15:43:04 ] :: [   PASS   ] :: Listing the foo test file (Expected 0, got 0)
1917           :: [ 15:43:04 ] :: [   PASS   ] :: Removing the foo test file (Expected 0, got 0)
1918           :: [ 15:43:04 ] :: [   PASS   ] :: File foo should not exist
1919           :: [ 15:43:04 ] :: [   PASS   ] :: Listing foo should now report an error (Expected 2, got 2)
1920           ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
1921           ::   Duration: 0s
1922           ::   Assertions: 6 good, 0 bad
1923           ::   RESULT: PASS
1924
1925
1926           ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
1927           ::   Cleanup
1928           ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
1929
1930           :: [ 15:43:04 ] :: [   PASS   ] :: Command 'popd' (Expected 0, got 0)
1931           :: [ 15:43:04 ] :: [   PASS   ] :: Removing tmp directory (Expected 0, got 0)
1932           ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
1933           ::   Duration: 0s
1934           ::   Assertions: 2 good, 0 bad
1935           ::   RESULT: PASS
1936
1937
1938           ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
1939           ::   /examples/beakerlib/Sanity/phases
1940           ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
1941
1942           :: [ 15:43:04 ] :: [   LOG    ] :: JOURNAL XML: /var/tmp/beakerlib-pRiJfWE/journal.xml
1943           :: [ 15:43:04 ] :: [   LOG    ] :: JOURNAL TXT: /var/tmp/beakerlib-pRiJfWE/journal.txt
1944           ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
1945           ::   Duration: 1s
1946           ::   Phases: 3 good, 0 bad
1947           ::   OVERALL RESULT: PASS
1948
1949       Note that the detailed test description is read from a separate file
1950       PURPOSE placed in the same directory as the test itself.
1951
1952       A lot of useful debugging information is reported on the DEBUG level.
1953       You can run your test with "DEBUG=1 make run" to get them.
1954
1955       Verbosity of the test logging may be altered also by setting the
1956       LOG_LEVEL variable. Possible values are "ERROR", "WARNING", "INFO" and
1957       "DEBUG". You will see messages like the ones below.
1958
1959           :: [ WARNING  ] :: rlGetArch: Update test to use rlGetPrimaryArch/rlGetSecondaryArch
1960           :: [  DEBUG   ] :: rlGetArch: This is architecture 'x86_64'
1961           :: [  ERROR   ] :: this function was dropped as its development is completely moved to the beaker library
1962           :: [   INFO   ] :: if you realy on this function and you really need to have it present in core beakerlib, file a RFE, please
1963
1964       Setting LOG_LEVEL="DEBUG" is equivalent to DEBUG=1.
1965
1966       Set DEBUG_TO_CONSOLE_ONLY=1 in conjuction with DEBUG=1 to avoid storing
1967       debug messages in journal. This also speeds up the execution in debug
1968       mode as those messages are not fully processed than.
1969

BKRDOC

1971       Description
1972           Bkrdoc is a documentation generator from tests written using
1973           BeakerLib library. This generator makes documentation from test
1974           code with and also without any documentation markup.
1975
1976       What it's good for
1977           For fast, brief and reliable documentation creation. It`s good for
1978           quick start with unknown BeakerLib test. Created documentations
1979           provides information about the documentation credibility. Also
1980           created documentations shows environmental variables and helps
1981           reader to run test script from which was documentation created.
1982
1983       Bkrdoc project page
1984           https://github.com/rh-lab-q/bkrdoc
1985
1987       Project Page
1988           https://github.com/beakerlib/beakerlib
1989
1990       Manual
1991           https://github.com/beakerlib/beakerlib/wiki/man
1992
1993       Issues list
1994           https://bugzilla.redhat.com/buglist.cgi?component=beakerlib&&order=bug_status%2Cassigned_to%2Cpriority
1995
1996           https://github.com/beakerlib/beakerlib/issues
1997
1998       Reporting issues
1999           https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora&component=beakerlib
2000
2001           https://github.com/beakerlib/beakerlib/issues/new
2002

AUTHORS

2004       ·   Petr Muller <pmuller@redhat.com>
2005
2006       ·   Ondrej Hudlicky <ohudlick@redhat.com>
2007
2008       ·   Jan Hutar <jhutar@redhat.com>
2009
2010       ·   Petr Splichal <psplicha@redhat.com>
2011
2012       ·   Ales Zelinka <azelinka@redhat.com>
2013
2014       ·   Dalibor Pospisil <dapospis@redhat.com>
2015
2016       ·   Martin Kyral <mkyral@redhat.com>
2017
2018       ·   Jakub Prokes <jprokes@redhat.com>
2019
2020       ·   Jakub Heger <jheger@redhat.com>
2021
2022
2023
2024perl v5.30.0                      2019-07-24                      BEAKERLIB(1)
Impressum