# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#
# Name: beakerlib.sh - part of the BeakerLib project
# Description: The main BeakerLib script
#
# Author: Petr Muller <pmuller@redhat.com>
# Author: Ondrej Hudlicky <ohudlick@redhat.com>
# Author: Jan Hutar <jhutar@redhat.com>
# Author: Petr Splichal <psplicha@redhat.com>
# Author: Ales Zelinka <azelinka@redhat.com>
# Author: Dalibor Pospisil <dapospis@redhat.com>
# Author: Martin Kyral <mkyral@redhat.com>
# Author: Jakub Prokes <jprokes@redhat.com>
#
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#
# Copyright (c) 2008-2012 Red Hat, Inc. All rights reserved.
#
# This copyrighted material is made available to anyone wishing
# to use, modify, copy, or redistribute it subject to the terms
# and conditions of the GNU General Public License version 2.
#
# This program is distributed in the hope that it will be
# useful, but WITHOUT ANY WARRANTY; without even the implied
# warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
# PURPOSE. See the GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public
# License along with this program; if not, write to the Free
# Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
# Boston, MA 02110-1301, USA.
#
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
: <<'=cut'
=pod
=for comment beakerlib-manual-header
=head1 NAME
BeakerLib - a shell-level integration testing library
=head1 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:
=over
=item
B<Journal> - uniform logging mechanism (logs & results saved in flexible XML
format, easy to compare results & generate reports)
=item
B<Phases> - logical grouping of test actions, clear separation of setup / test
/ cleanup (preventing false fails)
=item
B<Asserts> - common checks affecting the overall results of the individual
phases (checking for exit codes, file existence & content...)
=item
B<Helpers> - convenience functions for common operations such as managing
services, backup & restore
=back
The main script sets the C<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.
=cut
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# beakerlib-manual-include
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:<<'=cut'
=pod
=for comment beakerlib-manual-footer
=head1 EXAMPLES
=head2 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
=head2 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@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 C<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.
=head1 BKRDOC
=over
=item 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.
=item 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.
=item Bkrdoc project page
https://github.com/rh-lab-q/bkrdoc
=back
=head1 LINKS
=over
=item Project Page
https://github.com/beakerlib/beakerlib
=item Manual
https://github.com/beakerlib/beakerlib/wiki/man
=item Issues list
https://github.com/beakerlib/beakerlib/issues
=item Reporting issues
https://github.com/beakerlib/beakerlib/issues/new
=back
=head1 AUTHORS
=over
=item *
Petr Muller <pmuller@redhat.com>
=item *
Ondrej Hudlicky <ohudlick@redhat.com>
=item *
Jan Hutar <jhutar@redhat.com>
=item *
Petr Splichal <psplicha@redhat.com>
=item *
Ales Zelinka <azelinka@redhat.com>
=item *
Dalibor Pospisil <dapospis@redhat.com>
=item *
Martin Kyral <mkyral@redhat.com>
=item *
Jakub Prokes <jprokes@redhat.com>
=item *
Jakub Heger <jheger@redhat.com>
=back
=cut
if set -o | grep posix | grep on ; then
set +o posix
export POSIXFIXED="YES"
else
export POSIXFIXED="NO"
fi
export __INTERNAL_PERSISTENT_TMP=/var/tmp
# export COBBLER_SERVER for the usage in tests
test -f /etc/profile.d/cobbler.sh && . /etc/profile.d/cobbler.sh
set -e
export BEAKERLIB=${BEAKERLIB:-"/usr/share/beakerlib"}
. $BEAKERLIB/storage.sh
. $BEAKERLIB/infrastructure.sh
. $BEAKERLIB/journal.sh
. $BEAKERLIB/libraries.sh
. $BEAKERLIB/logging.sh
. $BEAKERLIB/rpms.sh
. $BEAKERLIB/testing.sh
. $BEAKERLIB/analyze.sh
. $BEAKERLIB/performance.sh
. $BEAKERLIB/virtualX.sh
. $BEAKERLIB/synchronisation.sh
if [ -d $BEAKERLIB/plugins/ ] ; then
for __INTERNAL_beakerlib_source_plugin in $BEAKERLIB/plugins/*.sh ; do
. $__INTERNAL_beakerlib_source_plugin
done
fi
set +e