1TESTING.SH(1)         User Contributed Perl Documentation        TESTING.SH(1)
2
3
4

NAME

6       BeakerLib - testing - asserting functions, watchdog and report
7

DESCRIPTION

9       This file contains functions related directly to testing. These
10       functions are various asserts affecting final result of the phase.
11       Watchdog and the report result function is included as well.
12

FUNCTIONS

14   Manual Asserts
15       rlPass
16
17       Manual assertion, asserts and logs PASS.
18
19           rlPass comment
20
21       comment
22           Short test summary.
23
24       Returns 0 and asserts PASS.
25
26       rlFail
27
28       Manual assertion, asserts and logs FAIL.
29
30           rlFail comment
31
32       comment
33           Short test summary.
34
35       Returns 1 and asserts FAIL.
36
37   Arithmetic Asserts
38       rlAssert0
39
40       Assertion checking for the equality of parameter to zero.
41
42           rlAssert0 comment value
43
44       comment
45           Short test summary, e.g. "Test if compilation ended successfully".
46
47       value
48           Integer value (usually return code of a command).
49
50       Returns 0 and asserts PASS when "value == 0".
51
52       rlAssertEquals
53
54       Assertion checking for the equality of two parameters.
55
56           rlAssertEquals comment value1 value2
57
58       comment
59           Short test summary, e.g. "Test if all 3 packages have been
60           downloaded".
61
62       value1
63           First parameter to compare, can be a number or a string
64
65       value2
66           Second parameter to compare, can be a number or a string
67
68       Returns 0 and asserts PASS when "value1 == value2".
69
70       rlAssertNotEquals
71
72       Assertion checking for the non-equality of two parameters.
73
74           rlAssertNotEquals comment value1 value2
75
76       comment
77           Short test summary, e.g. "Test if return code is not 139".
78
79       value1
80           First parameter to compare, can be a number or a string
81
82       value2
83           Second parameter to compare, can be a number or a string
84
85       Returns 0 and asserts PASS when "value1 != value2".
86
87       rlAssertGreater
88
89       Assertion checking whether first parameter is greater than the second
90       one.
91
92           rlAssertGreater comment value1 value2
93
94       comment
95           Short test summary, e.g. "Test whether there are running more
96           instances of program."
97
98       value1
99           Integer value.
100
101       value2
102           Integer value.
103
104       Returns 0 and asserts PASS when "value1 > value2".
105
106       rlAssertGreaterOrEqual
107
108       Assertion checking whether first parameter is greater or equal to the
109       second one.
110
111           rlAssertGreaterOrEqual comment value1 value2
112
113       comment
114           Short test summary (e.g. "There should present at least one...")
115
116       value1
117           Integer value.
118
119       value2
120           Integer value.
121
122       Returns 0 and asserts PASS when "value1 ≥= value2".
123
124       rlAssertLesser
125
126       Assertion checking whether first parameter is lesser than the second
127       one.
128
129           rlAssertLesser comment value1 value2
130
131       comment
132           Short test summary, e.g. "Test whether there are running more
133           instances of program."
134
135       value1
136           Integer value.
137
138       value2
139           Integer value.
140
141       Returns 0 and asserts PASS when "value1 < value2".
142
143       rlAssertLesserOrEqual
144
145       Assertion checking whether first parameter is lesser or equal to the
146       second one.
147
148           rlAssertLesserOrEqual comment value1 value2
149
150       comment
151           Short test summary (e.g. "There should present at least one...")
152
153       value1
154           Integer value.
155
156       value2
157           Integer value.
158
159       Returns 0 and asserts PASS when "value1 ≤= value2".
160
161   File Asserts
162       rlAssertExists
163
164       Assertion checking for the existence of a file or a directory.
165
166           rlAssertExists file|directory
167
168       file|directory
169           Path to the file or directory.
170
171       Returns 0 and asserts PASS when "file" exists.
172
173       rlAssertNotExists
174
175       Assertion checking for the non-existence of a file or a directory.
176
177           rlAssertNotExists file|directory
178
179       file|directory
180           Path to the file or directory.
181
182       Returns 0 and asserts PASS when "file" does not exist.
183
184       rlAssertGrep
185
186       Assertion checking if the file contains a pattern.
187
188           rlAssertGrep pattern file [options]
189
190       pattern
191           Regular expression to be searched for.
192
193       file
194           Path to the file.
195
196       options
197           Optional parameters to be passed to grep, default is "-q". Can be
198           used to perform case insensitive matches (-i), or using extended
199           (-E) or perl (-P) regular expressions.
200
201       Returns 0 and asserts PASS when "file" exists and contains given
202       "pattern".
203
204       rlAssertNotGrep
205
206       Assertion checking that the file does not contain a pattern.
207
208           rlAssertNotGrep pattern file [options]
209
210       pattern
211           Regular expression to be searched for.
212
213       file
214           Path to the file.
215
216       options
217           Optional parameters to be passed to grep, default is "-q". Can be
218           used to perform case insensitive matches (-i), or using extended
219           (-E) or perl (-P) regular expressions.
220
221       Returns 0 and asserts PASS when "file" exists and does not contain
222       given "pattern".
223
224       rlAssertDiffer
225
226       Assertion checking that two files differ (are not identical).
227
228           rlAssertDiffer file1 file2
229
230       file1
231           Path to first file1
232
233       file2
234           Path to second file
235
236       Returns 0 and asserts PASS when "file1" and "file2" differs.
237
238       rlAssertNotDiffer
239
240       Assertion checking that two files do not differ (are identical).
241
242           rlAssertNotDiffer file1 file2
243
244       file1
245           Path to first file1
246
247       file2
248           Path to second file
249
250       Returns 0 and asserts PASS when "file1" and "file2" do not differ.
251
252   Run, Watch, Report
253       rlRun
254
255       Run command with optional comment and make sure its exit code matches
256       expectations.
257
258           rlRun [-t] [-l] [-c] [-s] command [status[,status...] [comment]]
259
260       -t  If specified, stdout and stderr of the command output will be
261           tagged with strings 'STDOUT: ' and 'STDERR: '.
262
263       -l  If specified, output of the command (tagged, if -t was specified)
264           is logged using rlLog function. This is intended for short outputs,
265           and therefore only last 50 lines are logged this way. Longer
266           outputs should be analysed separately, or uploaded via rlFileSubmit
267           or rlBundleLogs.
268
269       -c  Same as "-l", but only log the command output if it failed.
270
271       -s  Store stdout and stderr to a file (mixed together, as the user
272           would see it on a terminal) and set $rlRun_LOG variable to name of
273           the file. $rlRun_LOG is now actually an array where the first index
274           holds the last reference to the file.  Thus its behavior is not
275           changed if used without an index. The array is consumed by the
276           rlJournalEnd function to remove the leftover files, so no manual
277           files removal is needed anymore.  Note that if you need to use such
278           a file after calling the rlJournalEnd function you need to create
279           your own copy of the respective file.  When -t option is used, the
280           content of the file becomes tagged too.
281
282           If the -s option is not used, $rlRun_LOG is not modified and keeps
283           its content from the last "rlRun -s".
284
285       command
286           Command to run.
287
288       status
289           Expected exit code(s). Optional, default 0. If you expect more exit
290           codes, separate them with comma (e.g. "0,1" when both 0 and 1 are
291           OK and expected), or use from-to notation (i.e. "2-5" for
292           "2,3,4,5"), or combine them (e.g. "2-4,26" for "2,3,4,26").
293
294       comment
295           Short summary describing the action (optional, but recommended -
296           explain what you are doing here).
297
298       Returns the exit code of the command run. Asserts PASS when command\'s
299       exit status is in the list of expected exit codes.
300
301       Note:
302
303       •   The output of rlRun is buffered when using "-t", "-l" or "-s"
304           option (they use unix pipes, which are buffered by nature). If you
305           need an unbuffered output just make sure that "expect" package is
306           installed on your system (its "unbuffer" tool will automatically be
307           used to produce unbuffered output).
308
309       •   Be aware that there are some variables which can collide with your
310           code executed within rlRun. You should avoid using
311           __INTERNAL_rlRun_* variables.
312
313       •   When any of "-t" "-l", "-c", or "-s" option is used, special file
314           descriptors 111 and 112 are used to avoid the issue with incomplete
315           log file, bz1361246. As there might be an indefinite loop, there's
316           a timeout of two minutes implemented as a fix for bz1416796. Also
317           an error message is issued to signal the possibility of running
318           subprocess which keeps the file descriptors open.
319
320           Do not use these options if you expect process forking and
321           continuouse run. Try your own apropriate solution instead.
322
323       Warning: using "unbuffer" tool is now disabled because of bug 547686.
324
325       rlWatchdog
326
327       Run "command". If it does not finish in specified time, then kill it
328       using "signal".  Note that the command is executed in a sub-shell so
329       modified environment (e.g. set variables) is not relfected in the test
330       environment.
331
332           rlWatchdog command timeout [signal] [callback]
333
334       command
335           Command to run.
336
337       timeout
338           Timeout to wait, in seconds.
339
340       signal
341           Signal to use (optional, default KILL).
342
343       callback
344           Callback function to be called before the signal is send (optional,
345           none by default). The callback function will have one argument
346           available -- PGID of the process group.
347
348       Returns 0 if the command ends normally, without need to be killed.
349
350       rlReport
351
352       Report test result to the test harness. The command to be used for
353       reporting is set by the respective plugin. You can also use the
354       $BEAKERLIB_COMMAND_REPORT_RESULT variable to use your custom command.
355
356           rlReport name result [score] [log]
357
358       name
359           Name of the test result.
360
361       result
362           Result (one of PASS, WARN, FAIL). If called with something else,
363           will use WARN.
364
365       score
366           Test score (optional).
367
368       log Optional log file to be submitted instead of default "OUTPUTFILE".
369
370       rlCmpVersion
371
372       Compare two given versions composed by numbers and letters divided by
373       dot (.), underscore (_), or dash (-).
374
375           rlCmpVersion ver1 ver2
376
377       If ver1 = ver2, sign '=' is printed to stdout and 0 is returned.  If
378       ver1 > ver2, sign '>' is printed to stdout and 1 is returned.  If ver1
379       < ver2, sign '<' is printed to stdout and 2 is returned.
380
381       rlTestVersion
382
383       Test releation between two given versions based on given operator.
384
385           rlTestVersion ver1 op ver2
386
387       op  Operator defining the logical expression.  It can be '=', '==',
388           '!=', '<', '<=', '=<', '>', '>=', or '=>'.
389
390       Returns 0 if the expresison ver1 op ver2 is true; 1 if the expression
391       is false and 2 if something went wrong.
392
393   Release Info
394       rlIsRHEL
395
396           rlIsRHEL [VERSION_SPEC]...
397
398       VERSION_SPEC
399           Argument specifies version of particular RHEL distribution, eg. 8,
400           8.4 ">8.4".
401
402           For more details see description of "rlIsOSVersion".
403
404       Returns 0 when we're running on RHEL.  With given version specification
405       in arguments returns 0 if the particular RHEL version is running.
406
407       Prototype:
408
409           rlIsRHEL
410
411         Returns 0 if we are running on RHEL.
412
413           rlIsRHEL 7 '>=8.5'
414
415         Returns 0 if we are running any RHEL 7 or RHEL 8.5 and higher.
416
417       rlIsFedora
418
419           rlIsFedora [VERSION_SPEC]...
420
421       VERSION_SPEC
422           Argument specifies version of particular Fedora distribution, eg.
423           30, ">30".
424
425           For more details see description of "rlIsOSVersion".
426
427       Returns 0 when we're running on Fedora.  With given version
428       specification in arguments returns 0 if the particular Fedora version
429       is running.
430
431       Prototype:
432
433           rlIsFedora
434
435         Returns 0 if we are running on Fedora.
436
437           rlIsFedora 30 32
438
439         Returns 0 if we are running Fedora 30 or 32.
440
441       rlIsCentOS
442
443           rlIsCentOS [VERSION_SPEC]...
444
445       VERSION_SPEC
446           Argument specifies version of particular CentOS distribution, eg.
447           7, ">7".
448
449           For more details see description of "rlIsOSVersion".
450
451       Returns 0 when we're running on CentOS.  With given version
452       specification in arguments returns 0 if the particular CentOS version
453       is running.
454
455       Prototype:
456
457           rlIsCentOS
458
459         Returns 0 if we are running on CentOS.
460
461           rlIsCentOS 7.1 6
462
463         Returns 0 if we are running CentOS 7.1 or any CentOS 6.
464
465       rlIsOS
466
467           rlIsOS ID
468
469       ID  Argument is based on contents of /etc/os-release.  Possible options
470           of ID are e.g. fedora, rhel, centos, ol.
471
472       Returns 0 when we're running on system with respective ID.  Returns 1
473       when parameter does not match with ID in os-release.  Returns 2 when
474       there is no ID defined.  Returns 3 when no argument is given.
475
476       Prototype:
477
478           rlIsOS rhel
479
480         Returns 0 if we are running on RHEL.
481
482       rlIsOSLike
483
484           rlIsOSLike ID_LIKE
485
486       ID_LIKE
487           Argument is based on contents of /etc/os-release.  Possible options
488           of ID_LIKE are e.g. fedora, rhel.
489
490       Returns 0 when we're running on system with requested ID_LIKE.  Returns
491       1 when parameter does not match with ID nor ID_LIKE in os-release.
492       Returns 2 when there is no ID or ID_LIKE defined.  Returns 3 when no
493       argument is given.
494
495       Prototype:
496
497           rlIsOSLike rhel
498
499         Returns 0 if we are running on RHEL, CentOS, Rocky Linux, etc..
500
501           rlIsOSLike fedora
502
503         Returns 0 if we are running on Fedora, RHEL, CentOS, Oracle Linux, etc..
504
505       rlIsOSVersion
506
507           rlIsOsVersion VERSION_SPEC...
508
509       VERSION_SPEC
510           Parameter is based on VERSION_ID in /etc/os-release.  It consists
511           of either "major" or "major"."minor" refering to a particular
512           release.
513
514           It accepts multiple arguments separated by space (8.1 8.2 8.3 9).
515
516           To specify a group of distributions optional operator can be passed
517           in argument together with the version number as one string
518           ('>8.5').  Operator can be '<', '<=', '=<', '=', '>', '>=' matching
519           whether the currently installed version is lesser, lesser or equal,
520           equal, equal or greater, greater than the version number supplied
521           as second half of the argument.
522
523           Note that when using >/< operators you have to either put the
524           argument in quotes or escape the operators to avoid them being
525           interpreted as bash redirection operator.
526
527       Returns 0 when we're running distribution of the particular version
528       requested by the argument.
529
530       It usually follows after "rlIsOS" and "rlIsOSLike".
531
532       Be cautious when using together with "rlIsOSLike" as different
533       distributions may use different versioning schema.
534
535       Prototype:
536
537          rlIsOSVersion 6 7 9
538
539         Returns 0 if we are running distribution with VERSION_ID 6, 7 or 9.
540
541           rlIsOSVersion 7.8 8
542
543         Returns 0 if we are running distribution 7.8 or any 8.
544
545           rlIsOSVersion ">=7.5" or rlIsOSVersion \>=7.5
546
547         Returns 0 if we are running distribution 7.5 or higher (both minors or majors).
548
549       Note:
550
551           rlIsOSVersion '<7.5' || rlIsOSVersion '<8.5'
552
553         would also cover 7.9 as it is less than 8.5, which is not what you want.
554         So if you want to construct a condition for a distribution <7.5 within the major 7 or
555         a distribution <8.5 within the major 8 you actually need to use following construct:
556
557           rlIsOSVersion 7 && rlIsOSVersion '<7.5' || rlIsOSVersion 8 && rlIsOSVersion '<8.5'
558
559         This returns 0 when running distribution less than 7.5 and less then 8.5, but not 7.9 (nor 6.9).
560
561       rlIsRHELLike
562
563           rlIsRHELLike [VERSION_SPEC]...
564
565       VERSION_SPEC
566           Argument specifies version of particular RHEL distribution, eg. 8,
567           8.4 ">8.4".
568
569           For more details see description of "rlIsOSVersion".
570
571       Returns 0 when we're running on RHEL-like distribution.  These are
572       considered to be RHEL, CentOS, Rocky Linux, etc..  With given version
573       specification in arguments returns 0 if the particular version of RHEL-
574       like distribution is running.
575
576       Prototype:
577
578           rlIsRHELLike
579
580         Returns 0 if we are running on RHEL-like system.
581
582           rlIsRHELLike ">=6"
583
584         Returns 0 if we are running on RHEL-like distribution of version 6.0 or higher.
585

AUTHORS

587       •   Ondrej Hudlicky <ohudlick@redhat.com>
588
589       •   Petr Muller <pmuller@redhat.com>
590
591       •   Jan Hutar <jhutar@redhat.com>
592
593       •   Petr Splichal <psplicha@redhat.com>
594
595       •   Ales Zelinka <azelinka@redhat.com>
596
597
598
599perl v5.36.0                      2023-01-18                     TESTING.SH(1)
Impressum