1.\" Copyright 2012 The Kyua Authors. 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions are 6.\" met: 7.\" 8.\" * Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" * Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" * Neither the name of Google Inc. nor the names of its contributors 14.\" may be used to endorse or promote products derived from this software 15.\" without specific prior written permission. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 18.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 19.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 20.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 21.\" OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 22.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 23.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 24.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 25.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 26.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 27.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 28.Dd October 13, 2014 29.Dt KYUA-DEBUG 1 30.Os 31.Sh NAME 32.Nm "kyua debug" 33.Nd Executes a single test case with facilities for debugging 34.Sh SYNOPSIS 35.Nm 36.Op Fl -build-root Ar path 37.Op Fl -kyuafile Ar file 38.Op Fl -stdout Ar path 39.Op Fl -stderr Ar path 40.Ar test_case 41.Sh DESCRIPTION 42The 43.Nm 44command provides a mechanism to execute a single test case bypassing some 45of the Kyua infrastructure and allowing the user to poke into the execution 46behavior of the test. 47.Pp 48The test case to run is selected by providing a test filter, described below in 49.Sx Test filters , 50that matches a single test case. 51The test case is executed and its result is printed as the last line of the 52output of the tool. 53.Pp 54The test executed by 55.Nm 56is run under a controlled environment as described in 57.Sx Test isolation . 58.Pp 59At the moment, the 60.Nm 61command allows the following aspects of a test case execution to be 62tweaked: 63.Bl -bullet 64.It 65Redirection of the test case's stdout and stderr to the console (the 66default) or to arbitrary files. 67See the 68.Fl -stdout 69and 70.Fl -stderr 71options below. 72.El 73.Pp 74The following subcommand options are recognized: 75.Bl -tag -width XX 76.It Fl -build-root Ar path 77Specifies the build root in which to find the test programs referenced 78by the Kyuafile, if different from the Kyuafile's directory. 79See 80.Sx Build directories 81below for more information. 82.It Fl -kyuafile Ar file , Fl k Ar file 83Specifies the Kyuafile to process. 84Defaults to 85.Pa Kyuafile 86file in the current directory. 87.It Fl -stderr Ar path 88Specifies the file to which to send the standard error of the test 89program's body. 90The default is 91.Pa /dev/stderr , 92which is a special character device that redirects the output to 93standard error on the console. 94.It Fl -stdout Ar path 95Specifies the file to which to send the standard output of the test 96program's body. 97The default is 98.Pa /dev/stdout , 99which is a special character device that redirects the output to 100standard output on the console. 101.El 102.Pp 103For example, consider the following Kyua session: 104.Bd -literal -offset indent 105$ kyua test 106kernel/fs:mkdir -> passed 107kernel/fs:rmdir -> failed: Invalid argument 108 1091/2 passed (1 failed) 110.Ed 111.Pp 112At this point, we do not have a lot of information regarding the 113failure of the 114.Sq kernel/fs:rmdir 115test. 116We can run this test through the 117.Nm 118command to inspect its output a bit closer, hoping that the test case is 119kind enough to log its progress: 120.Bd -literal -offset indent 121$ kyua debug kernel/fs:rmdir 122Trying rmdir('foo') 123Trying rmdir(NULL) 124kernel/fs:rmdir -> failed: Invalid argument 125.Ed 126.Pp 127Luckily, the offending test case was printing status lines as it 128progressed, so we could see the last attempted call and we can know match 129the failure message to the problem. 130.Ss Build directories 131__include__ build-root.mdoc COMMAND=debug 132.Ss Test filters 133__include__ test-filters.mdoc 134.Ss Test isolation 135__include__ test-isolation.mdoc 136.Sh EXIT STATUS 137The 138.Nm 139command returns 0 if the test case passes or 1 if the test case fails. 140.Pp 141Additional exit codes may be returned as described in 142.Xr kyua 1 . 143.Sh SEE ALSO 144.Xr kyua 1 , 145.Xr kyuafile 5 146