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