Blame doc/README.tests

Packit Service 360c39
Working with the gfs2-utils test suite
Packit Service 360c39
--------------------------------------
Packit Service 360c39
Packit Service 360c39
Overview
Packit Service 360c39
--------
Packit Service 360c39
The test suite in the tests directory of the gfs2-utils source tree is based on
Packit Service 360c39
the Autotest framework provided by Autoconf. The basic idea is that the
Packit Service 360c39
testsuite.at file is the main source file for the tests, written in m4 and
Packit Service 360c39
generating a bourne shell script called testsuite, which we run with 'make check'.
Packit Service 360c39
Packit Service 360c39
When run, the test suite sources tests/atconfig and tests/atlocal for
Packit Service 360c39
configuration and then runs the whole suite or a specified set of tests,
Packit Service 360c39
depending on options passed to the test suite using TOPTS. For example, to see
Packit Service 360c39
a list of available options, use 'make check TOPTS=-h' and to see a numbered
Packit Service 360c39
list of the available tests, use 'make check TOPTS=-l'.
Packit Service 360c39
Packit Service 360c39
A subset of the available tests can be run using keywords and/or by specifying
Packit Service 360c39
the test ID numbers in TOPTS, e.g. make check TOPTS='-k mkfs 24 25'
Packit Service 360c39
Packit Service 360c39
Test output is captured and, if a test fails, a log is kept in
Packit Service 360c39
tests/testsuite.dir/$n/testsuite.log where $n is the test's ID number. Failed
Packit Service 360c39
tests can be re-run using make check TOPTS='--recheck' although it's better to
Packit Service 360c39
re-run the entire suite after fixing tests as a fix for one test could break
Packit Service 360c39
another.
Packit Service 360c39
Packit Service 360c39
Writing tests
Packit Service 360c39
-------------
Packit Service 360c39
A number of GFS2-specific convenience macros have been defined in testsuite.at
Packit Service 360c39
to make defining new tests quick and easy. Also, some variables have been
Packit Service 360c39
defined in atlocal.in so that full paths to programs do not have to be included
Packit Service 360c39
in each test. Configuration should be specified in atlocal.in as atconfig is
Packit Service 360c39
generated by the configure script and atlocal is generated from atlocal.in at
Packit Service 360c39
build time.
Packit Service 360c39
Packit Service 360c39
To keep the test suite organised, the testsuite.at file sources the actual
Packit Service 360c39
tests from other files, e.g. mkfs.at.
Packit Service 360c39
Packit Service 360c39
A single test, specified as a test group in Autotest terms, follows the form
Packit Service 360c39
Packit Service 360c39
    AT_SETUP([Test title])
Packit Service 360c39
    ...test goes here...
Packit Service 360c39
    AT_CLEANUP
Packit Service 360c39
Packit Service 360c39
so, when adding tests, this is generally all that is required unless the tests
Packit Service 360c39
do not fit into an existing category, in which case AT_BANNER can be used to
Packit Service 360c39
group them, and they can be organised into a new .at file and sourced from
Packit Service 360c39
testsuite.at.
Packit Service 360c39
Packit Service 360c39
As the tests can be run individually, any new tests which require the dummy
Packit Service 360c39
volume $GFS_TGT to be present should call GFS_TGT_REGEN before attempting to
Packit Service 360c39
use it.
Packit Service 360c39
Packit Service 360c39
Documentation for Autotest, including the AT_* macros used to define tests, can
Packit Service 360c39
be found in the autoconf manual at:
Packit Service 360c39
Packit Service 360c39
    http://www.gnu.org/software/autoconf/manual/index.html
Packit Service 360c39
Packit Service 360c39
Generating coverage reports
Packit Service 360c39
---------------------------
Packit Service 360c39
Test coverage instrumentation can be enabled using the --enable-gcov option at
Packit Service 360c39
the configure stage. Once the tools have been built and run with this option
Packit Service 360c39
enabled, coverage data will be written to files in the source directories for
Packit Service 360c39
use by tools such as gcov or lcov. For example, to generate a HTML report of
Packit Service 360c39
testsuite code coverage, using lcov, in a directory named 'coverage':
Packit Service 360c39
Packit Service 360c39
    ./autogen.sh
Packit Service 360c39
    ./configure --enable-gcov
Packit Service 360c39
    make check
Packit Service 360c39
    lcov --directory . -c -o gfs2-utils.info
Packit Service 360c39
    genhtml -o coverage gfs2-utils.info