Manual Pages  — KYUA

kyua – Testing framework for infrastructure software

SYNOPSIS DESCRIPTION Overview Logging Bug reporting ENVIRONMENT FILES EXIT STATUS SEE ALSO AUTHORS

kyua [--config file] [--logfile file] [--loglevel level] [--variable name=value] command [command_options] [command_arguments]

As can be observed in the synopsis, the interface of kyua implements a common subcommand-based interface. The arguments to the tool specify, in this order: a set of common options that all the commands accept, a required command name that specifies what kyua should do, and a set of possibly-optional command_options and command_arguments that are specific to the chosen command.

The following options are recognized by all the commands. Keep in mind that these must always be specified before the command name.

--config path , -c path
	Specifies the configuration file to process, which must be in the format described in kyua.conf(5). The special value 'none' explicitly disables the loading of any configuration file. Defaults to ~/.kyua/kyua.conf if it exists, otherwise to /etc/kyua/kyua.conf if it exists, or else to 'none'.
--logfile path
	Specifies the location of the file to which kyua will log run time events useful for postmortem debugging. The default depends on different environment variables as described in Logging, but typically the file will be stored within the user's home directory.
--loglevel level
	Specifies the maximum logging level to record in the log file. See Logging for more details. The default is 'info'.
--variable name=value , -v name=value
	Sets the name configuration variable to value. The values set through this option have preference over the values set in the configuration file. The specified variable can either be a builtin variable or a test-suite specific variable. See kyua.conf(5) for more details.

The following commands are generic and do not have any relation to the execution of tests or the inspection of their results:

about	Shows general program information. See kyua-about(1).
config	Inspects the values of the configuration variables. See kyua-config(1).
db-exec	Executes an arbitrary SQL statement on a results file and prints the resulting table. See kyua-db-exec(1).
help	Shows usage information. See kyua-help(1).

The following commands are used to generate reports based on the data previously recorded in a results file:

report	Generates a plaintext report. Combined with its --verbose flag and the ability to only display specific test cases, this command can also be used to debug test failures post-facto on the console. See kyua-report(1).
report-html	Generates an HTML report. See kyua-report-html(1).
report-junit	Generates a JUnit report. See kyua-report-junit(1).

The following commands are used to interact with a test suite:

debug	Executes a single test case in a controlled environment for debugging purposes. See kyua-debug(1).
list	Lists test cases defined in a test suite by a kyuafile(5) and, optionally, displays their metadata. See kyua-list(1).
test	Runs tests defined in a test suite by a kyuafile(5). See kyua-test(1).

kyua has a logging facility that collects all kinds of events at run time. These events are always logged to a file so that the log is available when it is most needed: right after a non-reproducible problem happens. The only way to disable logging is by sending the log to /dev/null.

The location of the log file can be manually specified with the --logfile option, which applies to all commands. If no file is explicitly specified, the location of the log files is chosen in this order:

1. ${HOME}/.kyua/logs/ if HOME is defined.
2. ${TMPDIR}/ if TMPDIR is defined.
3. /tmp/.

And the default naming scheme of the log files is: '<progname>.<timestamp>.log'.

The messages stored in the log file have a level (or severity) attached to them. These are:

error	Fatal error messages. The program generally terminates after these, either in a clean manner or by crashing.
warning	Non-fatal error messages. These generally report a condition that must be addressed but the application can continue to run.
info	Informational messages. These tell the user what the program was doing at a general level of operation.
debug	Detailed informational messages. These are often useful when debugging problems in the application, as they contain lots of internal details.

The default log level is 'info' unless explicitly overridden with --loglevel.

The log file is a plain text file containing one line per log record. The format of each line is as follows:

timestamp entry_type pid file:line: message

entry_type can be one of: 'E' for an error, 'W' for a warning, 'I' for an informational message and 'D' for a debug message.

The following variables are recognized and can be freely tuned by the end user:

COLUMNS
	The width of the screen, in number of characters. kyua uses this to wrap long lines. If not present, the width of the screen is determined from the terminal stdout is connected to, and, if the guessing fails, this defaults to infinity.
HOME
	Path to the user's home directory. kyua uses this location to determine paths to configuration files and default log files.
TMPDIR
	Path to the system-wide temporary directory. kyua uses this location to place the work directory of test cases, among other things. The default value of this variable depends on the operating system. In general, it is /tmp.

The following variables are also recognized, but you should not need to set them during normal operation. They are only provided to override the value of built-in values, which is useful when testing kyua itself:

KYUA_CONFDIR
	Path to the system-wide configuration files for kyua. Defaults to /etc/kyua.
KYUA_DOCDIR
	Path to the location of installed documentation. Defaults to /usr/share/doc/kyua.
KYUA_MISCDIR
	Path to the location of the installed miscellaneous scripts and data files provided by kyua. Defaults to /usr/share/kyua/misc.
KYUA_STOREDIR
	Path to the location of the installed store support files; e.g., the directory containing the SQL database schema. Defaults to /usr/share/kyua/store.

~/.kyua/store/
	Default location for the results files.
~/.kyua/kyua.conf
	User-specific configuration file.
~/.kyua/logs/
	Default location for the collected log files.
/etc/kyua/kyua.conf
	System-wide configuration file.

kyua returns 0 on success, 1 on a controlled error condition in the given subcommand, 2 on a general unexpected error and 3 on a usage error.

The documentation of the subcommands in the corresponding manual pages only details the difference between a successful exit (0) and the detection of a controlled error (1). Even though when those manual pages do not describe any other exit statuses, codes above 1 can be returned.

For more details on the people that made kyua possible and the license terms, run:

$ kyua about