1.\" Copyright 2012 Google Inc. 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 September 9, 2012 29.Dt KYUA-DEBUG 1 30.Os 31.Sh NAME 32.Nm 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 that matches a 49single test case; see 50.Xr kyua-test-filters 7 . 51The test case is executed and its result is printed as the last line of the 52output of the tool. 53.Pp 54At the moment, the 55.Nm 56command allows the following aspects of a test case execution to be 57tweaked: 58.Bl -bullet 59.It 60Redirection of the test case's stdout and stderr to the console (the 61default) or to arbitraty files. See the 62.Fl -stdout 63and 64.Fl -stderr 65options below. 66.El 67.Pp 68The following subcommand options are recognized: 69.Bl -tag -width XX 70.It Fl -build-root Ar path 71Specifies the build root in which to find the test programs referenced 72by the Kyuafile, if different from the Kyuafile's directory. See 73.Xr kyua-build-root 7 74for more information. 75.It Fl -kyuafile Ar file , Fl k Ar file 76Specifies the Kyuafile to process. Defaults to 77.Pa Kyuafile 78file in the current directory. 79.It Fl -stderr Ar path 80Specifies the file to which to send the standard error of the test 81program's body. The default is 82.Pa /dev/stderr , 83which is a special that redirects the output to the console. 84.It Fl -stdout Ar path 85Specifies the file to which to send the standard output of the test 86program's body. The default is 87.Pa /dev/stdout , 88which is a special that redirects the output to the console. 89.El 90.Pp 91For example, consider the following Kyua session: 92.Bd -literal -offset indent 93$ kyua test 94kernel/fs:mkdir -> passed 95kernel/fs:rmdir -> failed: Invalid argument 96 971/2 passed (1 failed) 98.Ed 99.Pp 100At this point, we do not have a lot of information regarding the 101failure of the 102.Sq kernel/fs:rmdir 103test. We can run this test through the 104.Nm 105command to inspect its output a bit closer, hoping that the test case is 106kind enough to log its progress: 107.Bd -literal -offset indent 108$ kyua debug kernel/fs:rmdir 109Trying rmdir('foo') 110Trying rmdir(NULL) 111kernel/fs:rmdir -> failed: Invalid argument 112.Ed 113.Pp 114Luckily, the offending test case was printing status lines as it 115progressed, so we could see the last attempted call and we can know match 116the failure message to the problem. 117.Sh EXIT STATUS 118The 119.Nm 120command returns 0 if the test case passes or 1 if the test case fails. 121.Pp 122Additional exit codes may be returned as described in 123.Xr kyua 1 . 124.Sh SEE ALSO 125.Xr kyua 1 , 126.Xr kyua-build-root 7 , 127.Xr kyua-test-filters 7 128