1 .\" Copyright 2012 The Kyua Authors.
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions are
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.
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.
33 .Nd Executes a single test case with facilities for debugging
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
44 command provides a mechanism to execute a single test case bypassing some
45 of the Kyua infrastructure and allowing the user to poke into the execution
48 The test case to run is selected by providing a test filter, described below in
50 that matches a single test case.
51 The test case is executed and its result is printed as the last line of the
56 is run under a controlled environment as described in
61 command allows the following aspects of a test case execution to be
65 Redirection of the test case's stdout and stderr to the console (the
66 default) or to arbitrary files.
74 The following subcommand options are recognized:
76 .It Fl -build-root Ar path
77 Specifies the build root in which to find the test programs referenced
78 by the Kyuafile, if different from the Kyuafile's directory.
81 below for more information.
82 .It Fl -kyuafile Ar file , Fl k Ar file
83 Specifies the Kyuafile to process.
86 file in the current directory.
87 .It Fl -stderr Ar path
88 Specifies the file to which to send the standard error of the test
92 which is a special character device that redirects the output to
93 standard error on the console.
94 .It Fl -stdout Ar path
95 Specifies the file to which to send the standard output of the test
99 which is a special character device that redirects the output to
100 standard output on the console.
103 For example, consider the following Kyua session:
104 .Bd -literal -offset indent
106 kernel/fs:mkdir -> passed
107 kernel/fs:rmdir -> failed: Invalid argument
109 1/2 passed (1 failed)
112 At this point, we do not have a lot of information regarding the
116 We can run this test through the
118 command to inspect its output a bit closer, hoping that the test case is
119 kind enough to log its progress:
120 .Bd -literal -offset indent
121 $ kyua debug kernel/fs:rmdir
124 kernel/fs:rmdir -> failed: Invalid argument
127 Luckily, the offending test case was printing status lines as it
128 progressed, so we could see the last attempted call and we can know match
129 the failure message to the problem.
130 .Ss Build directories
131 __include__ build-root.mdoc COMMAND=debug
133 __include__ test-filters.mdoc
135 __include__ test-isolation.mdoc
139 command returns 0 if the test case passes or 1 if the test case fails.
141 Additional exit codes may be returned as described in