contrib/kyua/doc/kyua-test.1.in

   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-TEST 1
  30 .Os
  31 .Sh NAME
  32 .Nm "kyua test"
  33 .Nd Runs tests
  34 .Sh SYNOPSIS
  35 .Nm
  36 .Op Fl -build-root Ar path
  37 .Op Fl -kyuafile Ar file
  38 .Op Fl -results-file Ar file
  39 .Op Ar test_filter1 .. test_filterN
  40 .Sh DESCRIPTION
  41 The
  42 .Nm
  43 command loads a test suite definition from a
  44 .Xr kyuafile 5 ,
  45 runs the tests defined in it, and records the results into a new results
  46 file.
  47 By default, all tests in the test suite are executed but the optional
  48 arguments to
  49 .Nm
  50 can be used to select which test programs or test cases to run.
  51 These are filters and are described below in
  52 .Sx Test filters .
  53 .Pp
  54 Every test executed by
  55 .Nm
  56 is run under a controlled environment as described in
  57 .Sx Test isolation .
  58 .Pp
  59 The following subcommand options are recognized:
  60 .Bl -tag -width XX
  61 .It Fl -build-root Ar path
  62 Specifies the build root in which to find the test programs referenced by
  63 the Kyuafile, if different from the Kyuafile's directory.
  64 See
  65 .Sx Build directories
  66 below for more information.
  67 .It Fl -kyuafile Ar path , Fl k Ar path
  68 Specifies the Kyuafile to process.
  69 Defaults to a
  70 .Pa Kyuafile
  71 file in the current directory.
  72 .It Fl -results-file Ar path , Fl s Ar path
  73 __include__ results-file-flag-write.mdoc
  74 .El
  75 .Pp
  76 You can later inspect the results of the test run in more detail by using
  77 .Xr kyua-report 1
  78 or you can execute a single test case with debugging functionality by using
  79 .Xr kyua-debug 1 .
  80 .Ss Build directories
  81 __include__ build-root.mdoc COMMAND=test
  82 .Ss Results files
  83 __include__ results-files.mdoc
  84 .Ss Test filters
  85 __include__ test-filters.mdoc
  86 .Ss Test isolation
  87 __include__ test-isolation.mdoc
  88 .Sh EXIT STATUS
  89 The
  90 .Nm
  91 command returns 0 if all executed test cases pass or 1 if any of the
  92 executed test cases fails or if any of the given test case filters does not
  93 match any test case.
  94 .Pp
  95 Additional exit codes may be returned as described in
  96 .Xr kyua 1 .
  97 .Sh EXAMPLES
  98 __include__ results-files-report-example.mdoc REPORT_COMMAND=report
  99 .Sh SEE ALSO
 100 .Xr kyua 1 ,
 101 .Xr kyua-report 1 ,
 102 .Xr kyuafile 5