1.\" $NetBSD: atf-c-api.3,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 November 30, 2012 32.Dt ATF-C-API 3 33.Os 34.Sh NAME 35.Nm atf-c-api , 36.Nm ATF_CHECK , 37.Nm ATF_CHECK_MSG , 38.Nm ATF_CHECK_EQ , 39.Nm ATF_CHECK_EQ_MSG , 40.Nm ATF_CHECK_MATCH , 41.Nm ATF_CHECK_MATCH_MSG , 42.Nm ATF_CHECK_STREQ , 43.Nm ATF_CHECK_STREQ_MSG , 44.Nm ATF_CHECK_ERRNO , 45.Nm ATF_REQUIRE , 46.Nm ATF_REQUIRE_MSG , 47.Nm ATF_REQUIRE_EQ , 48.Nm ATF_REQUIRE_EQ_MSG , 49.Nm ATF_REQUIRE_MATCH , 50.Nm ATF_REQUIRE_MATCH_MSG , 51.Nm ATF_REQUIRE_STREQ , 52.Nm ATF_REQUIRE_STREQ_MSG , 53.Nm ATF_REQUIRE_ERRNO , 54.Nm ATF_TC , 55.Nm ATF_TC_BODY , 56.Nm ATF_TC_BODY_NAME , 57.Nm ATF_TC_CLEANUP , 58.Nm ATF_TC_CLEANUP_NAME , 59.Nm ATF_TC_HEAD , 60.Nm ATF_TC_HEAD_NAME , 61.Nm ATF_TC_NAME , 62.Nm ATF_TC_WITH_CLEANUP , 63.Nm ATF_TC_WITHOUT_HEAD , 64.Nm ATF_TP_ADD_TC , 65.Nm ATF_TP_ADD_TCS , 66.Nm atf_tc_get_config_var , 67.Nm atf_tc_get_config_var_wd , 68.Nm atf_tc_get_config_var_as_bool , 69.Nm atf_tc_get_config_var_as_bool_wd , 70.Nm atf_tc_get_config_var_as_long , 71.Nm atf_tc_get_config_var_as_long_wd , 72.Nm atf_no_error , 73.Nm atf_tc_expect_death , 74.Nm atf_tc_expect_exit , 75.Nm atf_tc_expect_fail , 76.Nm atf_tc_expect_pass , 77.Nm atf_tc_expect_signal , 78.Nm atf_tc_expect_timeout , 79.Nm atf_tc_fail , 80.Nm atf_tc_fail_nonfatal , 81.Nm atf_tc_pass , 82.Nm atf_tc_skip , 83.Nm atf_utils_cat_file , 84.Nm atf_utils_compare_file , 85.Nm atf_utils_copy_file , 86.Nm atf_utils_create_file , 87.Nm atf_utils_file_exists , 88.Nm atf_utils_fork , 89.Nm atf_utils_free_charpp , 90.Nm atf_utils_grep_file , 91.Nm atf_utils_grep_string , 92.Nm atf_utils_readline , 93.Nm atf_utils_redirect , 94.Nm atf_utils_wait 95.Nd C API to write ATF-based test programs 96.Sh SYNOPSIS 97.In atf-c.h 98.Fn ATF_CHECK "expression" 99.Fn ATF_CHECK_MSG "expression" "fail_msg_fmt" ... 100.Fn ATF_CHECK_EQ "expression_1" "expression_2" 101.Fn ATF_CHECK_EQ_MSG "expression_1" "expression_2" "fail_msg_fmt" ... 102.Fn ATF_CHECK_MATCH "regexp" "string" 103.Fn ATF_CHECK_MATCH_MSG "regexp" "string" "fail_msg_fmt" ... 104.Fn ATF_CHECK_STREQ "string_1" "string_2" 105.Fn ATF_CHECK_STREQ_MSG "string_1" "string_2" "fail_msg_fmt" ... 106.Fn ATF_CHECK_ERRNO "exp_errno" "bool_expression" 107.Fn ATF_REQUIRE "expression" 108.Fn ATF_REQUIRE_MSG "expression" "fail_msg_fmt" ... 109.Fn ATF_REQUIRE_EQ "expression_1" "expression_2" 110.Fn ATF_REQUIRE_EQ_MSG "expression_1" "expression_2" "fail_msg_fmt" ... 111.Fn ATF_REQUIRE_MATCH "regexp" "string" 112.Fn ATF_REQUIRE_MATCH_MSG "regexp" "string" "fail_msg_fmt" ... 113.Fn ATF_REQUIRE_STREQ "string_1" "string_2" 114.Fn ATF_REQUIRE_STREQ_MSG "string_1" "string_2" "fail_msg_fmt" ... 115.Fn ATF_REQUIRE_ERRNO "exp_errno" "bool_expression" 116.Fn ATF_TC "name" 117.Fn ATF_TC_BODY "name" "tc" 118.Fn ATF_TC_BODY_NAME "name" 119.Fn ATF_TC_CLEANUP "name" "tc" 120.Fn ATF_TC_CLEANUP_NAME "name" 121.Fn ATF_TC_HEAD "name" "tc" 122.Fn ATF_TC_HEAD_NAME "name" 123.Fn ATF_TC_NAME "name" 124.Fn ATF_TC_WITH_CLEANUP "name" 125.Fn ATF_TC_WITHOUT_HEAD "name" 126.Fn ATF_TP_ADD_TC "tp_name" "tc_name" 127.Fn ATF_TP_ADD_TCS "tp_name" 128.Fn atf_tc_get_config_var "tc" "varname" 129.Fn atf_tc_get_config_var_wd "tc" "variable_name" "default_value" 130.Fn atf_tc_get_config_var_as_bool "tc" "variable_name" 131.Fn atf_tc_get_config_var_as_bool_wd "tc" "variable_name" "default_value" 132.Fn atf_tc_get_config_var_as_long "tc" "variable_name" 133.Fn atf_tc_get_config_var_as_long_wd "tc" "variable_name" "default_value" 134.Fn atf_no_error 135.Fn atf_tc_expect_death "reason" "..." 136.Fn atf_tc_expect_exit "exitcode" "reason" "..." 137.Fn atf_tc_expect_fail "reason" "..." 138.Fn atf_tc_expect_pass 139.Fn atf_tc_expect_signal "signo" "reason" "..." 140.Fn atf_tc_expect_timeout "reason" "..." 141.Fn atf_tc_fail "reason" 142.Fn atf_tc_fail_nonfatal "reason" 143.Fn atf_tc_pass 144.Fn atf_tc_skip "reason" 145.Ft void 146.Fo atf_utils_cat_file 147.Fa "const char *file" 148.Fa "const char *prefix" 149.Fc 150.Ft bool 151.Fo atf_utils_compare_file 152.Fa "const char *file" 153.Fa "const char *contents" 154.Fc 155.Ft void 156.Fo atf_utils_copy_file 157.Fa "const char *source" 158.Fa "const char *destination" 159.Fc 160.Ft void 161.Fo atf_utils_create_file 162.Fa "const char *file" 163.Fa "const char *contents" 164.Fa "..." 165.Fc 166.Ft void 167.Fo atf_utils_file_exists 168.Fa "const char *file" 169.Fc 170.Ft pid_t 171.Fo atf_utils_fork 172.Fa "void" 173.Fc 174.Ft void 175.Fo atf_utils_free_charpp 176.Fa "char **argv" 177.Fc 178.Ft bool 179.Fo atf_utils_grep_file 180.Fa "const char *regexp" 181.Fa "const char *file" 182.Fa "..." 183.Fc 184.Ft bool 185.Fo atf_utils_grep_string 186.Fa "const char *regexp" 187.Fa "const char *str" 188.Fa "..." 189.Fc 190.Ft char * 191.Fo atf_utils_readline 192.Fa "int fd" 193.Fc 194.Ft void 195.Fo atf_utils_redirect 196.Fa "const int fd" 197.Fa "const char *file" 198.Fc 199.Ft void 200.Fo atf_utils_wait 201.Fa "const pid_t pid" 202.Fa "const int expected_exit_status" 203.Fa "const char *expected_stdout" 204.Fa "const char *expected_stderr" 205.Fc 206.Sh DESCRIPTION 207The ATF 208.Pp 209C-based test programs always follow this template: 210.Bd -literal -offset indent 211.Ns ... C-specific includes go here ... 212 213#include <atf-c.h> 214 215ATF_TC(tc1); 216ATF_TC_HEAD(tc1, tc) 217{ 218 ... first test case's header ... 219} 220ATF_TC_BODY(tc1, tc) 221{ 222 ... first test case's body ... 223} 224 225ATF_TC_WITH_CLEANUP(tc2); 226ATF_TC_HEAD(tc2, tc) 227{ 228 ... second test case's header ... 229} 230ATF_TC_BODY(tc2, tc) 231{ 232 ... second test case's body ... 233} 234ATF_TC_CLEANUP(tc2, tc) 235{ 236 ... second test case's cleanup ... 237} 238 239ATF_TC_WITHOUT_HEAD(tc3); 240ATF_TC_BODY(tc3, tc) 241{ 242 ... third test case's body ... 243} 244 245.Ns ... additional test cases ... 246 247ATF_TP_ADD_TCS(tp) 248{ 249 ATF_TP_ADD_TC(tcs, tc1); 250 ATF_TP_ADD_TC(tcs, tc2); 251 ATF_TP_ADD_TC(tcs, tc3); 252 ... add additional test cases ... 253 254 return atf_no_error(); 255} 256.Ed 257.Ss Definition of test cases 258Test cases have an identifier and are composed of three different parts: 259the header, the body and an optional cleanup routine, all of which are 260described in 261.Xr atf-test-case 4 . 262To define test cases, one can use the 263.Fn ATF_TC , 264.Fn ATF_TC_WITH_CLEANUP 265or the 266.Fn ATF_TC_WITHOUT_HEAD 267macros, which take a single parameter specifiying the test case's name. 268.Fn ATF_TC , 269requires to define a head and a body for the test case, 270.Fn ATF_TC_WITH_CLEANUP 271requires to define a head, a body and a cleanup for the test case and 272.Fn ATF_TC_WITHOUT_HEAD 273requires only a body for the test case. 274It is important to note that these 275.Em do not 276set the test case up for execution when the program is run. 277In order to do so, a later registration is needed with the 278.Fn ATF_TP_ADD_TC 279macro detailed in 280.Sx Program initialization . 281.Pp 282Later on, one must define the three parts of the body by means of three 283functions. 284Their headers are given by the 285.Fn ATF_TC_HEAD , 286.Fn ATF_TC_BODY 287and 288.Fn ATF_TC_CLEANUP 289macros, all of which take the test case name provided to the 290.Fn ATF_TC 291.Fn ATF_TC_WITH_CLEANUP , 292or 293.Fn ATF_TC_WITHOUT_HEAD 294macros and the name of the variable that will hold a pointer to the 295test case data. 296Following each of these, a block of code is expected, surrounded by the 297opening and closing brackets. 298.Ss Program initialization 299The library provides a way to easily define the test program's 300.Fn main 301function. 302You should never define one on your own, but rely on the 303library to do it for you. 304This is done by using the 305.Fn ATF_TP_ADD_TCS 306macro, which is passed the name of the object that will hold the test 307cases; i.e. the test program instance. 308This name can be whatever you want as long as it is a valid variable 309identifier. 310.Pp 311After the macro, you are supposed to provide the body of a function, which 312should only use the 313.Fn ATF_TP_ADD_TC 314macro to register the test cases the test program will execute and return 315a success error code. 316The first parameter of this macro matches the name you provided in the 317former call. 318The success status can be returned using the 319.Fn atf_no_error 320function. 321.Ss Header definitions 322The test case's header can define the meta-data by using the 323.Fn atf_tc_set_md_var 324method, which takes three parameters: the first one points to the test 325case data, the second one specifies the meta-data variable to be set 326and the third one specifies its value. 327Both of them are strings. 328.Ss Configuration variables 329The test case has read-only access to the current configuration variables 330by means of the 331.Ft bool 332.Fn atf_tc_has_config_var , 333.Ft const char * 334.Fn atf_tc_get_config_var , 335.Ft const char * 336.Fn atf_tc_get_config_var_wd , 337.Ft bool 338.Fn atf_tc_get_config_var_as_bool , 339.Ft bool 340.Fn atf_tc_get_config_var_as_bool_wd , 341.Ft long 342.Fn atf_tc_get_config_var_as_long , 343and the 344.Ft long 345.Fn atf_tc_get_config_var_as_long_wd 346functions, which can be called in any of the three parts of a test case. 347.Pp 348The 349.Sq _wd 350variants take a default value for the variable which is returned if the 351variable is not defined. 352The other functions without the 353.Sq _wd 354suffix 355.Em require 356the variable to be defined. 357.Ss Access to the source directory 358It is possible to get the path to the test case's source directory from any 359of its three components by querying the 360.Sq srcdir 361configuration variable. 362.Ss Requiring programs 363Aside from the 364.Va require.progs 365meta-data variable available in the header only, one can also check for 366additional programs in the test case's body by using the 367.Fn atf_tc_require_prog 368function, which takes the base name or full path of a single binary. 369Relative paths are forbidden. 370If it is not found, the test case will be automatically skipped. 371.Ss Test case finalization 372The test case finalizes either when the body reaches its end, at which 373point the test is assumed to have 374.Em passed , 375unless any non-fatal errors were raised using 376.Fn atf_tc_fail_nonfatal , 377or at any explicit call to 378.Fn atf_tc_pass , 379.Fn atf_tc_fail 380or 381.Fn atf_tc_skip . 382These three functions terminate the execution of the test case immediately. 383The cleanup routine will be processed afterwards in a completely automated 384way, regardless of the test case's termination reason. 385.Pp 386.Fn atf_tc_pass 387does not take any parameters. 388.Fn atf_tc_fail , 389.Fn atf_tc_fail_nonfatal 390and 391.Fn atf_tc_skip 392take a format string and a variable list of parameters, which describe, in 393a user-friendly manner, why the test case failed or was skipped, 394respectively. 395It is very important to provide a clear error message in both cases so that 396the user can quickly know why the test did not pass. 397.Ss Expectations 398Everything explained in the previous section changes when the test case 399expectations are redefined by the programmer. 400.Pp 401Each test case has an internal state called 402.Sq expect 403that describes what the test case expectations are at any point in time. 404The value of this property can change during execution by any of: 405.Bl -tag -width indent 406.It Fn atf_tc_expect_death "reason" "..." 407Expects the test case to exit prematurely regardless of the nature of the 408exit. 409.It Fn atf_tc_expect_exit "exitcode" "reason" "..." 410Expects the test case to exit cleanly. 411If 412.Va exitcode 413is not 414.Sq -1 , 415.Xr atf-run 1 416will validate that the exit code of the test case matches the one provided 417in this call. 418Otherwise, the exact value will be ignored. 419.It Fn atf_tc_expect_fail "reason" "..." 420Any failure (be it fatal or non-fatal) raised in this mode is recorded. 421However, such failures do not report the test case as failed; instead, the 422test case finalizes cleanly and is reported as 423.Sq expected failure ; 424this report includes the provided 425.Fa reason 426as part of it. 427If no error is raised while running in this mode, then the test case is 428reported as 429.Sq failed . 430.Pp 431This mode is useful to reproduce actual known bugs in tests. 432Whenever the developer fixes the bug later on, the test case will start 433reporting a failure, signaling the developer that the test case must be 434adjusted to the new conditions. 435In this situation, it is useful, for example, to set 436.Fa reason 437as the bug number for tracking purposes. 438.It Fn atf_tc_expect_pass 439This is the normal mode of execution. 440In this mode, any failure is reported as such to the user and the test case 441is marked as 442.Sq failed . 443.It Fn atf_tc_expect_signal "signo" "reason" "..." 444Expects the test case to terminate due to the reception of a signal. 445If 446.Va signo 447is not 448.Sq -1 , 449.Xr atf-run 1 450will validate that the signal that terminated the test case matches the one 451provided in this call. 452Otherwise, the exact value will be ignored. 453.It Fn atf_tc_expect_timeout "reason" "..." 454Expects the test case to execute for longer than its timeout. 455.El 456.Ss Helper macros for common checks 457The library provides several macros that are very handy in multiple 458situations. 459These basically check some condition after executing a given statement or 460processing a given expression and, if the condition is not met, they 461report the test case as failed. 462.Pp 463The 464.Sq REQUIRE 465variant of the macros immediately abort the test case as soon as an error 466condition is detected by calling the 467.Fn atf_tc_fail 468function. 469Use this variant whenever it makes no sense to continue the execution of a 470test case when the checked condition is not met. 471The 472.Sq CHECK 473variant, on the other hand, reports a failure as soon as it is encountered 474using the 475.Fn atf_tc_fail_nonfatal 476function, but the execution of the test case continues as if nothing had 477happened. 478Use this variant whenever the checked condition is important as a result of 479the test case, but there are other conditions that can be subsequently 480checked on the same run without aborting. 481.Pp 482Additionally, the 483.Sq MSG 484variants take an extra set of parameters to explicitly specify the failure 485message. 486This failure message is formatted according to the 487.Xr printf 3 488formatters. 489.Pp 490.Fn ATF_CHECK , 491.Fn ATF_CHECK_MSG , 492.Fn ATF_REQUIRE 493and 494.Fn ATF_REQUIRE_MSG 495take an expression and fail if the expression evaluates to false. 496.Pp 497.Fn ATF_CHECK_EQ , 498.Fn ATF_CHECK_EQ_MSG , 499.Fn ATF_REQUIRE_EQ 500and 501.Fn ATF_REQUIRE_EQ_MSG 502take two expressions and fail if the two evaluated values are not equal. 503.Pp 504.Fn ATF_CHECK_MATCH , 505.Fn ATF_CHECK_MATCH_MSG , 506.Fn ATF_REQUIRE_MATCH 507and 508.Fn ATF_REQUIRE_MATCH_MSG 509take a regular expression and a string and fail if the regular expression does 510not match the given string. 511Note that the regular expression is not anchored, so it will match anywhere in 512the string. 513.Pp 514.Fn ATF_CHECK_STREQ , 515.Fn ATF_CHECK_STREQ_MSG , 516.Fn ATF_REQUIRE_STREQ 517and 518.Fn ATF_REQUIRE_STREQ_MSG 519take two strings and fail if the two are not equal character by character. 520.Pp 521.Fn ATF_CHECK_ERRNO 522and 523.Fn ATF_REQUIRE_ERRNO 524take, first, the error code that the check is expecting to find in the 525.Va errno 526variable and, second, a boolean expression that, if evaluates to true, 527means that a call failed and 528.Va errno 529has to be checked against the first value. 530.Ss Utility functions 531The following functions are provided as part of the 532.Nm 533API to simplify the creation of a variety of tests. 534In particular, these are useful to write tests for command-line interfaces. 535.Pp 536.Ft void 537.Fo atf_utils_cat_file 538.Fa "const char *file" 539.Fa "const char *prefix" 540.Fc 541.Bd -offset indent 542Prints the contents of 543.Fa file 544to the standard output, prefixing every line with the string in 545.Fa prefix . 546.Ed 547.Pp 548.Ft bool 549.Fo atf_utils_compare_file 550.Fa "const char *file" 551.Fa "const char *contents" 552.Fc 553.Bd -offset indent 554Returns true if the given 555.Fa file 556matches exactly the expected inlined 557.Fa contents . 558.Ed 559.Pp 560.Ft void 561.Fo atf_utils_copy_file 562.Fa "const char *source" 563.Fa "const char *destination" 564.Fc 565.Bd -offset indent 566Copies the file 567.Fa source 568to 569.Fa destination . 570The permissions of the file are preserved during the code. 571.Ed 572.Pp 573.Ft void 574.Fo atf_utils_create_file 575.Fa "const char *file" 576.Fa "const char *contents" 577.Fa "..." 578.Fc 579.Bd -offset indent 580Creates 581.Fa file 582with the text given in 583.Fa contents , 584which is a formatting string that uses the rest of the variable arguments. 585.Ed 586.Pp 587.Ft void 588.Fo atf_utils_file_exists 589.Fa "const char *file" 590.Fc 591.Bd -offset indent 592Checks if 593.Fa file 594exists. 595.Ed 596.Pp 597.Ft pid_t 598.Fo atf_utils_fork 599.Fa "void" 600.Fc 601.Bd -offset indent 602Forks a process and redirects the standard output and standard error of the 603child to files for later validation with 604.Fn atf_utils_wait . 605Fails the test case if the fork fails, so this does not return an error. 606.Ed 607.Pp 608.Ft void 609.Fo atf_utils_free_charpp 610.Fa "char **argv" 611.Fc 612.Bd -offset indent 613Frees a dynamically-allocated array of dynamically-allocated strings. 614.Ed 615.Pp 616.Ft bool 617.Fo atf_utils_grep_file 618.Fa "const char *regexp" 619.Fa "const char *file" 620.Fa "..." 621.Fc 622.Bd -offset indent 623Searches for the 624.Fa regexp , 625which is a formatting string representing the regular expression, 626in the 627.Fa file . 628The variable arguments are used to construct the regular expression. 629.Ed 630.Pp 631.Ft bool 632.Fo atf_utils_grep_string 633.Fa "const char *regexp" 634.Fa "const char *str" 635.Fa "..." 636.Fc 637.Bd -offset indent 638Searches for the 639.Fa regexp , 640which is a formatting string representing the regular expression, 641in the literal string 642.Fa str . 643The variable arguments are used to construct the regular expression. 644.Ed 645.Pp 646.Ft char * 647.Fo atf_utils_readline 648.Fa "int fd" 649.Fc 650.Bd -offset indent 651Reads a line from the file descriptor 652.Fa fd . 653The line, if any, is returned as a dynamically-allocated buffer that must be 654released with 655.Xr free 3 . 656If there was nothing to read, returns 657.Sq NULL . 658.Ed 659.Pp 660.Ft void 661.Fo atf_utils_redirect 662.Fa "const int fd" 663.Fa "const char *file" 664.Fc 665.Bd -offset indent 666Redirects the given file descriptor 667.Fa fd 668to 669.Fa file . 670This function exits the process in case of an error and does not properly mark 671the test case as failed. 672As a result, it should only be used in subprocesses of the test case; specially 673those spawned by 674.Fn atf_utils_fork . 675.Ed 676.Pp 677.Ft void 678.Fo atf_utils_wait 679.Fa "const pid_t pid" 680.Fa "const int expected_exit_status" 681.Fa "const char *expected_stdout" 682.Fa "const char *expected_stderr" 683.Fc 684.Bd -offset indent 685Waits and validates the result of a subprocess spawned with 686.Fn atf_utils_wait . 687The validation involves checking that the subprocess exited cleanly and returned 688the code specified in 689.Fa expected_exit_status 690and that its standard output and standard error match the strings given in 691.Fa expected_stdout 692and 693.Fa expected_stderr . 694.Pp 695If any of the 696.Fa expected_stdout 697or 698.Fa expected_stderr 699strings are prefixed with 700.Sq save: , 701then they specify the name of the file into which to store the stdout or stderr 702of the subprocess, and no comparison is performed. 703.Ed 704.Sh EXAMPLES 705The following shows a complete test program with a single test case that 706validates the addition operator: 707.Bd -literal -offset indent 708#include <atf-c.h> 709 710ATF_TC(addition); 711ATF_TC_HEAD(addition, tc) 712{ 713 atf_tc_set_md_var(tc, "descr", 714 "Sample tests for the addition operator"); 715} 716ATF_TC_BODY(addition, tc) 717{ 718 ATF_CHECK_EQ(0 + 0, 0); 719 ATF_CHECK_EQ(0 + 1, 1); 720 ATF_CHECK_EQ(1 + 0, 1); 721 722 ATF_CHECK_EQ(1 + 1, 2); 723 724 ATF_CHECK_EQ(100 + 200, 300); 725} 726 727ATF_TC(string_formatting); 728ATF_TC_HEAD(string_formatting, tc) 729{ 730 atf_tc_set_md_var(tc, "descr", 731 "Sample tests for the snprintf"); 732} 733ATF_TC_BODY(string_formatting, tc) 734{ 735 char buf[1024]; 736 snprintf(buf, sizeof(buf), "a %s", "string"); 737 ATF_CHECK_STREQ_MSG("a string", buf, "%s is not working"); 738} 739 740ATF_TC(open_failure); 741ATF_TC_HEAD(open_failure, tc) 742{ 743 atf_tc_set_md_var(tc, "descr", 744 "Sample tests for the open function"); 745} 746ATF_TC_BODY(open_failure, tc) 747{ 748 ATF_CHECK_ERRNO(ENOENT, open("non-existent", O_RDONLY) == -1); 749} 750 751ATF_TC(known_bug); 752ATF_TC_HEAD(known_bug, tc) 753{ 754 atf_tc_set_md_var(tc, "descr", 755 "Reproduces a known bug"); 756} 757ATF_TC_BODY(known_bug, tc) 758{ 759 atf_tc_expect_fail("See bug number foo/bar"); 760 ATF_CHECK_EQ(3, 1 + 1); 761 atf_tc_expect_pass(); 762 ATF_CHECK_EQ(3, 1 + 2); 763} 764 765ATF_TP_ADD_TCS(tp) 766{ 767 ATF_TP_ADD_TC(tp, addition); 768 ATF_TP_ADD_TC(tp, string_formatting); 769 ATF_TP_ADD_TC(tp, open_failure); 770 ATF_TP_ADD_TC(tp, known_bug); 771 772 return atf_no_error(); 773} 774.Ed 775.Sh SEE ALSO 776.Xr atf-test-program 1 , 777.Xr atf-test-case 4 , 778.Xr atf 7 779