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 63ATF provides a mostly-macro-based programming interface to implement test 64programs in C or C++. 65This interface is backed by a C++ implementation, but this fact is 66hidden from the developer as much as possible through the use of 67macros to simplify programming. 68However, the use of C++ is not hidden everywhere and while you can 69implement test cases without knowing anything at all about the object model 70underneath the provided calls, you might need some minimum notions of the 71language in very specific circumstances. 72.Pp 73C++-based test programs always follow this template: 74.Bd -literal -offset indent 75extern "C" { 76.Ns ... C-specific includes go here ... 77} 78 79.Ns ... C++-specific includes go here ... 80 81#include <atf-c++.hpp> 82 83ATF_TEST_CASE(tc1); 84ATF_TEST_CASE_HEAD(tc1) 85{ 86 ... first test case's header ... 87} 88ATF_TEST_CASE_BODY(tc1) 89{ 90 ... first test case's body ... 91} 92 93ATF_TEST_CASE_WITH_CLEANUP(tc2); 94ATF_TEST_CASE_HEAD(tc2) 95{ 96 ... second test case's header ... 97} 98ATF_TEST_CASE_BODY(tc2) 99{ 100 ... second test case's body ... 101} 102ATF_TEST_CASE_CLEANUP(tc2) 103{ 104 ... second test case's cleanup ... 105} 106 107.Ns ... additional test cases ... 108 109ATF_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 117Test cases have an identifier and are composed of three different parts: 118the header, the body and an optional cleanup routine, all of which are 119described in 120.Xr atf-test-case 8 . 121To define test cases, one can use the 122.Fn ATF_TEST_CASE 123or the 124.Fn ATF_TEST_CASE_WITH_CLEANUP 125macros, which take a single parameter specifiying the test case's 126name. 127The former does not allow the specification of a cleanup routine for the 128test case while the latter does. 129It is important to note that these 130.Em do not 131set the test case up for execution when the program is run. 132In order to do so, a later registration is needed through the 133.Fn ATF_ADD_TEST_CASE 134macro detailed in 135.Sx Program initialization . 136.Pp 137Later on, one must define the three parts of the body by means of three 138functions. 139Their headers are given by the 140.Fn ATF_TEST_CASE_HEAD , 141.Fn ATF_TEST_CASE_BODY 142and 143.Fn ATF_TEST_CASE_CLEANUP 144macros, all of which take the test case's name. 145Following each of these, a block of code is expected, surrounded by the 146opening and closing brackets. 147.Ss Program initialization 148The library provides a way to easily define the test program's 149.Fn main 150function. 151You should never define one on your own, but rely on the 152library to do it for you. 153This is done by using the 154.Fn ATF_INIT_TEST_CASES 155macro, which is passed the name of the list that will hold the test cases. 156This name can be whatever you want as long as it is a valid variable value. 157.Pp 158After the macro, you are supposed to provide the body of a function, which 159should only use the 160.Fn ATF_ADD_TEST_CASE 161macro to register the test cases the test program will execute. 162The first parameter of this macro matches the name you provided in the 163former call. 164.Ss Header definitions 165The test case's header can define the meta-data by using the 166.Fn set 167method, which takes two parameters: the first one specifies the 168meta-data variable to be set and the second one specifies its value. 169Both of them are strings. 170.Ss Configuration variables 171The test case has read-only access to the current configuration variables 172by means of the 173.Ft bool 174.Fn has_config_var 175and the 176.Ft std::string 177.Fn get_config_var 178methods, which can be called in any of the three parts of a test case. 179.Ss Access to the source directory 180It is possible to get the path to the test case's source directory from any 181of its three components by querying the 182.Sq srcdir 183configuration variable. 184.Ss Requiring programs 185Aside from the 186.Va require.progs 187meta-data variable available in the header only, one can also check for 188additional programs in the test case's body by using the 189.Fn require_prog 190function, which takes the base name or full path of a single binary. 191Relative paths are forbidden. 192If it is not found, the test case will be automatically skipped. 193.Ss Test case finalization 194The test case finalizes either when the body reaches its end, at which 195point the test is assumed to have 196.Em passed , 197or at any explicit call to 198.Fn ATF_PASS , 199.Fn ATF_FAIL 200or 201.Fn ATF_SKIP . 202These three macros terminate the execution of the test case immediately. 203The cleanup routine will be processed afterwards in a completely automated 204way, regardless of the test case's termination reason. 205.Pp 206.Fn ATF_PASS 207does not take any parameters. 208.Fn ATF_FAIL 209and 210.Fn ATF_SKIP 211take a single string that describes why the test case failed or 212was skipped, respectively. 213It is very important to provide a clear error message in both cases so that 214the user can quickly know why the test did not pass. 215.Ss Helper macros for common checks 216The library provides several macros that are very handy in multiple 217situations. 218These basically check some condition after executing a given statement or 219processing a given expression and, if the condition is not met, they 220automatically call 221.Fn ATF_FAIL 222with an appropriate error message. 223.Pp 224.Fn ATF_CHECK 225takes an expression and raises a failure if it evaluates to false. 226.Pp 227.Fn ATF_CHECK_EQUAL 228takes two expressions and raises a failure if the two do not evaluate to 229the same exact value. 230.Pp 231.Fn ATF_CHECK_THROW 232takes a statement and the name of an exception and raises a failure if 233the statement did not throw the specified exception. 234.Sh EXAMPLES 235The following shows a complete test program with a single test case that 236validates the addition operator: 237.Bd -literal -offset indent 238#include <atf-c++.hpp> 239 240ATF_TEST_CASE(addition); 241ATF_TEST_CASE_HEAD(addition) 242{ 243 set("descr", "Sample tests for the addition operator"); 244} 245ATF_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 256ATF_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 265