contrib/atf/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 January 21, 2012
  30 .Dt ATF-C++-API 3
  31 .Os
  32 .Sh NAME
  33 .Nm ATF_ADD_TEST_CASE ,
  34 .Nm ATF_CHECK_ERRNO ,
  35 .Nm ATF_FAIL ,
  36 .Nm ATF_INIT_TEST_CASES ,
  37 .Nm ATF_PASS ,
  38 .Nm ATF_REQUIRE ,
  39 .Nm ATF_REQUIRE_EQ ,
  40 .Nm ATF_REQUIRE_ERRNO ,
  41 .Nm ATF_REQUIRE_IN ,
  42 .Nm ATF_REQUIRE_MATCH ,
  43 .Nm ATF_REQUIRE_NOT_IN ,
  44 .Nm ATF_REQUIRE_THROW ,
  45 .Nm ATF_REQUIRE_THROW_RE ,
  46 .Nm ATF_SKIP ,
  47 .Nm ATF_TEST_CASE ,
  48 .Nm ATF_TEST_CASE_BODY ,
  49 .Nm ATF_TEST_CASE_CLEANUP ,
  50 .Nm ATF_TEST_CASE_HEAD ,
  51 .Nm ATF_TEST_CASE_NAME ,
  52 .Nm ATF_TEST_CASE_USE ,
  53 .Nm ATF_TEST_CASE_WITH_CLEANUP ,
  54 .Nm ATF_TEST_CASE_WITHOUT_HEAD ,
  55 .Nd C++ API to write ATF-based test programs
  56 .Sh SYNOPSIS
  57 .In atf-c++.hpp
  58 .Fn ATF_ADD_TEST_CASE "tcs" "name"
  59 .Fn ATF_CHECK_ERRNO "exp_errno" "bool_expression"
  60 .Fn ATF_FAIL "reason"
  61 .Fn ATF_INIT_TEST_CASES "tcs"
  62 .Fn ATF_PASS
  63 .Fn ATF_REQUIRE "expression"
  64 .Fn ATF_REQUIRE_EQ "expression_1" "expression_2"
  65 .Fn ATF_REQUIRE_ERRNO "exp_errno" "bool_expression"
  66 .Fn ATF_REQUIRE_IN "element" "collection"
  67 .Fn ATF_REQUIRE_MATCH "regexp" "string_expression"
  68 .Fn ATF_REQUIRE_NOT_IN "element" "collection"
  69 .Fn ATF_REQUIRE_THROW "expected_exception" "statement"
  70 .Fn ATF_REQUIRE_THROW_RE "expected_exception" "regexp" "statement"
  71 .Fn ATF_SKIP "reason"
  72 .Fn ATF_TEST_CASE "name"
  73 .Fn ATF_TEST_CASE_BODY "name"
  74 .Fn ATF_TEST_CASE_CLEANUP "name"
  75 .Fn ATF_TEST_CASE_HEAD "name"
  76 .Fn ATF_TEST_CASE_NAME "name"
  77 .Fn ATF_TEST_CASE_USE "name"
  78 .Fn ATF_TEST_CASE_WITH_CLEANUP "name"
  79 .Fn ATF_TEST_CASE_WITHOUT_HEAD "name"
  80 .Sh DESCRIPTION
  81 ATF provides a mostly-macro-based programming interface to implement test
  82 programs in C or C++.
  83 This interface is backed by a C++ implementation, but this fact is
  84 hidden from the developer as much as possible through the use of
  85 macros to simplify programming.
  86 However, the use of C++ is not hidden everywhere and while you can
  87 implement test cases without knowing anything at all about the object model
  88 underneath the provided calls, you might need some minimum notions of the
  89 language in very specific circumstances.
  90 .Pp
  91 C++-based test programs always follow this template:
  92 .Bd -literal -offset indent
  93 extern "C" {
  94 .Ns ... C-specific includes go here ...
  95 }
  96
  97 .Ns ... C++-specific includes go here ...
  98
  99 #include <atf-c++.hpp>
 100
 101 ATF_TEST_CASE(tc1);
 102 ATF_TEST_CASE_HEAD(tc1)
 103 {
 104     ... first test case's header ...
 105 }
 106 ATF_TEST_CASE_BODY(tc1)
 107 {
 108     ... first test case's body ...
 109 }
 110
 111 ATF_TEST_CASE_WITH_CLEANUP(tc2);
 112 ATF_TEST_CASE_HEAD(tc2)
 113 {
 114     ... second test case's header ...
 115 }
 116 ATF_TEST_CASE_BODY(tc2)
 117 {
 118     ... second test case's body ...
 119 }
 120 ATF_TEST_CASE_CLEANUP(tc2)
 121 {
 122     ... second test case's cleanup ...
 123 }
 124
 125 ATF_TEST_CASE(tc3);
 126 ATF_TEST_CASE_BODY(tc3)
 127 {
 128     ... third test case's body ...
 129 }
 130
 131 .Ns ... additional test cases ...
 132
 133 ATF_INIT_TEST_CASES(tcs)
 134 {
 135     ATF_ADD_TEST_CASE(tcs, tc1);
 136     ATF_ADD_TEST_CASE(tcs, tc2);
 137     ATF_ADD_TEST_CASE(tcs, tc3);
 138     ... add additional test cases ...
 139 }
 140 .Ed
 141 .Ss Definition of test cases
 142 Test cases have an identifier and are composed of three different parts:
 143 the header, the body and an optional cleanup routine, all of which are
 144 described in
 145 .Xr atf-test-case 4 .
 146 To define test cases, one can use the
 147 .Fn ATF_TEST_CASE ,
 148 .Fn ATF_TEST_CASE_WITH_CLEANUP
 149 or the
 150 .Fn ATF_TEST_CASE_WITHOUT_HEAD
 151 macros, which take a single parameter specifiying the test case's
 152 name.
 153 .Fn ATF_TEST_CASE ,
 154 requires to define a head and a body for the test case,
 155 .Fn ATF_TEST_CASE_WITH_CLEANUP
 156 requires to define a head, a body and a cleanup for the test case and
 157 .Fn ATF_TEST_CASE_WITHOUT_HEAD
 158 requires only a body for the test case.
 159 It is important to note that these
 160 .Em do not
 161 set the test case up for execution when the program is run.
 162 In order to do so, a later registration is needed through the
 163 .Fn ATF_ADD_TEST_CASE
 164 macro detailed in
 165 .Sx Program initialization .
 166 .Pp
 167 Later on, one must define the three parts of the body by means of three
 168 functions.
 169 Their headers are given by the
 170 .Fn ATF_TEST_CASE_HEAD ,
 171 .Fn ATF_TEST_CASE_BODY
 172 and
 173 .Fn ATF_TEST_CASE_CLEANUP
 174 macros, all of which take the test case's name.
 175 Following each of these, a block of code is expected, surrounded by the
 176 opening and closing brackets.
 177 .Pp
 178 Additionally, the
 179 .Fn ATF_TEST_CASE_NAME
 180 macro can be used to obtain the name of the class corresponding to a
 181 particular test case, as the name is internally manged by the library to
 182 prevent clashes with other user identifiers.
 183 Similarly, the
 184 .Fn ATF_TEST_CASE_USE
 185 macro can be executed on a particular test case to mark it as "used" and
 186 thus prevent compiler warnings regarding unused symbols.
 187 Note that
 188 .Em you should never have to use these macros during regular operation.
 189 .Ss Program initialization
 190 The library provides a way to easily define the test program's
 191 .Fn main
 192 function.
 193 You should never define one on your own, but rely on the
 194 library to do it for you.
 195 This is done by using the
 196 .Fn ATF_INIT_TEST_CASES
 197 macro, which is passed the name of the list that will hold the test cases.
 198 This name can be whatever you want as long as it is a valid variable value.
 199 .Pp
 200 After the macro, you are supposed to provide the body of a function, which
 201 should only use the
 202 .Fn ATF_ADD_TEST_CASE
 203 macro to register the test cases the test program will execute.
 204 The first parameter of this macro matches the name you provided in the
 205 former call.
 206 .Ss Header definitions
 207 The test case's header can define the meta-data by using the
 208 .Fn set
 209 method, which takes two parameters: the first one specifies the
 210 meta-data variable to be set and the second one specifies its value.
 211 Both of them are strings.
 212 .Ss Configuration variables
 213 The test case has read-only access to the current configuration variables
 214 by means of the
 215 .Ft bool
 216 .Fn has_config_var
 217 and the
 218 .Ft std::string
 219 .Fn get_config_var
 220 methods, which can be called in any of the three parts of a test case.
 221 .Ss Access to the source directory
 222 It is possible to get the path to the test case's source directory from any
 223 of its three components by querying the
 224 .Sq srcdir
 225 configuration variable.
 226 .Ss Requiring programs
 227 Aside from the
 228 .Va require.progs
 229 meta-data variable available in the header only, one can also check for
 230 additional programs in the test case's body by using the
 231 .Fn require_prog
 232 function, which takes the base name or full path of a single binary.
 233 Relative paths are forbidden.
 234 If it is not found, the test case will be automatically skipped.
 235 .Ss Test case finalization
 236 The test case finalizes either when the body reaches its end, at which
 237 point the test is assumed to have
 238 .Em passed ,
 239 or at any explicit call to
 240 .Fn ATF_PASS ,
 241 .Fn ATF_FAIL
 242 or
 243 .Fn ATF_SKIP .
 244 These three macros terminate the execution of the test case immediately.
 245 The cleanup routine will be processed afterwards in a completely automated
 246 way, regardless of the test case's termination reason.
 247 .Pp
 248 .Fn ATF_PASS
 249 does not take any parameters.
 250 .Fn ATF_FAIL
 251 and
 252 .Fn ATF_SKIP
 253 take a single string that describes why the test case failed or
 254 was skipped, respectively.
 255 It is very important to provide a clear error message in both cases so that
 256 the user can quickly know why the test did not pass.
 257 .Ss Expectations
 258 Everything explained in the previous section changes when the test case
 259 expectations are redefined by the programmer.
 260 .Pp
 261 Each test case has an internal state called
 262 .Sq expect
 263 that describes what the test case expectations are at any point in time.
 264 The value of this property can change during execution by any of:
 265 .Bl -tag -width indent
 266 .It Fn expect_death "reason"
 267 Expects the test case to exit prematurely regardless of the nature of the
 268 exit.
 269 .It Fn expect_exit "exitcode" "reason"
 270 Expects the test case to exit cleanly.
 271 If
 272 .Va exitcode
 273 is not
 274 .Sq -1 ,
 275 .Xr atf-run 1
 276 will validate that the exit code of the test case matches the one provided
 277 in this call.
 278 Otherwise, the exact value will be ignored.
 279 .It Fn expect_fail "reason"
 280 Any failure (be it fatal or non-fatal) raised in this mode is recorded.
 281 However, such failures do not report the test case as failed; instead, the
 282 test case finalizes cleanly and is reported as
 283 .Sq expected failure ;
 284 this report includes the provided
 285 .Fa reason
 286 as part of it.
 287 If no error is raised while running in this mode, then the test case is
 288 reported as
 289 .Sq failed .
 290 .Pp
 291 This mode is useful to reproduce actual known bugs in tests.
 292 Whenever the developer fixes the bug later on, the test case will start
 293 reporting a failure, signaling the developer that the test case must be
 294 adjusted to the new conditions.
 295 In this situation, it is useful, for example, to set
 296 .Fa reason
 297 as the bug number for tracking purposes.
 298 .It Fn expect_pass
 299 This is the normal mode of execution.
 300 In this mode, any failure is reported as such to the user and the test case
 301 is marked as
 302 .Sq failed .
 303 .It Fn expect_race "reason"
 304 Any failure or timeout during the execution of the test case will be
 305 considered as if a race condition has been triggered and reported as such.
 306 If no problems arise, the test will continue execution as usual.
 307 .It Fn expect_signal "signo" "reason"
 308 Expects the test case to terminate due to the reception of a signal.
 309 If
 310 .Va signo
 311 is not
 312 .Sq -1 ,
 313 .Xr atf-run 1
 314 will validate that the signal that terminated the test case matches the one
 315 provided in this call.
 316 Otherwise, the exact value will be ignored.
 317 .It Fn expect_timeout "reason"
 318 Expects the test case to execute for longer than its timeout.
 319 .El
 320 .Ss Helper macros for common checks
 321 The library provides several macros that are very handy in multiple
 322 situations.
 323 These basically check some condition after executing a given statement or
 324 processing a given expression and, if the condition is not met, they
 325 automatically call
 326 .Fn ATF_FAIL
 327 with an appropriate error message.
 328 .Pp
 329 .Fn ATF_REQUIRE
 330 takes an expression and raises a failure if it evaluates to false.
 331 .Pp
 332 .Fn ATF_REQUIRE_EQ
 333 takes two expressions and raises a failure if the two do not evaluate to
 334 the same exact value.
 335 .Pp
 336 .Fn ATF_REQUIRE_IN
 337 takes an element and a collection and validates that the element is present in
 338 the collection.
 339 .Pp
 340 .Fn ATF_REQUIRE_MATCH
 341 takes a regular expression and a string and raises a failure if the regular
 342 expression does not match the string.
 343 .Pp
 344 .Fn ATF_REQUIRE_NOT_IN
 345 takes an element and a collection and validates that the element is not present
 346 in the collection.
 347 .Pp
 348 .Fn ATF_REQUIRE_THROW
 349 takes the name of an exception and a statement and raises a failure if
 350 the statement does not throw the specified exception.
 351 .Fn ATF_REQUIRE_THROW_EQ
 352 takes the name of an exception, a regular expresion and a statement and raises a
 353 failure if the statement does not throw the specified exception and if the
 354 message of the exception does not match the regular expression.
 355 .Pp
 356 .Fn ATF_CHECK_ERRNO
 357 and
 358 .Fn ATF_REQUIRE_ERRNO
 359 take, first, the error code that the check is expecting to find in the
 360 .Va errno
 361 variable and, second, a boolean expression that, if evaluates to true,
 362 means that a call failed and
 363 .Va errno
 364 has to be checked against the first value.
 365 .Sh EXAMPLES
 366 The following shows a complete test program with a single test case that
 367 validates the addition operator:
 368 .Bd -literal -offset indent
 369 #include <atf-c++.hpp>
 370
 371 ATF_TEST_CASE(addition);
 372 ATF_TEST_CASE_HEAD(addition)
 373 {
 374     set("descr", "Sample tests for the addition operator");
 375 }
 376 ATF_TEST_CASE_BODY(addition)
 377 {
 378     ATF_REQUIRE_EQ(0 + 0, 0);
 379     ATF_REQUIRE_EQ(0 + 1, 1);
 380     ATF_REQUIRE_EQ(1 + 0, 1);
 381
 382     ATF_REQUIRE_EQ(1 + 1, 2);
 383
 384     ATF_REQUIRE_EQ(100 + 200, 300);
 385 }
 386
 387 ATF_TEST_CASE(open_failure);
 388 ATF_TEST_CASE_HEAD(open_failure)
 389 {
 390     set("descr", "Sample tests for the open function");
 391 }
 392 ATF_TEST_CASE_BODY(open_failure)
 393 {
 394     ATF_REQUIRE_ERRNO(ENOENT, open("non-existent", O_RDONLY) == -1);
 395 }
 396
 397 ATF_TEST_CASE(known_bug);
 398 ATF_TEST_CASE_HEAD(known_bug)
 399 {
 400     set("descr", "Reproduces a known bug");
 401 }
 402 ATF_TEST_CASE_BODY(known_bug)
 403 {
 404     expect_fail("See bug number foo/bar");
 405     ATF_REQUIRE_EQ(3, 1 + 1);
 406     expect_pass();
 407     ATF_REQUIRE_EQ(3, 1 + 2);
 408 }
 409
 410 ATF_INIT_TEST_CASES(tcs)
 411 {
 412     ATF_ADD_TEST_CASE(tcs, addition);
 413     ATF_ADD_TEST_CASE(tcs, open_failure);
 414     ATF_ADD_TEST_CASE(tcs, known_bug);
 415 }
 416 .Ed
 417 .Sh SEE ALSO
 418 .Xr atf-test-program 1 ,
 419 .Xr atf-test-case 4 ,
 420 .Xr atf 7