Minix Man Pages

home | help
KYUAFILE(5)                 BSD File Formats Manual                KYUAFILE(5)

NAME
     Kyuafile -- Test suite description files

SYNOPSIS
     atf_test_program(string name, [string test_suite], [string metadata]);

     include(string path);

     plain_test_program(string name, [string test_suite], [string metadata]);

     syntax(int version);

     test_suite(string name);

DESCRIPTION
     A test suite is a collection of test programs and is represented by a
     hierarchical layout of test binaries on the file system.  Any subtree of
     the file system can represent a test suite, provided that it includes one
     or more Kyuafiles, which are the test suite definition files.

     A Kyuafile is a Lua script whose purpose is to describe the structure of
     the test suite it belongs to.  To do so, the script has access to a
     collection of special functions provided by kyua(1).

     A typical Kyuafile will look similar to this:

           syntax(2)

           test_suite('first')

           -- Declare the test programs that are in this directory.
           atf_test_program{name='foo_test'}
           atf_test_program{name='bar_test', test_suite='second'}
           plain_test_program{name='legacy_test'}
           plain_test_program{name='legacy2_test', allowed_architectures='amd64 i386',
                              required_files='/bin/ls', timeout=30}

           -- Recurse into any subdirectories that may have other tests.
           include('dir1/Kyuafile')
           include('dir2/Kyuafile')

   File versioning
     Every Kyuafile file starts with a call to syntax(int version).  This call
     determines the specific schema used by the file so that future backwards-
     incompatible modifications to the file can be introduced.

     Any new Kyuafile file should set version to '2'.

   Test suite definition
     Every Kyuafile should define the name of the test suite it belongs to by
     calling the test_suite() function at the very beginning.  Individual test
     programs can override this value in their definition, but the most common
     style is to list a single test suite name for the whole file.

     The purpose of the test suite name definition is to tell kyua(1) scoping
     for the run-time configuration variables that these programs accept.

   Test program registration
     A Kyuafile can register test programs by means of a variety of
     *_test_program() functions, all of which take the name of a test program
     and a set of optional metadata properties that describe such test
     program.

     The test programs to be registered must live in the current directory; in
     other words, the various *_test_program() calls cannot reference test
     programs in other directories.  The rationale for this is to force all
     Kyuafile files to be self-contained, and to simplify their internal
     representation.

     ATF-based test programs (those that implement the kyua-atf-interface(7)
     interface) can be registered with the atf_test_program() table
     constructor.  This function takes the name of the test program, an
     optional test_suite name that overrides the global test suite name and a
     collection of optional metadata settings for all the test cases in the
     test program.  Any metadata properties defined by the test cases
     themselves override the metadata values defined here.

     Plain test programs (those that implement the kyua-plain-interface(7)
     interface) can be registered with the plain_test_program() table
     constructor.  This function takes the name of the test program an
     optional test_suite name that overrides the global test suite name and a
     collection of optional metadata settings for the test program.

     Please see kyua-tester-list(5) for the list of metadata properties that
     can be given to test programs.  All the properties that can be given to a
     test case can also be given to a test program.

   Recursion
     To reference test programs in another subdirectory, a different Kyuafile
     must be created in that directory and it must be included into the
     original Kyuafile by means of the include() function.

     Note that each file is processed in its own Lua environment: there is no
     mechanism to pass state from one file to the other.  The reason for this
     is that there is no such thing as a "top-level" Kyuafile in a test suite:
     the user has to be able to run the test suite from any directory in a
     given hierarchy, and this execution must not depend on files that live in
     parent directories.

   Top-level Kyuafile
     Every system has a top directory into which test suites get installed.
     The default is /usr/tests.  Within this directory live test suites, each
     of which is in an independent subdirectory.  Each subdirectory can be
     provided separately by independent third-party packages.

     Kyua allows running all the installed test suites at once in order to
     provide comprehensive cross-component reports.  In order to do this,
     there is a special file in the top directory that knows how to inspect
     the subdirectories in search for other Kyuafiles and include them.

     The FILES section includes more details on where this file lives.

FILES
     /usr/tests/Kyuafile.
         Top-level Kyuafile for the current system.

     /usr/share/examples/kyua-cli/Kyuafile.top.
         Sample file to serve as a top-level Kyuafile.

SEE ALSO
     kyua(1)

BSD                            February 9, 2013                            BSD
NAME | SYNOPSIS | DESCRIPTION | FILES | SEE ALSO