·

beakerlib (1) Linux Manual Page

ByLinux Manual Posted on

BeakerLib – a shell-level integration testing library

Description

BeakerLib is a shell-level integration testing library, providing convenience functions which simplify writing, running and analysis of integration and blackbox tests.

The essential features include:

•
Journal – uniform logging mechanism (logs & results saved in flexible XML format, easy to compare results & generate reports)
•
Phases – logical grouping of test actions, clear separation of setup / test / cleanup (preventing false fails)
•
Asserts – common checks affecting the overall results of the individual phases (checking for exit codes, file existence & content…)
•
Helpers – convenience functions for common operations such as managing services, backup & restore

The main script sets the "BEAKERLIB" variable and sources other scripts where the actual functions are defined. You should source it at the beginning of your test with: 

 . /usr/share/beakerlib/beakerlib.sh
See the EXAMPLES section for quick start inspiration.

See the BKRDOC section for more information about Automated documentation generator for BeakerLib tests.

Functions

Journalling

rlJournalStart

Initialize the journal file. 

 rlJournalStart
Run on the very beginning of your script to initialize journalling functionality.

rlJournalEnd

Summarize the test run and upload the journal file. 

 rlJournalEnd
Run on the very end of your script to print summary of the whole test run, generate OUTPUTFILE and include journal in Beaker logs.

rlJournalPrint

Print the content of the journal in pretty xml format. 

 rlJournalPrint [type]
type
Can be either ‘raw’ or ‘pretty’, with the latter as a default. Raw: xml is in raw form, no indentation etc Pretty: xml is pretty printed, indented, with one record per line

Example: 

 <?xml version="1.0"?>

 <BEAKER_TEST>

 <test_id>debugging</test_id>

 <package>setup</package>

 <pkgdetails>setup-2.8.9-1.fc12.noarch</pkgdetails>

 <starttime>2010-02-08 15:17:47</starttime>

 <endtime>2010-02-08 15:17:47</endtime>

 <testname>/examples/beakerlib/Sanity/simple</testname>

 <release>Fedora release 12 (Constantine)</release>

 <hostname>localhost</hostname>

 <arch>i686</arch>

 <purpose>PURPOSE of /examples/beakerlib/Sanity/simple

 Description: Minimal BeakerLib sanity test

 Author: Petr Splichal &lt;psplicha [at] redhat.com&gt;

 This is a minimal sanity test for BeakerLib. It contains a single

 phase with a couple of asserts. We Just check that the "setup"

 package is installed and that there is a sane /etc/passwd file.

 </purpose>

 <log>

 <phase endtime="2010-02-08 15:17:47" name="Test" result="PASS"

 score="0" starttime="2010-02-08 15:17:47" type="FAIL">

 <test message="Checking for the presence of setup rpm">PASS</test>

 <test message="File /etc/passwd should exist">PASS</test>

 <test message="File ‘/etc/passwd’ should contain ‘root’">PASS</test>

 </phase>

 </log>

 </BEAKER_TEST>
rlJournalPrintText

Print the content of the journal in pretty text format. 

 rlJournalPrintText [–full-journal]
–full-journal
With this option, additional items like some HW information will be printed in the journal.

Example: 

 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

 :: [ LOG ] :: TEST PROTOCOL

 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

 :: [ LOG ] :: Test run ID : debugging

 :: [ LOG ] :: Package : debugging

 :: [ LOG ] :: Test started : 2010-02-08 14:45:57

 :: [ LOG ] :: Test finished : 2010-02-08 14:45:58

 :: [ LOG ] :: Test name :

 :: [ LOG ] :: Distro: : Fedora release 12 (Constantine)

 :: [ LOG ] :: Hostname : localhost

 :: [ LOG ] :: Architecture : i686

 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

 :: [ LOG ] :: Test description

 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

 PURPOSE of /examples/beakerlib/Sanity/simple

 Description: Minimal BeakerLib sanity test

 Author: Petr Splichal <psplicha [at] redhat.com>

 This is a minimal sanity test for BeakerLib. It contains a single

 phase with a couple of asserts. We Just check that the "setup"

 package is installed and that there is a sane /etc/passwd file.

 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

 :: [ LOG ] :: Test

 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

 :: [ PASS ] :: Checking for the presence of setup rpm

 :: [ PASS ] :: File /etc/passwd should exist

 :: [ PASS ] :: File ‘/etc/passwd’ should contain ‘root’

 :: [ LOG ] :: Duration: 1s

 :: [ LOG ] :: Assertions: 3 good, 0 bad

 :: [ PASS ] :: RESULT: Test
rlGetTestState

Returns number of failed asserts in so far, 255 if there are more then 255 failures. 

 rlGetTestState
rlGetPhaseState

Returns number of failed asserts in current phase so far, 255 if there are more then 255 failures. 

 rlGetPhaseState

Logging

rlLog

rlLogDebug

rlLogInfo

rlLogWarning

rlLogError

rlLogFatal

Create a time/priority-labelled message in the log. There is a bunch of aliases which can create messages formated as DEBUG/INFO/WARNING/ERROR or FATAL (but you would probably want to use rlDie instead of the last one). 

 rlLog message [logfile] [priority] [label]
message
Message you want to show (use quotes when invoking).
logfile
Log file. If not supplied, OUTPUTFILE is assumed.
priority
Priority of the log.
label
Print this text instead of time in log label.

rlDie

Create a time-labelled message in the log, report test result, upload logs, close unfinished phase and terminate the test. 

 rlDie message [file…]
message
Message you want to show (use quotes when invoking) – this option is mandatory.
file
Files (logs) you want to upload as well. "rlBundleLogs" will be used for it. Files which are not readable will be excluded before calling "rlBundleLogs", so it is safe to call even with possibly not existent logs and it will succeed.

rlBundleLogs

Create a tarball of files (e.g. logs) and attach them to the test result. 

 rlBundleLogs package file [file…]
package
Name of the package. Will be used as a part of the tar-ball name.
file
File(s) to be packed and submitted.

Returns result of submiting the tarball.

rlFileSubmit

Resolves absolute path to the file, replaces / for – and uploads this renamed file using rhts-submit-log. It also allows you to specify your custom name for the uploaded file. 

 rlFileSubmit [-s sep] path_to_file [required_name]
-s sep
Sets separator (i.e. the replacement of the /) to sep.
path_to_file
Either absolute or relative path to file. Relative path is converted to absolute.
required_name
Default behavior renames file to full_path_to_file with / replaced for -, if this does not suit your needs, you can specify the name using this option.

Examples:

rlFileSubmit logfile.txt -> logfile.txt cd /etc; rlFileSubmit ./passwd -> etc-passwd rlFileSubmit /etc/passwd -> etc-passwd rlFileSubmit /etc/passwd my-top-secret_file -> my-top-secret-file rlFileSubmit -s ‘_’ /etc/passwd -> etc_passwd

Info

rlShowPackageVersion

Shows a message about version of packages. 

 rlShowPackageVersion package [package…]
package
Name of a package(s) you want to log.

rlGetArch

This function is deprecated. Use rlGetPrimaryArch or rlGetSecondaryArch instead, or use uname. This function will be only kept for compatibility.

Return base arch for the current system (good when you need base arch on a multilib system). 

 rlGetArch
On an i686 system you will get i386, on a ppc64 you will get ppc.

rlGetPrimaryArch

Return primary arch for the current system (good when you need base arch on a multilib system). 

 rlGetPrimaryArch
rlGetSecondaryArch

Return base arch for the current system (good when you need base arch on a multilib system). 

 rlGetSecondaryArch
rlGetDistroRelease

rlGetDistroVariant

Return release or variant of the distribution on the system. 

 rlGetDistroRelease

 rlGetDistroVariant
For example on the RHEL-4-AS you will get release 4 and variant AS, on the RHEL-5-Client you will get release 5 and variant Client.

rlShowRunningKernel

Log a message with version of the currently running kernel. 

 rlShowRunningKernel

Phases

rlPhaseStart

Starts a phase of a specific type. The final phase result is based on all asserts included in the phase. Do not forget to end phase with "rlPhaseEnd" when you are done. 

 rlPhaseStart type [name]
type
Type of the phase, one of the following:
FAIL
When assert fails here, phase will report a FAIL.
WARN
When assert fails here, phase will report a WARN.
name
Optional name of the phase (if not provided, one will be generated).

If all asserts included in the phase pass, phase reports PASS.

rlPhaseEnd

End current phase, summarize asserts included and report phase result. 

 rlPhaseEnd
Final phase result is based on included asserts and phase type.

rlPhaseStartSetup

rlPhaseStartTest

rlPhaseStartCleanup

Start a phase of the specified type: Setup -> WARN, Test -> FAIL, Cleanup -> WARN. 

 rlPhaseStartSetup [name]

 rlPhaseStartTest [name]

 rlPhaseStartCleanup [name]
name
Optional name of the phase. If not specified, default Setup/Test/Cleanup are used.

If you do not want these shortcuts, use plain "rlPhaseStart" function.

Metric

rlLogMetricLow

Log a metric, which should be as low as possible to the journal. (Example: memory consumption, run time) 

 rlLogMetricLow name value [tolerance]
name
Name of the metric. It has to be unique in a phase.
value
Value of the metric.
tolerance
It is used when comparing via rcw. It means how larger can the second value be to not trigger a FAIL. Default is 0.2

When comparing FIRST, SECOND, then: 

 FIRST >= SECOND means PASS

 FIRST+FIRST*tolerance >= SECOND means WARN

 FIRST+FIRST*tolerance < SECOND means FAIL
Example: Simple benchmark is compared via this metric type in rcw. It has a tolerance of 0.2. First run had 1 second. So: 

 For PASS, second run has to be better or equal to first.

 So any value of second or less is a PASS.

 For WARN, second run can be a little worse than first.

 Tolerance is 0.2, so anything lower than 1.2 means WARN.

 For FAIL, anything worse than 1.2 means FAIL.
rlLogMetricHigh

Log a metric, which should be as high as possible to the journal. (Example: number of executions per second) 

 rlLogMetricHigh name value [tolerance]
name
Name of the metric. It has to be unique in a phase.
value
Value of the metric.
tolerance
It is used when comparing via rcw. It means how lower can the second value be to not trigger a FAIL. Default is 0.2

When comparing FIRST, SECOND, then: 

 FIRST <= SECOND means PASS

 FIRST+FIRST*tolerance <= SECOND means WARN

 FIRST+FIRST*tolerance > SECOND means FAIL

Manual Asserts

rlPass

Manual assertion, asserts and logs PASS. 

 rlPass comment
comment
Short test summary.

Returns 0 and asserts PASS.

rlFail

Manual assertion, asserts and logs FAIL. 

 rlFail comment
comment
Short test summary.

Returns 1 and asserts FAIL.

Arithmetic Asserts

rlAssert0

Assertion checking for the equality of parameter to zero. 

 rlAssert0 comment value
comment
Short test summary, e.g. “Test if compilation ended successfully”.
value
Integer value (usually return code of a command).

Returns 0 and asserts PASS when "value == 0".

rlAssertEquals

Assertion checking for the equality of two parameters. 

 rlAssertEquals comment value1 value2
comment
Short test summary, e.g. “Test if all 3 packages have been downloaded”.
value1
First parameter to compare, can be a number or a string
value2
Second parameter to compare, can be a number or a string

Returns 0 and asserts PASS when "value1 == value2".

rlAssertNotEquals

Assertion checking for the non-equality of two parameters. 

 rlAssertNotEquals comment value1 value2
comment
Short test summary, e.g. “Test if return code is not 139”.
value1
First parameter to compare, can be a number or a string
value2
Second parameter to compare, can be a number or a string

Returns 0 and asserts PASS when "value1 != value2".

rlAssertGreater

Assertion checking whether first parameter is greater than the second one. 

 rlAssertGreater comment value1 value2
comment
Short test summary, e.g. “Test whether there are running more instances of program.”
value1
Integer value.
value2
Integer value.

Returns 0 and asserts PASS when "value1 > value2".

rlAssertGreaterOrEqual

Assertion checking whether first parameter is greater or equal to the second one. 

 rlAssertGreaterOrEqual comment value1 value2
comment
Short test summary (e.g. “There should present at least one…”)
value1
Integer value.
value2
Integer value.

Returns 0 and asserts PASS when "value1 >= value2".

File Asserts

rlAssertExists

Assertion checking for the existence of a file or a directory. 

 rlAssertExists file|directory
file|directory
Path to the file or directory.

Returns 0 and asserts PASS when "file" exists.

rlAssertNotExists

Assertion checking for the non-existence of a file or a directory. 

 rlAssertNotExists file|directory
file|directory
Path to the file or directory.

Returns 0 and asserts PASS when "file" does not exist.

rlAssertGrep

Assertion checking if the file contains a pattern. 

 rlAssertGrep pattern file [options]
pattern
Regular expression to be searched for.
file
Path to the file.
options
Optional parameters to be passed to grep, default is "-q". Can be used to perform case insensitive matches (-i), or using extended (-E) or perl (-P) regular expressions.

Returns 0 and asserts PASS when "file" exists and contains given "pattern".

rlAssertNotGrep

Assertion checking that the file does not contain a pattern. 

 rlAssertNotGrep pattern file [options]
pattern
Regular expression to be searched for.
file
Path to the file.
options
Optional parameters to be passed to grep, default is "-q". Can be used to perform case insensitive matches (-i), or using extended (-E) or perl (-P) regular expressions.

Returns 0 and asserts PASS when "file" exists and does not contain given "pattern".

rlAssertDiffer

Assertion checking that two files differ (are not identical). 

 rlAssertDiffer file1 file2
file1
Path to first file1
file2
Path to second file

Returns 0 and asserts PASS when "file1" and "file2" differs.

rlAssertNotDiffer

Assertion checking that two files do not differ (are identical). 

 rlAssertNotDiffer file1 file2
file1
Path to first file1
file2
Path to second file

Returns 0 and asserts PASS when "file1" and "file2" do not differ.

Run, Watch, Report

rlRun

Run command with optional comment and make sure its exit code matches expectations. 

 rlRun [-t] [-l] [-c] [-s] command [status[,status…]] [comment]
-t
If specified, stdout and stderr of the command output will be tagged with strigs ‘STDOUT: ‘ and ‘STDERR: ‘.
-l
If specified, output of the command (tagged, if -t was specified) is logged using rlLog function. This is intended for short outputs, and therefore only last 50 lines are logged this way. Longer outputs should be analysed separately, or uploaded via rlFileSubmit or rlBundleLogs.
-c
Same as "-l", but only log the commands output if it failed.
-s
Store stdout and stderr to a file (mixed together, as the user would see it on a terminal) and set $rlRun_LOG variable to name of the file. Caller is responsible for removing the file. When -t option is used, the content of the file becomes tagged too.

If the -s option is not used, $rlRun_LOG is not modified and keeps its content from the last “rlRun -s”.

command
Command to run.
status
Expected exit code(s). Optional, default 0. If you expect more exit codes, separate them with comma (e.g. “0,1” when both 0 and 1 are OK and expected), or use from-to notation (i.e. “2-5” for “2,3,4,5”), or combine them (e.g. “2-4,26” for “2,3,4,26”).
comment
Short summary describing the action (optional, but recommended – explain what are you doing here).

Returns the exit code of the command run. Asserts PASS when command\’s exit status is in the list of expected exit codes.

Note:

•
The output of rlRun is buffered when using "-t", "-l" or "-s" option (they use unix pipes, which are buffered by nature). If you need an unbuffered output just make sure that "expect" package is installed on your system (its “unbuffer” tool will automatically be used to produce unbuffered output).
•
Be aware that there are some variables which can collide with your code executed within rlRun. You should avoid using __INTERNAL_rlRun_* variables.

Warning: using "unbuffer" tool is now disabled because of bug 547686.

rlWatchdog

Run "command". If it does not finish in specified time, then kill it using "signal". 

 rlWatchdog command timeout [signal] [callback]
command
Command to run.
timeout
Timeout to wait, in seconds.
signal
Signal to use (optional, default KILL).
callback
Callback function to be called before the signal is send (optional, none by default). The callback function will have one argument available — PGID of the process group.

Returns 0 if the command ends normally, without need to be killed.

rlReport

Report test result to the test harness. The command to be used for reporting is set by the respective plugin. You can also use the $BEAKERLIB_COMMAND_REPORT_RESULT variable to use your custom command. 

 rlReport name result [score] [log]
name
Name of the test result.
result
Result (one of PASS, WARN, FAIL). If called with something else, will use WARN.
score
Test score (optional).
log
Optional log file to be submitted instead of default "OUTPUTFILE".

rlCmpVersion

Compare two given versions composed by numbers and letters divided by dot (.), underscore (_), or dash (-). 

 rlCmpVersion ver1 ver2
If ver1 = ver2, sign ‘=’ is printed to stdout and 0 is returned. If ver1 > ver2, sign ‘>’ is printed to stdout and 1 is returned. If ver1 < ver2, sign ‘<‘ is printed to stdout and 2 is returned.

rlTestVersion

Test releation between two given versions based on given operator. 

 rlTestVersion ver1 op ver2
op
Operator definitng the logical expression. It can be ‘=’, ‘==’, ‘!=’, ‘<‘, ‘<=’, ‘=<‘, ‘>’, ‘>=’, or ‘=>’.

Returns 0 if the expresison ver1 op ver2 is true; 1 if the expression is false and 2 if something went wrong.

Release Info

rlIsRHEL

Check whether we’re running on RHEL. With given number of version as parameter returns 0 if the particular RHEL version is running. Multiple arguments can be passed separated with space as well as any particular release (5.1 5.2 5.3). Each version can have a prefix consisting of ‘<‘, ‘<=’, ‘=’, ‘>=’, ‘>’, matching whenever the currently installed version is lesser, lesser or equal, equal, equal or greater, greater than the version specified as argument. Note that ie. ‘=5’ (unlike just ‘5’) matches exactly 5 (5.0), not 5.N, where N > 0. 

 rlIsRHEL
Returns 0 if we are running on RHEL. 

 rlIsRHEL 4.8 5
Returns 0 if we are running RHEL 4.8 or any RHEL 5.

rlIsFedora

Check whether we’re running on Fedora. With given number of version as parameter returns 0 if the particular Fedora version is running. Range matching can be used in the form used by rlIsRHEL. 

 rlIsFedora
Returns 0 if we are running on Fedora. 

 rlIsFedora 9 10
Returns 0 if we are running Fedora 9 or 10.

Release Info

rlIsCentOS

Check whether we’re running on CentOS. With given number of version as parameter returns 0 if the particular CentOS version is running. Multiple arguments can be passed separated with space as well as any particular release (5.1 5.2 5.3). Each version can have a prefix consisting of ‘<‘, ‘<=’, ‘=’, ‘>=’, ‘>’, matching whenever the currently installed version is lesser, lesser or equal, equal, equal or greater, greater than the version specified as argument. Note that ie. ‘=5’ (unlike just ‘5’) matches exactly 5 (5.0), not 5.N, where N > 0. 

 rlIsCentOS
Returns 0 if we are running on CentOS. 

 rlIsCentOS 7.1 6
Returns 0 if we are running CentOS 7.1 or any CentOS 6.

Rpm Handling

rlCheckRpm

Check whether a package is installed. 

 rlCheckRpm name [version] [release] [arch]
name
Package name like "kernel"
version
Package version like 2.6.25.6
release
Package release like "55.fc9"
arch
Package architucture like "i386"

Returns 0 if the specified package is installed.

rlAssertRpm

Assertion making sure that a package is installed. 

 rlAssertRpm name [version] [release] [arch]>

 rlAssertRpm –all
name
Package name like "kernel"
version
Package version like 2.6.25.6
release
Package release like "55.fc9"
arch
Package architucture like "i386"
–all
Assert all packages listed in the $PACKAGES $REQUIRES and $COLLECTIONS environment variables.

Returns 0 and asserts PASS if the specified package is installed.

rlAssertNotRpm

Assertion making sure that a package is not installed. This is just inverse of "rlAssertRpm". 

 rlAssertNotRpm name [version] [release] [arch]>
name
Package name like "kernel"
version
Package version like 2.6.25.6
release
Package release like "55.fc9"
arch
Package architucture like "i386"

Returns 0 and asserts PASS if the specified package is not installed.

Example

Function "rlAssertRpm" is useful especially in prepare phase where it causes abort if a package is missing, while "rlCheckRpm" is handy when doing something like: 

 if ! rlCheckRpm package; then

 yum install package

 rlAssertRpm package

 fi
rlAssertBinaryOrigin

Assertion making sure that given binary is owned by (one of) the given package(s). 

 rlAssertBinaryOrigin binary package [package2 […]]

 PACKAGES=… rlAssertBinaryOrigin binary
binary
Binary name like "ksh" or "/bin/ksh"
package
List of packages like "ksh mksh". The parameter is optional. If missing, contents of environment variable $PACKAGES are taken into account.

Returns 0 and asserts PASS if the specified binary belongs to (one of) the given package(s). Returns 1 and asserts FAIL if the specified binary does not belong to (any of) the given package(s). Returns 2 and asserts FAIL if the specified binary is not found. Returns 3 and asserts FAIL if no packages are given. Returns 100 and asserts FAIL if invoked with no parameters.

Example

Function "rlAssertBinaryOrigin" is useful especially in prepare phase where it causes abort if a binary is missing or is owned by different package: 

 PACKAGES=mksh rlAssertBinaryOrigin ksh

 or

 rlAssertBinaryOrigin ksh mksh
Returns true if ksh is owned by the mksh package (in this case: /bin/ksh is a symlink pointing to /bin/mksh).

rlGetMakefileRequires

Prints comma separated list of requirements defined in Makefile using ‘Requires’ attribute.

Return 0 if success.

rlCheckRequirements

Check that all given requirements are covered eigther by installed package or by binary available in PATHs or by some package’s provides. 

 rlRun "rlCheckRequirements REQ…"
REQ
Requirement to be checked. It can be package name, provides string or binary name.

Returns number of unsatisfied requirements.

rlCheckMakefileRequires

This is just a bit smarted wrapper of

"rlCheckRequirements $(rlGetMakefileRequires)"

Example 

 rlRun "rlCheckMakefileRequires"
Return 255 if requirements could not be retrieved, 0 if all requirements are satisfied or number of unsatisfied requirements.

Mounting

rlMount

Create mount point (if neccessary) and mount a NFS share. 

 rlMount [-o MOUNT_OPTS] server share mountpoint
server
NFS server hostname.
share
Shared directory name.
mountpoint
Local mount point.
MOUNT_OPTS
Mount options.

Returns 0 if mounting the share was successful.

rlCheckMount

Check either if a directory is a mountpoint, if it is a mountpoint to a specific server, or if it is a mountpoint to a specific export on a specific server and if it uses specific mount options. 

 rlCheckMount [-o MOUNT_OPTS] mountpoint

 rlCheckMount [-o MOUNT_OPTS] server mountpoint

 rlCheckMount [-o MOUNT_OPTS] server share mountpoint
mountpoint
Local mount point.
server
NFS server hostname
share
Shared directory name
MOUNT_OPTS
Mount options to check (comma separated list)

With one parameter, returns 0 when specified directory exists and is a mountpoint. With two parameters, returns 0 when specific directory exists, is a mountpoint and an export from specific server is mounted there. With three parameters, returns 0 if a specific shared directory is mounted on a given server on a given mountpoint

If the -o option is provided, returns 0 if the mountpoint uses all the given options, 2 otherwise.

rlAssertMount

Assertion making sure that given directory is a mount point, if it is a mountpoint to a specific server, or if it is a mountpoint to a specific export on a specific server and if it uses specific mount options. 

 rlAssertMount [-o MOUNT_OPTS] mountpoint

 rlAssertMount [-o MOUNT_OPTS] server mountpoint

 rlAssertMount [-o MOUNT_OPTS] server share mountpoint
mountpoint
Local mount point.
server
NFS server hostname
share
Shared directory name
MOUNT_OPTS
Mount options to check (comma separated list)

With one parameter, returns 0 when specified directory exists and is a mountpoint. With two parameters, returns 0 when specific directory exists, is a mountpoint and an export from specific server is mounted there. With three parameters, returns 0 if a specific shared directory is mounted on a given server on a given mountpoint. Asserts PASS when the condition is true.

If the -o option is provided, asserts PASS if the above conditions are met and the mountpoint uses all the given options.

rlHash, rlUnhash

Hashes/Unhashes given string. 

 rlHash [–decode] [–algorithm HASH_ALG] –stdin|STRING

 rlUnhash [–algorithm HASH_ALG] –stdin|STRING
–decode
Unhash given string.
–algorithm
Use given hash algorithm. Currently supported algorithms:
  base64
  base64_ – this is standard base64 where ‘=’ is replaced by ‘_’
  hex

Defaults to hex. Default algorithm can be override using global variable rlHashAlgorithm.

–stdin
Get the string from stdin.
STRING
String to be hashed/unhashed.

Returns 0 if success.

Example with –clean: 

 hash=rlHash "text"

Backup and Restore

rlFileBackup

Create a backup of files or directories (recursive). Can be used multiple times to add more files to backup. Backing up an already backed up file overwrites the original backup. 

 rlFileBackup [–clean] [–namespace name] [–missing-ok|–no-missing-ok] file [file…]
You can use "rlRun" for asserting the result but keep in mind meaning of exit codes, especialy exit code 8, if using without –clean option.
–clean
If this option is provided (have to be first option of the command), then file/dir backuped using this command (provided in next options) will be (recursively) removed before we will restore it. This option implies –missing-ok, this can be overridden by –no-missing-ok.
–namespace name
Specifies the namespace to use. Namespaces can be used to separate backups and their restoration.
–missing-ok
Do not raise an error in case of missing file to backup.
–no-missing-ok
Do raise an error in case of missing file to backup. This is useful with –clean. This behaviour can be globally set by global variable BEAKERLIB_FILEBACKUP_MISSING_OK=false.
file
Files and/or directories to be backed up.

Returns 0 if the backup was successful. Returns 1 if parsing of parameters was not successful. Returns 2 if no files specification was provided. Returns 3 if BEAKERLIB_DIR variable is not set, e.g. rlJournalStart was not executed. Returns 4 if creating of main backup destination directories was not successful. Returns 5 if creating of file specific backup destination directories was not successful. Returns 6 if the copy of backed up files was not successful. Returns 7 if attributes of backedup files were not successfuly copied. Returns 8 if backed up files does not exist. This can be suppressed based on other options.

Example with –clean: 

 touch cleandir/aaa

 rlRun "rlFileBackup –clean cleandir/"

 touch cleandir/bbb

 ls cleandir/

 aaa bbb

 rlRun "rlFileRestore"

 ls cleandir/

 aaa
rlFileRestore

Restore backed up files to their original location. "rlFileRestore" does not remove new files appearing after backup has been made. If you don’t want to leave anything behind just remove the whole original tree before running "rlFileRestore", or see "–clean" option of "rlFileBackup". 

 rlFileRestore [–namespace name]
You can use "rlRun" for asserting the result.
–namespace name
Specifies the namespace to use. Namespaces can be used to separate backups and their restoration.

Returns 0 if backup dir is found and files are restored successfully.

Return code bits meaning XXXXX
                   |||||
                   ||||\_ error parsing parameters
                   |||\__ could not find backup directory
                   ||\___ files cleanup failed
                   |\____ files restore failed
                   \_____ no files were restored nor cleaned

Services

Following routines implement comfortable way how to start/stop system services with the possibility to restore them to their original state after testing.

rlServiceStart

Make sure the given "service" is running with fresh configuration. (Start it if it is stopped and restart if it is already running.) In addition, when called for the first time, the current state is saved so that the "service" can be restored to its original state when testing is finished, see "rlServiceRestore". 

 rlServiceStart service [service…]
service
Name of the service(s) to start.

Returns number of services which failed to start/restart; thus zero is returned when everything is OK.

rlServiceStop

Make sure the given "service" is stopped. Stop it if it is running and do nothing when it is already stopped. In addition, when called for the first time, the current state is saved so that the "service" can be restored to its original state when testing is finished, see "rlServiceRestore". 

 rlServiceStop service [service…]
service
Name of the service(s) to stop.

Returns number of services which failed to become stopped; thus zero is returned when everything is OK.

rlServiceRestore

Restore given "service" into its original state (before the first "rlServiceStart" or "rlServiceStop" was called). 

 rlServiceRestore [service…]
service
Name of the service(s) to restore to original state. All services will be restored in reverse order if no service name is given.

Returns number of services which failed to get back to their original state; thus zero is returned when everything is OK.

rlServiceEnable

Enables selected services if needed, or does nothing if already enabled. In addition, when called for the first time, the current state is saved so that the "service" can be restored to its original state when testing is finished, see "rlServiceRestore". 

 rlServiceEnable service [service…]
service
Name of the service(s) to enable.

Returns number of services which failed enablement; thus zero is returned when everything is OK.

rlServiceDisable

Disables selected services if needed, or does nothing if already disabled. In addition, when called for the first time, the current state is saved so that the "service" can be restored to its original state when testing is finished, see "rlServiceRestore". 

 rlServiceDisable service [service…]
service
Name of the service(s) to disable.

Returns number of services which failed disablement; thus zero is returned when everything is OK.

Sockets

Following routines implement comfortable way how to start/stop system sockets with the possibility to restore them to their original state after testing.

rlSocketStart

Make sure the given "socket" is running. (Start it if stopped, leave it if already running.) In addition, when called for the first time, the current state is saved so that the "socket" can be restored to its original state when testing is finished, see "rlSocketRestore". 

 rlSocketStart socket [socket…]
socket
Name of the socket(s) to start.

Returns number of sockets which failed to start/restart; thus zero is returned when everything is OK.

rlSocketStop

Make sure the given "socket" is stopped. Stop it if it is running and do nothing when it is already stopped. In addition, when called for the first time, the current state is saved so that the "socket" can be restored to its original state when testing is finished, see "rlSocketRestore". 

 rlSocketStop socket [socket…]
socket
Name of the socket(s) to stop.

Returns number of sockets which failed to become stopped; thus zero is returned when everything is OK.

rlSocketRestore

Restore given "socket" into its original state (before the first "rlSocketStart" or "rlSocketStop" was called).

Warning !!! Xinetd process [even though it might have been used] is NOT restored. It is recommended to call rlServiceRestore xinetd as well. 

 rlSocketRestore socket [socket…]
socket
Name of the socket(s) to restore to original state.

Returns number of sockets which failed to get back to their original state; thus zero is returned when everything is OK.

Cleanup management

Cleanup management works with a so-called cleanup buffer, which is a temporary representation of what should be run at cleanup time, and a final cleanup script (executable), which is generated from this buffer and wraps it using BeakerLib essentials (journal initialization, cleanup phase, …). The cleanup script must always be updated on an atomic basis (filesystem-wise) to allow an asynchronous execution by a third party (ie. test watcher).

The test watcher usage is mandatory for the cleanup management system to work properly as it is the test watcher that executes the actual cleanup script. Limited, catastrophe-avoiding mechanism is in place even when the test is not run in test watcher, but that should be seen as a backup and such situation is to be avoided whenever possible.

The cleanup script shares all environment (variables, exported or not, and functions) with the test itself – the cleanup append/prepend functions “sample” or “snapshot” the environment at the time of their call, IOW any changes to the test environment are synchronized to the cleanup script only upon calling append/prepend. When the append/prepend functions are called within a function which has local variables, these will appear as global in the cleanup.

While the cleanup script receives $PWD from the test, its working dir is set to the initial test execution dir even if $PWD contains something else. It is impossible to use relative paths inside cleanup reliably – certain parts of the cleanup might have been added under different current directories (CWDs). Therefore always use absolute paths in append/prepend cleanup or make sure you never ‘cd’ elsewhere (ie. to a TmpDir).

rlCleanupAppend

Appends a string to the cleanup buffer and recreates the cleanup script. 

 rlCleanupAppend string
Returns 0 if the operation was successful, 1 otherwise.

rlCleanupPrepend

Prepends a string to the cleanup buffer and recreates the cleanup script. 

 rlCleanupPrepend string
Returns 0 if the operation was successful, 1 otherwise.

Time Performance

rlPerfTime_RunsInTime

Measures, how many runs of some commands can be done in specified time. This approach is suitable for short-time running tasks (up to few seconds), where averaging few runs is not precise. This is done several times, and the final result is the average of all runs. It prints the number on stdout, so it has to be captured. 

 rlPerfTime_RunsInTime command [time] [runs]
command
Command to run.
time
Time in seconds (optional, default=30).
runs
Number of averaged runs (optional, default=3).

rlPerfTime_AvgFromRuns

Measures the average time of running some task. This approach is suitable for long-time running tasks (tens of seconds and more), where it is precise enough. Measured runs can be preceded by dry run, which is not measured and it’s purpose is to warm up various caches. It prints the number on stdout, so it has to be captured. Or, result is then stored in special rl_retval variable. 

 rlPerfTime_AvgFromRuns command [count] [warmup]
command
Command to run.
count
Times to run (optional, default=3).
warmup
Warm-up run, run if this option is not “warmup” (optional, default=“warmup”)

Analyze

rlDejaSum

TODO description 

 rlDejaSum par1 par2
par1
TODO description
par2
TODO description

Return 0 if… TODO

rlImport

Imports code provided by one or more libraries into the test namespace. The library search mechanism is based on Beaker test hierarchy system, i.e.:

/component/type/test-name/test-file

When test-file calls rlImport with ‘foo/bar’ parameter, the directory path is traversed upwards, and a check for presence of the test /foo/Library/bar/ will be performed. This means this function needs to be called from the test hierarchy, not e.g. the /tmp directory.

Once library is found, it is sourced and a verifier function is called. The verifier function is cunstructed by composing the library prefix and LibraryLoaded. Library prefix can be defined in the library itself. If the verifier passes the library is ready to use. Also variable <PREFIX>LibraryDir is created and it points to the library folder.

Usage: 

 rlImport –all

 rlImport LIBRARY [LIBRARY2…]
–all
Read Makefile in current/original directory, pick library requirements up and import them all.
LIBRARY
Must have ‘component/library’ format. Identifies the library to import.

Returns 0 if the import of all libraries was successful. Returns non-zero if one or more library failed to import.

Process Synchronisation

rlWaitForCmd

Pauses script execution until command exit status is the expeced value. Logs a WARNING and returns 1 if the command didn’t exit successfully before timeout elapsed or a maximum number of invocations has been reached. 

 rlWaitForCmd command [-p PID] [-t time] [-m count] [-d delay] [-r retval]
command
Command that will be executed until its return code is equal 0 or value speciefied as option to `-r’.
-t time
Timeout in seconds, default=120. If the command doesn’t return 0 before time elapses, the command will be killed.
-p PID
PID of the process to check before running command. If the process exits before the socket is opened, the command will log a WARNING.
-m count
Maximum number of `command’ executions before continuing anyway. Default is infite. Returns 1 if the maximum was reached.
-d delay
Delay between `command’ invocations. Default 1.
-r retval
Expected return value of command. Default 0.

rlWaitForFile

Pauses script execution until specified file or directory starts existing. Returns 0 if file started existing, 1 if timeout was reached or PID exited. Return code is greater than 1 in case of error. 

 rlWaitForFile path [-p PID] [-t time] [-d delay]
path
Path to file that should start existing.
-t time
Timeout in seconds (optional, default=120). If the file isn’t opened before the time elapses the command returns 1.
-p PID
PID of the process that should also be running. If the process exits before the file is created, the command returns with status code of 1.
-d delay
Delay between subsequent checks for existence of file. Default 1.

rlWaitForSocket

Pauses script execution until socket starts listening. Returns 0 if socket started listening, 1 if timeout was reached or PID exited. Return code is greater than 1 in case of error. 

 rlWaitForSocket {port|path} [-p PID] [-t time] [-d delay] [–close]
port|path
Network port to wait for opening or a path to UNIX socket. Regular expressions are also supported.
-t time
Timeout in seconds (optional, default=120). If the socket isn’t opened before the time elapses the command returns 1.
-p PID
PID of the process that should also be running. If the process exits before the socket is opened, the command returns with status code of 1.
-d delay
Delay between subsequent checks for availability of socket. Default 1.
–close
Wait for the socket to stop listening.

rlWait

Wrapper around bash builtin `wait’ command. See bash_builtins(1) man page. Kills the process and all its children if the timeout elapses. 

 rlWaitFor [n …] [-s SIGNAL] [-t time]
n
List of PIDs to wait for. They need to be background tasks of current shell. See bash_builtins(1) section for `wait’ command/
-t time
Timeout in seconds (optional, default=30). If the wait isn’t successful before the time elapses then all specified tasks are killed.
-s SIGNAL
Signal used to kill the process, optional SIGTERM by default.

Virtual X Server

Functions providing simple way how to start and stop virtual X server.

rlVirtualXStart

Start a virtual X server on a first free display. Tries only first N displays, so you can run out of them. 

 rlVirtualXStart name
name
String identifying the X server.

Returns 0 when the server is started successfully.

rlVirtualXGetDisplay

Get the DISPLAY variable for specified virtual X server. 

 rlVirtualXGetDisplay name
name
String identifying the X server.

Displays the number of display where specified virtual X server is running to standard output. Returns 0 on success.

rlVirtualXStop

Kill the specified X server. 

 rlVirtualXStop name
name
String identifying the X server.

Returns 0 when the server is stopped successfully.

Example

Below is a simple example of usage. Note that a lot of usefull debugging information is reported on the DEBUG level, so you can run your test with "DEBUG=1 make run" to get them. 

 rlVirtualXStart $TEST

 rlAssert0 "Virtual X server started" $?

 export DISPLAY="$( rlVirtualXGetDisplay $TEST )"

 # …your test which needs X…

 rlVirtualXStop $TEST

 rlAssert0 "Virtual X server killed" $?
These are “Requires” lines for your scripts – note different package names for different RHEL versions: 

 @echo "Requires: xorg-x11-server-Xvfb" >> $(METADATA) # RHEL-5

 @echo "Requires: xorg-x11-Xvfb" >> $(METADATA) # RHEL-4

 @echo "Requires: XFree86-Xvfb" >> $(METADATA) # RHEL-3

Examples

Simple

A minimal BeakerLib test can look like this: 

 . /usr/share/beakerlib/beakerlib.sh

 rlJournalStart

 rlPhaseStartTest

 rlAssertRpm "setup"

 rlAssertExists "/etc/passwd"

 rlAssertGrep "root" "/etc/passwd"

 rlPhaseEnd

 rlJournalEnd

Phases

Here comes a bit more interesting example of a test which sets all the recommended variables and makes use of the phases: 

 # Include the BeakerLib environment

 . /usr/share/beakerlib/beakerlib.sh

 # Set the full test name

 TEST="/examples/beakerlib/Sanity/phases"

 # Package being tested

 PACKAGE="coreutils"

 rlJournalStart

 # Setup phase: Prepare test directory

 rlPhaseStartSetup

 rlAssertRpm $PACKAGE

 rlRun ‘TmpDir=$(mktemp -d)’ 0 ‘Creating tmp directory’ # no-reboot

 rlRun "pushd $TmpDir"

 rlPhaseEnd

 # Test phase: Testing touch, ls and rm commands

 rlPhaseStartTest

 rlRun "touch foo" 0 "Creating the foo test file"

 rlAssertExists "foo"

 rlRun "ls -l foo" 0 "Listing the foo test file"

 rlRun "rm foo" 0 "Removing the foo test file"

 rlAssertNotExists "foo"

 rlRun "ls -l foo" 2 "Listing foo should now report an error"

 rlPhaseEnd

 # Cleanup phase: Remove test directory

 rlPhaseStartCleanup

 rlRun "popd"

 rlRun "rm -r $TmpDir" 0 "Removing tmp directory"

 rlPhaseEnd

 rlJournalEnd

 # Print the test report

 rlJournalPrintText
The ouput of the rlJournalPrintText command would produce an output similar to the following: 

 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

 :: [ LOG ] :: TEST PROTOCOL

 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

 :: [ LOG ] :: Test run ID : debugging

 :: [ LOG ] :: Package : coreutils

 :: [ LOG ] :: Installed: : coreutils-7.6-9.fc12.i686

 :: [ LOG ] :: Test started : 2010-02-08 14:55:44

 :: [ LOG ] :: Test finished : 2010-02-08 14:55:50

 :: [ LOG ] :: Test name : /examples/beakerlib/Sanity/phases

 :: [ LOG ] :: Distro: : Fedora release 12 (Constantine)

 :: [ LOG ] :: Hostname : localhost

 :: [ LOG ] :: Architecture : i686

 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

 :: [ LOG ] :: Test description

 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

 PURPOSE of /examples/beakerlib/Sanity/phases

 Description: Testing BeakerLib phases

 Author: Petr Splichal <psplicha [at] redhat.com>

 This example shows how the phases work in the BeakerLib on a

 trivial smoke test for the "touch", "ls" and "rm" commands from

 the coreutils package.

 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

 :: [ LOG ] :: Setup

 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

 :: [ PASS ] :: Checking for the presence of coreutils rpm

 :: [ PASS ] :: Creating tmp directory

 :: [ PASS ] :: Running ‘pushd /tmp/tmp.IcluQu5GVS’ # no-reboot

 :: [ LOG ] :: Duration: 0s

 :: [ LOG ] :: Assertions: 3 good, 0 bad

 :: [ PASS ] :: RESULT: Setup

 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

 :: [ LOG ] :: Test

 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

 :: [ PASS ] :: Creating the foo test file

 :: [ PASS ] :: File foo should exist

 :: [ PASS ] :: Listing the foo test file

 :: [ PASS ] :: Removing the foo test file

 :: [ PASS ] :: File foo should not exist

 :: [ PASS ] :: Listing foo should now report an error

 :: [ LOG ] :: Duration: 1s

 :: [ LOG ] :: Assertions: 6 good, 0 bad

 :: [ PASS ] :: RESULT: Test

 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

 :: [ LOG ] :: Cleanup

 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

 :: [ PASS ] :: Running ‘popd’

 :: [ PASS ] :: Removing tmp directory

 :: [ LOG ] :: Duration: 1s

 :: [ LOG ] :: Assertions: 2 good, 0 bad

 :: [ PASS ] :: RESULT: Cleanup
Note that the detailed test description is read from a separate file PURPOSE placed in the same directory as the test itself.

A lot of useful debugging information is reported on the DEBUG level. You can run your test with "DEBUG=1 make run" to get them.

Verbosity of the test logging may be altered also by setting the LOG_LEVEL variable. Possible values are “ERROR”, “WARNING”, “INFO” and “DEBUG”. You will see messages like the ones below. 

 :: [ WARNING ] :: rlGetArch: Update test to use rlGetPrimaryArch/rlGetSecondaryArch

 :: [ DEBUG ] :: rlGetArch: This is architecture ‘x86_64’

 :: [ ERROR ] :: this function was dropped as its development is completely moved to the beaker library

 :: [ INFO ] :: if you realy on this function and you really need to have it present in core beakerlib, file a RFE, please
Setting LOG_LEVEL=“DEBUG” is equivalent to DEBUG=1.

Bkrdoc

Description
Bkrdoc is a documentation generator from tests written using BeakerLib library. This generator makes documentation from test code with and also without any documentation markup.
What it’s good for
For fast, brief and reliable documentation creation. It`s good for quick start with unknown BeakerLib test. Created documentations provides information about the documentation credibility. Also created documentations shows environmental variables and helps reader to run test script from which was documentation created.
Bkrdoc project page
https://github.com/rh-lab-q/bkrdoc

Links

Project Page
https://fedorahosted.org/beakerlib/
Manual
https://fedorahosted.org/beakerlib/wiki/Manual
Reporting bugs
https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora&component=beakerlib

Authors

•
Petr Muller <pmuller [at] redhat.com>
•
Ondrej Hudlicky <ohudlick [at] redhat.com>
•
Jan Hutar <jhutar [at] redhat.com>
•
Petr Splichal <psplicha [at] redhat.com>
•
Ales Zelinka <azelinka [at] redhat.com>
•
Dalibor Pospisil <dapospis [at] redhat.com>
•
Martin Kyral <mkyral [at] redhat.com>
•
Jakub Prokes <jprokes [at] redhat.com>

Read more:

Leave a Reply

Your email address will not be published. Required fields are marked *