contrib/atf/atf-sh/atf-check.1

   1 .\" Copyright (c) 2008 The NetBSD Foundation, 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
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND
  14 .\" CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
  15 .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
  16 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  17 .\" IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS BE LIABLE FOR ANY
  18 .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
  20 .\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  21 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
  22 .\" IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  23 .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
  24 .\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  25 .Dd October 5, 2014
  26 .Dt ATF-CHECK 1
  27 .Os
  28 .Sh NAME
  29 .Nm atf-check
  30 .Nd executes a command and analyzes its results
  31 .Sh SYNOPSIS
  32 .Nm
  33 .Op Fl s Ar qual:value
  34 .Op Fl o Ar action:arg ...
  35 .Op Fl e Ar action:arg ...
  36 .Op Fl x
  37 .Ar command
  38 .Sh DESCRIPTION
  39 .Nm
  40 executes a given command and analyzes its results, including
  41 exit code, stdout and stderr.
  42 .Pp
  43 .Em Test cases must use
  44 .Em Xr atf-sh 3 Ns ' Ns s
  45 .Em Nm atf_check
  46 .Em builtin function instead of calling this utility directly.
  47 .Pp
  48 In the first synopsis form,
  49 .Nm
  50 will execute the provided command and apply checks specified
  51 by arguments.
  52 By default it will act as if it was run with
  53 .Fl s
  54 .Ar exit:0
  55 .Fl o
  56 .Ar empty
  57 .Fl e
  58 .Ar empty .
  59 Multiple checks for the same output channel are allowed and, if specified,
  60 their results will be combined as a logical and (meaning that the output must
  61 match all the provided checks).
  62 .Pp
  63 In the second synopsis form,
  64 .Nm
  65 will print information about all supported options and their purpose.
  66 .Pp
  67 The following options are available:
  68 .Bl -tag  -width XqualXvalueXX
  69 .It Fl s Ar qual:value
  70 Analyzes termination status.
  71 Must be one of:
  72 .Bl -tag -width signal:<value> -compact
  73 .It Ar exit:<value>
  74 checks that the program exited cleanly and that its exit status is equal to
  75 .Va value .
  76 The exit code can be omitted altogether, in which case any clean exit is
  77 accepted.
  78 .It Ar ignore
  79 ignores the exit check.
  80 .It Ar signal:<value>
  81 checks that the program exited due to a signal and that the signal that
  82 terminated it is
  83 .Va value .
  84 The signal can be specified both as a number or as a name, or it can also
  85 be omitted altogether, in which case any signal is accepted.
  86 .El
  87 .Pp
  88 Most of these checkers can be prefixed by the
  89 .Sq not-
  90 string, which effectively reverses the check.
  91 .It Fl o Ar action:arg
  92 Analyzes standard output.
  93 Must be one of:
  94 .Bl -tag -width inline:<value> -compact
  95 .It Ar empty
  96 checks that stdout is empty
  97 .It Ar ignore
  98 ignores stdout
  99 .It Ar file:<path>
 100 compares stdout with given file
 101 .It Ar inline:<value>
 102 compares stdout with inline value
 103 .It Ar match:<regexp>
 104 looks for a regular expression in stdout
 105 .It Ar save:<path>
 106 saves stdout to given file
 107 .El
 108 .Pp
 109 Most of these checkers can be prefixed by the
 110 .Sq not-
 111 string, which effectively reverses the check.
 112 .It Fl e Ar action:arg
 113 Analyzes standard error (syntax identical to above)
 114 .It Fl x
 115 Executes
 116 .Ar command
 117 as a shell command line, executing it with the system shell defined by
 118 .Va ATF_SHELL .
 119 You should avoid using this flag if at all possible to prevent shell quoting
 120 issues.
 121 .El
 122 .Sh EXIT STATUS
 123 .Nm
 124 exits 0 on success, and other (unspecified) value on failure.
 125 .Sh ENVIRONMENT
 126 .Bl -tag -width ATFXSHELLXX -compact
 127 .It Va ATF_SHELL
 128 Path to the system shell to be used when the
 129 .Fl x
 130 is given to run commands.
 131 .El
 132 .Sh EXAMPLES
 133 The following are sample invocations from within a test case.
 134 Note that we use the
 135 .Nm atf_check
 136 function provided by
 137 .Xr atf-sh 3
 138 instead of executing
 139 .Nm
 140 directly:
 141 .Bd -literal -offset indent
 142 # Exit code 0, nothing on stdout/stderr
 143 atf_check 'true'
 144
 145 # Typical usage if failure is expected
 146 atf_check -s not-exit:0 'false'
 147
 148 # Checking stdout/stderr
 149 echo foobar >expout
 150 atf_check -o file:expout -e inline:"xx\etyy\en" \e
 151     'echo foobar ; printf "xx\etyy\en" >&2'
 152
 153 # Checking for a crash
 154 atf_check -s signal:sigsegv my_program
 155
 156 # Combined checks
 157 atf_check -o match:foo -o not-match:bar echo foo baz
 158 .Ed
 159 .Sh SEE ALSO
 160 .Xr atf-sh 1