Working with the gfs2-utils test suite

--------------------------------------

Overview

--------

The test suite in the tests directory of the gfs2-utils source tree is based on

the Autotest framework provided by Autoconf. The basic idea is that the

testsuite.at file is the main source file for the tests, written in m4 and

generating a bourne shell script called testsuite, which we run with 'make check'.

When run, the test suite sources tests/atconfig and tests/atlocal for

configuration and then runs the whole suite or a specified set of tests,

depending on options passed to the test suite using TOPTS. For example, to see

a list of available options, use 'make check TOPTS=-h' and to see a numbered

list of the available tests, use 'make check TOPTS=-l'.

A subset of the available tests can be run using keywords and/or by specifying

the test ID numbers in TOPTS, e.g. make check TOPTS='-k mkfs 24 25'

Test output is captured and, if a test fails, a log is kept in

tests/testsuite.dir/$n/testsuite.log where $n is the test's ID number. Failed

tests can be re-run using make check TOPTS='--recheck' although it's better to

re-run the entire suite after fixing tests as a fix for one test could break

another.

Writing tests

-------------

A number of GFS2-specific convenience macros have been defined in testsuite.at

to make defining new tests quick and easy. Also, some variables have been

defined in atlocal.in so that full paths to programs do not have to be included

in each test. Configuration should be specified in atlocal.in as atconfig is

generated by the configure script and atlocal is generated from atlocal.in at

build time.

To keep the test suite organised, the testsuite.at file sources the actual

tests from other files, e.g. mkfs.at.

A single test, specified as a test group in Autotest terms, follows the form

    AT_SETUP([Test title])

    ...test goes here...

    AT_CLEANUP

so, when adding tests, this is generally all that is required unless the tests

do not fit into an existing category, in which case AT_BANNER can be used to

group them, and they can be organised into a new .at file and sourced from

testsuite.at.

As the tests can be run individually, any new tests which require the dummy

volume $GFS_TGT to be present should call GFS_TGT_REGEN before attempting to

use it.

Documentation for Autotest, including the AT_* macros used to define tests, can

be found in the autoconf manual at:

    http://www.gnu.org/software/autoconf/manual/index.html

Generating coverage reports

---------------------------

Test coverage instrumentation can be enabled using the --enable-gcov option at

the configure stage. Once the tools have been built and run with this option

enabled, coverage data will be written to files in the source directories for

use by tools such as gcov or lcov. For example, to generate a HTML report of

testsuite code coverage, using lcov, in a directory named 'coverage':

    ./autogen.sh

    ./configure --enable-gcov

    make check

    lcov --directory . -c -o gfs2-utils.info

    genhtml -o coverage gfs2-utils.info