*** UNIX MANUAL PAGE BROWSER ***

KYUA-TESTER(1) FreeBSD General Commands Manual KYUA-TESTER(1) NAME kyua-tester - Scriptable interface to interact with test programs SYNOPSIS kyua-tester [-g gid] [-t timeout] [-u uid] list test_program kyua-tester [-g gid] [-t timeout] [-u uid] test [-v var=value] test_program test_case result_file DESCRIPTION This generic manual page does not correspond to any specific binary. It describes the generic command-line interface provided by all Kyua testers shipped by the `kyua-testers' package, which all have names of the form kyua-INTERFACE-NAME-tester. The main goal of a kyua-tester is to provide a scriptable interface to run a single test case of a single test program in a generic manner. The specific implementation of how to do this is up to the tester, as each kyua-tester binary implements a specific test interface. The following binaries are shipped with the `kyua-testers' package: kyua-atf-tester(1) An implementation of kyua-tester that wraps tests that follow the kyua-atf-interface(7) interface. kyua-plain-tester(1) An implementation of kyua-tester that wraps tests that follow the kyua-plain-interface(7) interface. kyua(1) uses the various kyua-tester binaries to execute tests that implement diverse interfaces, without having to know about any of its specifics. It is possible for other packages to provide new testers that implement other interfaces as long as the tester's command line complies to what is described in this manual page. A kyua-tester implements a typical command-line interface based on subcommands. The tool takes a set of generic options first, a subcommand name, a set of any options accepted by such subcommand, and a set of arguments to the subcommand. The following options apply to all subcommands: -g gid GID of the user to switch to before running the test case. Defaults to the current GID. -t timeout Seconds to allow the test program to run before killing it. Defaults to 60. -u uid UID of the user to switch to before running the test case. Defaults to the current UID. Killing the tester should always be a safe operation, resulting in the subsequent termination of the test program being run and the cleanup of any used resources. Workflow The way kyua(1) uses the testers to interact with individual test cases is the following: 1. For every test program listed in a kyuafile(5), execute the `list' subcommand of the kyua-tester that matches the interface name in the test program description. 2. kyua(1) collects the test cases returned in the previous step and checks if they are runnable according to their metadata. 3. For every test case collected from the previous steps, execute the `test' subcommand of the same kyua-tester used in the test case listing. 4. Reinterpret the generic test result and record it as necessary. The list subcommand The `list' subcommand extracts the list of test cases that are part of the given test program in a machine-parseable format. The test program should be provided as an absolute pathname. The format of the output is described in kyua-tester-list(5). The test subcommand The `test' subcommand executes a single test case of a test program in a controlled manner, which means that it is placed in its own subprocess and its own work directory so that side-effects during execution are minimized. If the test is executed successfully, the result_file is created following the format described in kyua-tester-result(5). If the test crashes halfway through and dumps core, kyua-tester will attempt to gather a stacktrace and print it as part of the test's output. The following options are specific to the test command: -v var=name Passes a configuration variable to the test case. The following configuration variables have special meaning: unprivileged-user The name (not UID) of an unprivileged user that the test can use for its own purposes. ENVIRONMENT The following variables are recognized and can be freely tuned by the end user: TMPDIR Path to the system-wide temporary directory. kyua-tester uses this location to place the work directory of test cases. The default value is /tmp. EXIT STATUS kyua-tester returns the following exit codes: 0 The tester ran correctly and the test passed. 1 The tester ran correctly, but the test failed. 2 The tester failed. The result of the test itself is irrelevant. 3 The user invoked the tester incorrectly. SEE ALSO kyua-atf-tester(1), kyua-plain-tester(1) FreeBSD 14.1-RELEASE-p8 December 26, 2012 FreeBSD 14.1-RELEASE-p8