external/bsd/atf/dist/atf-c++/atf-c++-api.3

   1 .\"
   2 .\" Automated Testing Framework (atf)
   3 .\"
   4 .\" Copyright (c) 2008 The NetBSD Foundation, Inc.
   5 .\" All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND
  17 .\" CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
  18 .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
  19 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  20 .\" IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS BE LIABLE FOR ANY
  21 .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
  23 .\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  24 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
  25 .\" IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  26 .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
  27 .\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  28 .\"
  29 .Dd April 26, 2008
  30 .Dt ATF-C++-API 3
  31 .Os
  32 .Sh NAME
  33 .Nm ATF_ADD_TEST_CASE ,
  34 .Nm ATF_CHECK ,
  35 .Nm ATF_CHECK_EQUAL ,
  36 .Nm ATF_CHECK_THROW ,
  37 .Nm ATF_FAIL ,
  38 .Nm ATF_INIT_TEST_CASES ,
  39 .Nm ATF_PASS ,
  40 .Nm ATF_SKIP ,
  41 .Nm ATF_TEST_CASE ,
  42 .Nm ATF_TEST_CASE_BODY ,
  43 .Nm ATF_TEST_CASE_CLEANUP ,
  44 .Nm ATF_TEST_CASE_HEAD ,
  45 .Nm ATF_TEST_CASE_WITH_CLEANUP
  46 .Nd C++ API to write ATF-based test programs
  47 .Sh SYNOPSIS
  48 .In atf-c++.hpp
  49 .Fn ATF_ADD_TEST_CASE "tcs" "name"
  50 .Fn ATF_CHECK "expression"
  51 .Fn ATF_CHECK_EQUAL "expression_1" "expression_2"
  52 .Fn ATF_CHECK_THROW "statement_1" "expected_exception"
  53 .Fn ATF_FAIL "reason"
  54 .Fn ATF_INIT_TEST_CASES "tcs"
  55 .Fn ATF_PASS
  56 .Fn ATF_SKIP "reason"
  57 .Fn ATF_TEST_CASE "name"
  58 .Fn ATF_TEST_CASE_BODY "name"
  59 .Fn ATF_TEST_CASE_CLEANUP "name"
  60 .Fn ATF_TEST_CASE_HEAD "name"
  61 .Fn ATF_TEST_CASE_WITH_CLEANUP "name"
  62 .Sh DESCRIPTION
  63 ATF provides a mostly-macro-based programming interface to implement test
  64 programs in C or C++.
  65 This interface is backed by a C++ implementation, but this fact is
  66 hidden from the developer as much as possible through the use of
  67 macros to simplify programming.
  68 However, the use of C++ is not hidden everywhere and while you can
  69 implement test cases without knowing anything at all about the object model
  70 underneath the provided calls, you might need some minimum notions of the
  71 language in very specific circumstances.
  72 .Pp
  73 C++-based test programs always follow this template:
  74 .Bd -literal -offset indent
  75 extern "C" {
  76 .Ns ... C-specific includes go here ...
  77 }
  78
  79 .Ns ... C++-specific includes go here ...
  80
  81 #include <atf-c++.hpp>
  82
  83 ATF_TEST_CASE(tc1);
  84 ATF_TEST_CASE_HEAD(tc1)
  85 {
  86     ... first test case's header ...
  87 }
  88 ATF_TEST_CASE_BODY(tc1)
  89 {
  90     ... first test case's body ...
  91 }
  92
  93 ATF_TEST_CASE_WITH_CLEANUP(tc2);
  94 ATF_TEST_CASE_HEAD(tc2)
  95 {
  96     ... second test case's header ...
  97 }
  98 ATF_TEST_CASE_BODY(tc2)
  99 {
 100     ... second test case's body ...
 101 }
 102 ATF_TEST_CASE_CLEANUP(tc2)
 103 {
 104     ... second test case's cleanup ...
 105 }
 106
 107 .Ns ... additional test cases ...
 108
 109 ATF_INIT_TEST_CASES(tcs)
 110 {
 111     ATF_ADD_TEST_CASE(tcs, tc1)
 112     ATF_ADD_TEST_CASE(tcs, tc2)
 113     ... add additional test cases ...
 114 }
 115 .Ed
 116 .Ss Definition of test cases
 117 Test cases have an identifier and are composed of three different parts:
 118 the header, the body and an optional cleanup routine, all of which are
 119 described in
 120 .Xr atf-test-case 8 .
 121 To define test cases, one can use the
 122 .Fn ATF_TEST_CASE
 123 or the
 124 .Fn ATF_TEST_CASE_WITH_CLEANUP
 125 macros, which take a single parameter specifiying the test case's
 126 name.
 127 The former does not allow the specification of a cleanup routine for the
 128 test case while the latter does.
 129 It is important to note that these
 130 .Em do not
 131 set the test case up for execution when the program is run.
 132 In order to do so, a later registration is needed through the
 133 .Fn ATF_ADD_TEST_CASE
 134 macro detailed in
 135 .Sx Program initialization .
 136 .Pp
 137 Later on, one must define the three parts of the body by means of three
 138 functions.
 139 Their headers are given by the
 140 .Fn ATF_TEST_CASE_HEAD ,
 141 .Fn ATF_TEST_CASE_BODY
 142 and
 143 .Fn ATF_TEST_CASE_CLEANUP
 144 macros, all of which take the test case's name.
 145 Following each of these, a block of code is expected, surrounded by the
 146 opening and closing brackets.
 147 .Ss Program initialization
 148 The library provides a way to easily define the test program's
 149 .Fn main
 150 function.
 151 You should never define one on your own, but rely on the
 152 library to do it for you.
 153 This is done by using the
 154 .Fn ATF_INIT_TEST_CASES
 155 macro, which is passed the name of the list that will hold the test cases.
 156 This name can be whatever you want as long as it is a valid variable value.
 157 .Pp
 158 After the macro, you are supposed to provide the body of a function, which
 159 should only use the
 160 .Fn ATF_ADD_TEST_CASE
 161 macro to register the test cases the test program will execute.
 162 The first parameter of this macro matches the name you provided in the
 163 former call.
 164 .Ss Header definitions
 165 The test case's header can define the meta-data by using the
 166 .Fn set
 167 method, which takes two parameters: the first one specifies the
 168 meta-data variable to be set and the second one specifies its value.
 169 Both of them are strings.
 170 .Ss Configuration variables
 171 The test case has read-only access to the current configuration variables
 172 by means of the
 173 .Ft bool
 174 .Fn has_config_var
 175 and the
 176 .Ft std::string
 177 .Fn get_config_var
 178 methods, which can be called in any of the three parts of a test case.
 179 .Ss Access to the source directory
 180 It is possible to get the path to the test case's source directory from any
 181 of its three components by querying the
 182 .Sq srcdir
 183 configuration variable.
 184 .Ss Requiring programs
 185 Aside from the
 186 .Va require.progs
 187 meta-data variable available in the header only, one can also check for
 188 additional programs in the test case's body by using the
 189 .Fn require_prog
 190 function, which takes the base name or full path of a single binary.
 191 Relative paths are forbidden.
 192 If it is not found, the test case will be automatically skipped.
 193 .Ss Test case finalization
 194 The test case finalizes either when the body reaches its end, at which
 195 point the test is assumed to have
 196 .Em passed ,
 197 or at any explicit call to
 198 .Fn ATF_PASS ,
 199 .Fn ATF_FAIL
 200 or
 201 .Fn ATF_SKIP .
 202 These three macros terminate the execution of the test case immediately.
 203 The cleanup routine will be processed afterwards in a completely automated
 204 way, regardless of the test case's termination reason.
 205 .Pp
 206 .Fn ATF_PASS
 207 does not take any parameters.
 208 .Fn ATF_FAIL
 209 and
 210 .Fn ATF_SKIP
 211 take a single string that describes why the test case failed or
 212 was skipped, respectively.
 213 It is very important to provide a clear error message in both cases so that
 214 the user can quickly know why the test did not pass.
 215 .Ss Helper macros for common checks
 216 The library provides several macros that are very handy in multiple
 217 situations.
 218 These basically check some condition after executing a given statement or
 219 processing a given expression and, if the condition is not met, they
 220 automatically call
 221 .Fn ATF_FAIL
 222 with an appropriate error message.
 223 .Pp
 224 .Fn ATF_CHECK
 225 takes an expression and raises a failure if it evaluates to false.
 226 .Pp
 227 .Fn ATF_CHECK_EQUAL
 228 takes two expressions and raises a failure if the two do not evaluate to
 229 the same exact value.
 230 .Pp
 231 .Fn ATF_CHECK_THROW
 232 takes a statement and the name of an exception and raises a failure if
 233 the statement did not throw the specified exception.
 234 .Sh EXAMPLES
 235 The following shows a complete test program with a single test case that
 236 validates the addition operator:
 237 .Bd -literal -offset indent
 238 #include <atf-c++.hpp>
 239
 240 ATF_TEST_CASE(addition);
 241 ATF_TEST_CASE_HEAD(addition)
 242 {
 243     set("descr", "Sample tests for the addition operator");
 244 }
 245 ATF_TEST_CASE_BODY(addition)
 246 {
 247     ATF_CHECK_EQUAL(0 + 0, 0);
 248     ATF_CHECK_EQUAL(0 + 1, 1);
 249     ATF_CHECK_EQUAL(1 + 0, 1);
 250
 251     ATF_CHECK_EQUAL(1 + 1, 2);
 252
 253     ATF_CHECK_EQUAL(100 + 200, 300);
 254 }
 255
 256 ATF_INIT_TEST_CASES(tcs)
 257 {
 258     ATF_ADD_TEST_CASE(tcs, addition);
 259 }
 260 .Ed
 261 .Sh SEE ALSO
 262 .Xr atf-test-program 1 ,
 263 .Xr atf 7 ,
 264 .Xr atf-test-case 8