16.2 Writing `testsuite.at'

The `testsuite.at' is a Bourne shell script making use of special Autotest M4 macros. It often contains a call to AT_INIT nears its beginning followed by one call to m4_include per source file for tests. Each such included file, or the remainder of `testsuite.at' if include files are not used, contain a sequence of test groups. Each test group begins with one call to AT_SETUP, it contains an arbitrary number of shell commands or calls to AT_CHECK, and it completes with one call to AT_CLEANUP.

Macro: AT_INIT (program)

Initialize Autotest. This macro accepts a single argument, which is the file name of the executable program to use for checking version. At the time the validation suite gets executed, the program search path should be already preset so the proper executable will be selected. This is usually guaranteed through some `Makefile' magic.

program is then used to check that the test suite is ready to be run (program was found), and corresponds to the current version of the package (`program --version' is run and checked against the package version).

Macro: AT_SETUP (test-group-name)

This macro starts a group of related tests, all to be executed in the same subshell. It accepts a single argument, which holds a few words (no more than about 30 or 40 characters) quickly describing the purpose of the test group being started.

Macro: AT_CLEANUP ([generated-files])

This macro completes a group of related tests. It accepts a single argument, which is a white separated list of files which have been created within the test group. It has the effect of recursively removing those listed files. There is no need to list `stdout', `stderr', nor files created with AT_DATA.

Macro: AT_DATA (file, contents)

Initialize an input data file with given contents. Of course, the contents have to be properly quoted between square brackets to protect against included commas or spurious m4 expansion. The contents ought to end with an end of line.

Macro: AT_CHECK (commands, [status = ``0']', [stdout], [stderr])

Execute a test by performing given shell commands. These commands should normally exit with status, while producing expected stdout and stderr contents. If commands exit with status 77, then the whole test group is skipped.

The commands must not redirect the standard output, nor the standard error.

If status, or stdout, or stderr is `ignore', then the corresponding value is not checked.

The special value `expout' for stdout means the expected output of the commands is the content of the file `expout'. If stdout is `stdout', then the standard output of the commands is available for further tests in the file `stdout'. Similarly for stderr with `expout' and `stderr'.