KYUA-DEBUG(1)

NAME
kyua debug - Executes a single test case with facilities for debugging

SYNOPSIS
kyua debug [--build-root path] [--kyuafile file] [--pause-before-cleanup-upon-fail] [--pause-before-cleanup] [--stdout path] [--stderr path] test_case

DESCRIPTION
The kyua debug command provides a mechanism to execute a single test case bypassing some of the Kyua infrastructure and allowing the user to poke into the execution behavior of the test.

The test case to run is selected by providing a test filter, described below in Test filters, that matches a single test case. The test case is executed and its result is printed as the last line of the output of the tool.

The test executed by kyua debug is run under a controlled environment as described in Test isolation.

At the moment, the kyua debug command allows the following aspects of a test case execution to be tweaked:

•   Redirection of the test case's stdout and stderr to the console (the default) or to arbitrary files. See the --stdout and --stderr options below.

The following subcommand options are recognized:

--build-root path
    Specifies the build root in which to find the test programs referenced by the Kyuafile, if different from the Kyuafile's directory. See Build directories below for more information.

--kyuafile file, -k file
    Specifies the Kyuafile to process. Defaults to Kyuafile file in the current directory.

--pause-before-cleanup-upon-fail, -p
    Causes Kyua to pause right before the test cleanup routine is invoked if the test fails. When paused, Kyua waits for input on stdin, and any key press resumes execution.

    This can be useful for debugging system or end-to-end tests which alter the system by creating artifacts such as files, network interfaces, routing entries, firewall configuration, containers, etc. This flag makes it possible to preserve such artifacts immediately after a test failure, simplifying debugging. Otherwise, these artifacts would be removed by the test cleanup routine or by Kyua built-in cleanup mechanism.

--pause-before-cleanup
    The unconditional variant of the previous option. This can be helpful for reproducing the infrastructure or fixture of a passing test for further development or additional analysis.

--stderr path
    Specifies the file to which to send the standard error of the test program's body. The default is /dev/stderr, which is a special character device that redirects the output to standard error on the console.

--stdout path
    Specifies the file to which to send the standard output of the test program's body. The default is /dev/stdout, which is a special character device that redirects the output to standard output on the console.

For example, consider the following Kyua session:

    $ kyua test
    kernel/fs:mkdir  ->  passed
    kernel/fs:rmdir  ->  failed: Invalid argument
    1/2 passed (1 failed)

At this point, we do not have a lot of information regarding the failure of the ‘kernel/fs:rmdir’ test. We can run this test through the kyua debug command to inspect its output a bit closer, hoping that the test case is kind enough to log its progress:

    $ kyua debug kernel/fs:rmdir
    Trying rmdir('foo')
    Trying rmdir(NULL)
    kernel/fs:rmdir  ->  failed: Invalid argument

Luckily, the offending test case was printing status lines as it progressed, so we could see the last attempted call and we can know match the failure message to the problem.

  Build directories
__include__ build-root.mdoc COMMAND=debug

  Test filters
__include__ test-filters.mdoc

  Test isolation
__include__ test-isolation.mdoc

EXIT STATUS
The kyua debug command returns 0 if the test case passes or 1 if the test case fails.

Additional exit codes may be returned as described in kyua(1).

SEE ALSO
kyua(1), kyuafile(5)