Date: Sat, 1 Nov 2014 11:17:55 +0000 (UTC) From: Julio Merino <jmmv@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r273929 - in head: . contrib/atf contrib/atf/atf-c contrib/atf/atf-c++ contrib/atf/atf-c++/detail contrib/atf/atf-c/detail contrib/atf/atf-sh contrib/atf/doc contrib/atf/test-programs l... Message-ID: <201411011117.sA1BHtuQ065740@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: jmmv Date: Sat Nov 1 11:17:54 2014 New Revision: 273929 URL: https://svnweb.freebsd.org/changeset/base/273929 Log: MFV: Import atf-0.21. Added: head/contrib/atf/atf-c++/atf-c++.3 - copied unchanged from r273873, vendor/atf/dist/atf-c++/atf-c++.3 head/contrib/atf/atf-c/atf-c.3 - copied unchanged from r273873, vendor/atf/dist/atf-c/atf-c.3 head/contrib/atf/atf-sh/atf-sh.3 - copied unchanged from r273873, vendor/atf/dist/atf-sh/atf-sh.3 head/contrib/atf/config.h - copied, changed from r273922, head/contrib/atf/bconfig.h head/contrib/atf/doc/atf.7.in - copied unchanged from r273873, vendor/atf/dist/doc/atf.7.in Deleted: head/contrib/atf/atf-c++/config.cpp head/contrib/atf/atf-c++/config.hpp head/contrib/atf/atf-c++/config_test.cpp head/contrib/atf/atf-c++/detail/sanity_test.cpp head/contrib/atf/atf-c/config.c head/contrib/atf/atf-c/config.h head/contrib/atf/atf-c/config_test.c head/contrib/atf/bconfig.h Modified: head/ObsoleteFiles.inc head/contrib/atf/FREEBSD-Xlist head/contrib/atf/NEWS head/contrib/atf/atf-c++.hpp head/contrib/atf/atf-c++/Kyuafile head/contrib/atf/atf-c++/atf_c++_test.cpp head/contrib/atf/atf-c++/build.cpp head/contrib/atf/atf-c++/build.hpp head/contrib/atf/atf-c++/build_test.cpp head/contrib/atf/atf-c++/check.cpp head/contrib/atf/atf-c++/check.hpp head/contrib/atf/atf-c++/check_test.cpp head/contrib/atf/atf-c++/detail/Kyuafile head/contrib/atf/atf-c++/detail/application.cpp head/contrib/atf/atf-c++/detail/application.hpp head/contrib/atf/atf-c++/detail/application_test.cpp head/contrib/atf/atf-c++/detail/auto_array.hpp head/contrib/atf/atf-c++/detail/auto_array_test.cpp head/contrib/atf/atf-c++/detail/env.cpp head/contrib/atf/atf-c++/detail/env.hpp head/contrib/atf/atf-c++/detail/env_test.cpp head/contrib/atf/atf-c++/detail/exceptions.cpp head/contrib/atf/atf-c++/detail/exceptions.hpp head/contrib/atf/atf-c++/detail/exceptions_test.cpp head/contrib/atf/atf-c++/detail/fs.cpp head/contrib/atf/atf-c++/detail/fs.hpp head/contrib/atf/atf-c++/detail/fs_test.cpp head/contrib/atf/atf-c++/detail/process.cpp head/contrib/atf/atf-c++/detail/process.hpp head/contrib/atf/atf-c++/detail/process_test.cpp head/contrib/atf/atf-c++/detail/sanity.hpp head/contrib/atf/atf-c++/detail/test_helpers.cpp head/contrib/atf/atf-c++/detail/test_helpers.hpp head/contrib/atf/atf-c++/detail/text.cpp head/contrib/atf/atf-c++/detail/text.hpp head/contrib/atf/atf-c++/detail/text_test.cpp head/contrib/atf/atf-c++/detail/version_helper.cpp head/contrib/atf/atf-c++/macros.hpp head/contrib/atf/atf-c++/macros_hpp_test.cpp head/contrib/atf/atf-c++/macros_test.cpp head/contrib/atf/atf-c++/pkg_config_test.sh head/contrib/atf/atf-c++/tests.cpp head/contrib/atf/atf-c++/tests.hpp head/contrib/atf/atf-c++/tests_test.cpp head/contrib/atf/atf-c++/unused_test.cpp head/contrib/atf/atf-c++/utils.cpp head/contrib/atf/atf-c++/utils.hpp head/contrib/atf/atf-c++/utils_test.cpp head/contrib/atf/atf-c.h head/contrib/atf/atf-c/Kyuafile head/contrib/atf/atf-c/atf_c_test.c head/contrib/atf/atf-c/build.c head/contrib/atf/atf-c/build.h head/contrib/atf/atf-c/build_test.c head/contrib/atf/atf-c/check.c head/contrib/atf/atf-c/check.h head/contrib/atf/atf-c/check_test.c head/contrib/atf/atf-c/defs.h.in head/contrib/atf/atf-c/detail/dynstr.c head/contrib/atf/atf-c/detail/dynstr.h head/contrib/atf/atf-c/detail/dynstr_test.c head/contrib/atf/atf-c/detail/env.c head/contrib/atf/atf-c/detail/env.h head/contrib/atf/atf-c/detail/env_test.c head/contrib/atf/atf-c/detail/fs.c head/contrib/atf/atf-c/detail/fs.h head/contrib/atf/atf-c/detail/fs_test.c head/contrib/atf/atf-c/detail/list.c head/contrib/atf/atf-c/detail/list.h head/contrib/atf/atf-c/detail/list_test.c head/contrib/atf/atf-c/detail/map.c head/contrib/atf/atf-c/detail/map.h head/contrib/atf/atf-c/detail/map_test.c head/contrib/atf/atf-c/detail/process.c head/contrib/atf/atf-c/detail/process.h head/contrib/atf/atf-c/detail/process_helpers.c head/contrib/atf/atf-c/detail/process_test.c head/contrib/atf/atf-c/detail/sanity.c head/contrib/atf/atf-c/detail/sanity.h head/contrib/atf/atf-c/detail/sanity_test.c head/contrib/atf/atf-c/detail/test_helpers.c head/contrib/atf/atf-c/detail/test_helpers.h head/contrib/atf/atf-c/detail/text.c head/contrib/atf/atf-c/detail/text.h head/contrib/atf/atf-c/detail/text_test.c head/contrib/atf/atf-c/detail/tp_main.c head/contrib/atf/atf-c/detail/user.c head/contrib/atf/atf-c/detail/user.h head/contrib/atf/atf-c/detail/user_test.c head/contrib/atf/atf-c/detail/version_helper.c head/contrib/atf/atf-c/error.c head/contrib/atf/atf-c/error.h head/contrib/atf/atf-c/error_fwd.h head/contrib/atf/atf-c/error_test.c head/contrib/atf/atf-c/h_build.h head/contrib/atf/atf-c/macros.h head/contrib/atf/atf-c/macros_h_test.c head/contrib/atf/atf-c/macros_test.c head/contrib/atf/atf-c/pkg_config_test.sh head/contrib/atf/atf-c/tc.c head/contrib/atf/atf-c/tc.h head/contrib/atf/atf-c/tc_test.c head/contrib/atf/atf-c/tp.c head/contrib/atf/atf-c/tp.h head/contrib/atf/atf-c/tp_test.c head/contrib/atf/atf-c/unused_test.c head/contrib/atf/atf-c/utils.c head/contrib/atf/atf-c/utils.h head/contrib/atf/atf-c/utils_test.c head/contrib/atf/atf-sh/atf-check.1 head/contrib/atf/atf-sh/atf-check.cpp head/contrib/atf/atf-sh/atf-check_test.sh head/contrib/atf/atf-sh/atf-sh.1 head/contrib/atf/atf-sh/atf-sh.cpp head/contrib/atf/atf-sh/atf_check_test.sh head/contrib/atf/atf-sh/config_test.sh head/contrib/atf/atf-sh/integration_test.sh head/contrib/atf/atf-sh/libatf-sh.subr head/contrib/atf/atf-sh/misc_helpers.sh head/contrib/atf/atf-sh/normalize_test.sh head/contrib/atf/atf-sh/tc_test.sh head/contrib/atf/atf-sh/tp_test.sh head/contrib/atf/doc/atf-test-case.4 head/contrib/atf/doc/atf-test-program.1 head/contrib/atf/test-programs/c_helpers.c head/contrib/atf/test-programs/common.sh head/contrib/atf/test-programs/config_test.sh head/contrib/atf/test-programs/cpp_helpers.cpp head/contrib/atf/test-programs/expect_test.sh head/contrib/atf/test-programs/meta_data_test.sh head/contrib/atf/test-programs/result_test.sh head/contrib/atf/test-programs/sh_helpers.sh head/contrib/atf/test-programs/srcdir_test.sh head/lib/atf/Makefile.inc head/lib/atf/common.mk head/lib/atf/libatf-c++/Makefile head/lib/atf/libatf-c++/tests/Makefile head/lib/atf/libatf-c++/tests/detail/Makefile head/lib/atf/libatf-c/Makefile head/lib/atf/libatf-c/tests/Makefile head/lib/atf/libatf-c/tests/detail/Makefile head/libexec/atf/atf-check/Makefile head/libexec/atf/atf-sh/Makefile head/libexec/atf/atf-sh/tests/Makefile head/share/man/man7/Makefile head/tools/build/mk/OptionalObsoleteFiles.inc Directory Properties: head/contrib/atf/ (props changed) Modified: head/ObsoleteFiles.inc ============================================================================== --- head/ObsoleteFiles.inc Sat Nov 1 11:07:59 2014 (r273928) +++ head/ObsoleteFiles.inc Sat Nov 1 11:17:54 2014 (r273929) @@ -374,7 +374,6 @@ OLD_FILES+=usr/share/man/man1/atf-report OLD_FILES+=usr/share/man/man1/atf-run.1.gz OLD_FILES+=usr/share/man/man1/atf-version.1.gz OLD_FILES+=usr/share/man/man5/atf-formats.5.gz -OLD_FILES+=usr/share/man/man7/atf.7.gz OLD_FILES+=usr/share/xml/atf/tests-results.dtd OLD_FILES+=usr/share/xsl/atf/tests-results.xsl # 20131009: freebsd-version moved from /libexec to /bin Modified: head/contrib/atf/FREEBSD-Xlist ============================================================================== --- head/contrib/atf/FREEBSD-Xlist Sat Nov 1 11:07:59 2014 (r273928) +++ head/contrib/atf/FREEBSD-Xlist Sat Nov 1 11:17:54 2014 (r273929) @@ -1,22 +1,12 @@ -*/*/Atffile */*/Makefile* -*/Atffile */Makefile* */*.m4 */*.pc.in -Atffile INSTALL Makefile* aclocal.m4 admin/ -atf-config/ -atf-report/ -atf-run/ -atf-version/ -bconfig.h.in +config.h.in bootstrap/ configure* -doc/atf-formats.5 -doc/atf.7.in m4/ -tools/ Modified: head/contrib/atf/NEWS ============================================================================== --- head/contrib/atf/NEWS Sat Nov 1 11:07:59 2014 (r273928) +++ head/contrib/atf/NEWS Sat Nov 1 11:17:54 2014 (r273929) @@ -1,6 +1,62 @@ Major changes between releases Automated Testing Framework =========================================================================== +Changes in version 0.21 +*********************** + +Released on October 23rd, 2014. + +* Restored the atf(7) manual page to serve as a reference to all the other + manual pages shipped by ATF. + +* Added the -s flag to atf-sh to support specifying the shell interpreter + to be used. + +* Removed ATF_WORKDIR. The only remaining consumers have been converted to + use the standard TMPDIR environment variable. As a benefit, and because + Kyua forces the TMPDIR to live within the test case's work directory, + any stale files left behind by ATF will be automatically cleaned up. + +* Documented the environment variables recognized by each component in the + relevant manual pages. This information was lost with the atf-config(1) + removal. + +* Added a new "require.diskspace" metadata property to test cases so that + they can specify the minimum amount of disk space required for the test + to run. + +* Renamed the atf-{c,c++,sh}-api(3) manual pages to atf-{c,c++,sh}(3) for + discoverability purposes. Symbolic links are provided for the time + being to still make the old names visible. + +* Issue #5: Recommend the (expected, actual) idiom for calls to the test + macros in the manual pages. + +* Issue #7: Stopped catching unhandled exceptions in atf-c++ tests. This + propagates the crash to the caller, which in turn allows it to obtain + proper debugging information. In particular, Kyua should now be able to + extract a stacktrace pinpointing the problem. + +* Issue #8: Fixed atf-c/macros_test:use test failures spotted by the clang + that ships with FreeBSD 11.0-CURRENT. + +* Issue #12: Improved documentation of atf-sh(3) and atf-check(1) by better + explaining how they relate to each other. + +* Issue #14: Stopped setting 'set -e' in atf-sh. This setting was + initially added as a way to enable a "strict" mode in the library and to + make test cases fail fast when they run unprotected commands. However, + doing so in the library is surprising as the responsibility of enabling + 'set -e' should be on the user's code. Also, 'set -e' introduces + inconsistent behavior on subshells and users do not expect that. + +* Issue #15: Fixed atf_utils_{fork,wait} to support nested calls. + +* Issue #16: Fixed test failures (by removing a long-standing hack) on + systems that lack \e support in printf(1). + +* Issue #19: Removed stale references to atf-config and atf-run. + Changes in version 0.20 *********************** Modified: head/contrib/atf/atf-c++.hpp ============================================================================== --- head/contrib/atf/atf-c++.hpp Sat Nov 1 11:07:59 2014 (r273928) +++ head/contrib/atf/atf-c++.hpp Sat Nov 1 11:17:54 2014 (r273929) @@ -1,6 +1,3 @@ -// -// Automated Testing Framework (atf) -// // Copyright (c) 2007 The NetBSD Foundation, Inc. // All rights reserved. // @@ -25,12 +22,11 @@ // IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR // OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN // IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -// -#if !defined(_ATF_CXX_HPP_) -#define _ATF_CXX_HPP_ +#if !defined(ATF_CXX_HPP) +#define ATF_CXX_HPP #include <atf-c++/macros.hpp> #include <atf-c++/utils.hpp> -#endif // !defined(_ATF_CXX_HPP_) +#endif // !defined(ATF_CXX_HPP) Modified: head/contrib/atf/atf-c++/Kyuafile ============================================================================== --- head/contrib/atf/atf-c++/Kyuafile Sat Nov 1 11:07:59 2014 (r273928) +++ head/contrib/atf/atf-c++/Kyuafile Sat Nov 1 11:17:54 2014 (r273929) @@ -5,7 +5,6 @@ test_suite("atf") atf_test_program{name="atf_c++_test"} atf_test_program{name="build_test"} atf_test_program{name="check_test"} -atf_test_program{name="config_test"} atf_test_program{name="macros_test"} atf_test_program{name="pkg_config_test"} atf_test_program{name="tests_test"} Copied: head/contrib/atf/atf-c++/atf-c++.3 (from r273873, vendor/atf/dist/atf-c++/atf-c++.3) ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/contrib/atf/atf-c++/atf-c++.3 Sat Nov 1 11:17:54 2014 (r273929, copy of r273873, vendor/atf/dist/atf-c++/atf-c++.3) @@ -0,0 +1,649 @@ +.\" Copyright (c) 2008 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND +.\" CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, +.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS BE LIABLE FOR ANY +.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE +.\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER +.\" IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR +.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.Dd October 13, 2014 +.Dt ATF-C++ 3 +.Os +.Sh NAME +.Nm atf-c++ , +.Nm ATF_ADD_TEST_CASE , +.Nm ATF_CHECK_ERRNO , +.Nm ATF_FAIL , +.Nm ATF_INIT_TEST_CASES , +.Nm ATF_PASS , +.Nm ATF_REQUIRE , +.Nm ATF_REQUIRE_EQ , +.Nm ATF_REQUIRE_ERRNO , +.Nm ATF_REQUIRE_IN , +.Nm ATF_REQUIRE_MATCH , +.Nm ATF_REQUIRE_NOT_IN , +.Nm ATF_REQUIRE_THROW , +.Nm ATF_REQUIRE_THROW_RE , +.Nm ATF_SKIP , +.Nm ATF_TEST_CASE , +.Nm ATF_TEST_CASE_BODY , +.Nm ATF_TEST_CASE_CLEANUP , +.Nm ATF_TEST_CASE_HEAD , +.Nm ATF_TEST_CASE_NAME , +.Nm ATF_TEST_CASE_USE , +.Nm ATF_TEST_CASE_WITH_CLEANUP , +.Nm ATF_TEST_CASE_WITHOUT_HEAD , +.Nm atf::utils::cat_file , +.Nm atf::utils::compare_file , +.Nm atf::utils::copy_file , +.Nm atf::utils::create_file , +.Nm atf::utils::file_exists , +.Nm atf::utils::fork , +.Nm atf::utils::grep_collection , +.Nm atf::utils::grep_file , +.Nm atf::utils::grep_string , +.Nm atf::utils::redirect , +.Nm atf::utils::wait +.Nd C++ API to write ATF-based test programs +.Sh SYNOPSIS +.In atf-c++.hpp +.Fn ATF_ADD_TEST_CASE "tcs" "name" +.Fn ATF_CHECK_ERRNO "expected_errno" "bool_expression" +.Fn ATF_FAIL "reason" +.Fn ATF_INIT_TEST_CASES "tcs" +.Fn ATF_PASS +.Fn ATF_REQUIRE "expression" +.Fn ATF_REQUIRE_EQ "expected_expression" "actual_expression" +.Fn ATF_REQUIRE_ERRNO "expected_errno" "bool_expression" +.Fn ATF_REQUIRE_IN "element" "collection" +.Fn ATF_REQUIRE_MATCH "regexp" "string_expression" +.Fn ATF_REQUIRE_NOT_IN "element" "collection" +.Fn ATF_REQUIRE_THROW "expected_exception" "statement" +.Fn ATF_REQUIRE_THROW_RE "expected_exception" "regexp" "statement" +.Fn ATF_SKIP "reason" +.Fn ATF_TEST_CASE "name" +.Fn ATF_TEST_CASE_BODY "name" +.Fn ATF_TEST_CASE_CLEANUP "name" +.Fn ATF_TEST_CASE_HEAD "name" +.Fn ATF_TEST_CASE_NAME "name" +.Fn ATF_TEST_CASE_USE "name" +.Fn ATF_TEST_CASE_WITH_CLEANUP "name" +.Fn ATF_TEST_CASE_WITHOUT_HEAD "name" +.Ft void +.Fo atf::utils::cat_file +.Fa "const std::string& path" +.Fa "const std::string& prefix" +.Fc +.Ft bool +.Fo atf::utils::compare_file +.Fa "const std::string& path" +.Fa "const std::string& contents" +.Fc +.Ft void +.Fo atf::utils::copy_file +.Fa "const std::string& source" +.Fa "const std::string& destination" +.Fc +.Ft void +.Fo atf::utils::create_file +.Fa "const std::string& path" +.Fa "const std::string& contents" +.Fc +.Ft void +.Fo atf::utils::file_exists +.Fa "const std::string& path" +.Fc +.Ft pid_t +.Fo atf::utils::fork +.Fa "void" +.Fc +.Ft bool +.Fo atf::utils::grep_collection +.Fa "const std::string& regexp" +.Fa "const Collection& collection" +.Fc +.Ft bool +.Fo atf::utils::grep_file +.Fa "const std::string& regexp" +.Fa "const std::string& path" +.Fc +.Ft bool +.Fo atf::utils::grep_string +.Fa "const std::string& regexp" +.Fa "const std::string& path" +.Fc +.Ft void +.Fo atf::utils::redirect +.Fa "const int fd" +.Fa "const std::string& path" +.Fc +.Ft void +.Fo atf::utils::wait +.Fa "const pid_t pid" +.Fa "const int expected_exit_status" +.Fa "const std::string& expected_stdout" +.Fa "const std::string& expected_stderr" +.Fc +.Sh DESCRIPTION +ATF provides a C++ programming interface to implement test programs. +C++-based test programs follow this template: +.Bd -literal -offset indent +extern "C" { +.Ns ... C-specific includes go here ... +} + +.Ns ... C++-specific includes go here ... + +#include <atf-c++.hpp> + +ATF_TEST_CASE(tc1); +ATF_TEST_CASE_HEAD(tc1) +{ + ... first test case's header ... +} +ATF_TEST_CASE_BODY(tc1) +{ + ... first test case's body ... +} + +ATF_TEST_CASE_WITH_CLEANUP(tc2); +ATF_TEST_CASE_HEAD(tc2) +{ + ... second test case's header ... +} +ATF_TEST_CASE_BODY(tc2) +{ + ... second test case's body ... +} +ATF_TEST_CASE_CLEANUP(tc2) +{ + ... second test case's cleanup ... +} + +ATF_TEST_CASE(tc3); +ATF_TEST_CASE_BODY(tc3) +{ + ... third test case's body ... +} + +.Ns ... additional test cases ... + +ATF_INIT_TEST_CASES(tcs) +{ + ATF_ADD_TEST_CASE(tcs, tc1); + ATF_ADD_TEST_CASE(tcs, tc2); + ATF_ADD_TEST_CASE(tcs, tc3); + ... add additional test cases ... +} +.Ed +.Ss Definition of test cases +Test cases have an identifier and are composed of three different parts: +the header, the body and an optional cleanup routine, all of which are +described in +.Xr atf-test-case 4 . +To define test cases, one can use the +.Fn ATF_TEST_CASE , +.Fn ATF_TEST_CASE_WITH_CLEANUP +or the +.Fn ATF_TEST_CASE_WITHOUT_HEAD +macros, which take a single parameter specifiying the test case's +name. +.Fn ATF_TEST_CASE , +requires to define a head and a body for the test case, +.Fn ATF_TEST_CASE_WITH_CLEANUP +requires to define a head, a body and a cleanup for the test case and +.Fn ATF_TEST_CASE_WITHOUT_HEAD +requires only a body for the test case. +It is important to note that these +.Em do not +set the test case up for execution when the program is run. +In order to do so, a later registration is needed through the +.Fn ATF_ADD_TEST_CASE +macro detailed in +.Sx Program initialization . +.Pp +Later on, one must define the three parts of the body by means of three +functions. +Their headers are given by the +.Fn ATF_TEST_CASE_HEAD , +.Fn ATF_TEST_CASE_BODY +and +.Fn ATF_TEST_CASE_CLEANUP +macros, all of which take the test case's name. +Following each of these, a block of code is expected, surrounded by the +opening and closing brackets. +.Pp +Additionally, the +.Fn ATF_TEST_CASE_NAME +macro can be used to obtain the name of the class corresponding to a +particular test case, as the name is internally manged by the library to +prevent clashes with other user identifiers. +Similarly, the +.Fn ATF_TEST_CASE_USE +macro can be executed on a particular test case to mark it as "used" and +thus prevent compiler warnings regarding unused symbols. +Note that +.Em you should never have to use these macros during regular operation. +.Ss Program initialization +The library provides a way to easily define the test program's +.Fn main +function. +You should never define one on your own, but rely on the +library to do it for you. +This is done by using the +.Fn ATF_INIT_TEST_CASES +macro, which is passed the name of the list that will hold the test cases. +This name can be whatever you want as long as it is a valid variable value. +.Pp +After the macro, you are supposed to provide the body of a function, which +should only use the +.Fn ATF_ADD_TEST_CASE +macro to register the test cases the test program will execute. +The first parameter of this macro matches the name you provided in the +former call. +.Ss Header definitions +The test case's header can define the meta-data by using the +.Fn set_md_var +method, which takes two parameters: the first one specifies the +meta-data variable to be set and the second one specifies its value. +Both of them are strings. +.Ss Configuration variables +The test case has read-only access to the current configuration variables +by means of the +.Ft bool +.Fn has_config_var +and the +.Ft std::string +.Fn get_config_var +methods, which can be called in any of the three parts of a test case. +.Ss Access to the source directory +It is possible to get the path to the test case's source directory from any +of its three components by querying the +.Sq srcdir +configuration variable. +.Ss Requiring programs +Aside from the +.Va require.progs +meta-data variable available in the header only, one can also check for +additional programs in the test case's body by using the +.Fn require_prog +function, which takes the base name or full path of a single binary. +Relative paths are forbidden. +If it is not found, the test case will be automatically skipped. +.Ss Test case finalization +The test case finalizes either when the body reaches its end, at which +point the test is assumed to have +.Em passed , +or at any explicit call to +.Fn ATF_PASS , +.Fn ATF_FAIL +or +.Fn ATF_SKIP . +These three macros terminate the execution of the test case immediately. +The cleanup routine will be processed afterwards in a completely automated +way, regardless of the test case's termination reason. +.Pp +.Fn ATF_PASS +does not take any parameters. +.Fn ATF_FAIL +and +.Fn ATF_SKIP +take a single string that describes why the test case failed or +was skipped, respectively. +It is very important to provide a clear error message in both cases so that +the user can quickly know why the test did not pass. +.Ss Expectations +Everything explained in the previous section changes when the test case +expectations are redefined by the programmer. +.Pp +Each test case has an internal state called +.Sq expect +that describes what the test case expectations are at any point in time. +The value of this property can change during execution by any of: +.Bl -tag -width indent +.It Fn expect_death "reason" +Expects the test case to exit prematurely regardless of the nature of the +exit. +.It Fn expect_exit "exitcode" "reason" +Expects the test case to exit cleanly. +If +.Va exitcode +is not +.Sq -1 , +the runtime engine will validate that the exit code of the test case +matches the one provided in this call. +Otherwise, the exact value will be ignored. +.It Fn expect_fail "reason" +Any failure (be it fatal or non-fatal) raised in this mode is recorded. +However, such failures do not report the test case as failed; instead, the +test case finalizes cleanly and is reported as +.Sq expected failure ; +this report includes the provided +.Fa reason +as part of it. +If no error is raised while running in this mode, then the test case is +reported as +.Sq failed . +.Pp +This mode is useful to reproduce actual known bugs in tests. +Whenever the developer fixes the bug later on, the test case will start +reporting a failure, signaling the developer that the test case must be +adjusted to the new conditions. +In this situation, it is useful, for example, to set +.Fa reason +as the bug number for tracking purposes. +.It Fn expect_pass +This is the normal mode of execution. +In this mode, any failure is reported as such to the user and the test case +is marked as +.Sq failed . +.It Fn expect_race "reason" +Any failure or timeout during the execution of the test case will be +considered as if a race condition has been triggered and reported as such. +If no problems arise, the test will continue execution as usual. +.It Fn expect_signal "signo" "reason" +Expects the test case to terminate due to the reception of a signal. +If +.Va signo +is not +.Sq -1 , +the runtime engine will validate that the signal that terminated the test +case matches the one provided in this call. +Otherwise, the exact value will be ignored. +.It Fn expect_timeout "reason" +Expects the test case to execute for longer than its timeout. +.El +.Ss Helper macros for common checks +The library provides several macros that are very handy in multiple +situations. +These basically check some condition after executing a given statement or +processing a given expression and, if the condition is not met, they +automatically call +.Fn ATF_FAIL +with an appropriate error message. +.Pp +.Fn ATF_REQUIRE +takes an expression and raises a failure if it evaluates to false. +.Pp +.Fn ATF_REQUIRE_EQ +takes two expressions and raises a failure if the two do not evaluate to +the same exact value. +The common style is to put the expected value in the first parameter and the +actual value in the second parameter. +.Pp +.Fn ATF_REQUIRE_IN +takes an element and a collection and validates that the element is present in +the collection. +.Pp +.Fn ATF_REQUIRE_MATCH +takes a regular expression and a string and raises a failure if the regular +expression does not match the string. +.Pp +.Fn ATF_REQUIRE_NOT_IN +takes an element and a collection and validates that the element is not present +in the collection. +.Pp +.Fn ATF_REQUIRE_THROW +takes the name of an exception and a statement and raises a failure if +the statement does not throw the specified exception. +.Fn ATF_REQUIRE_THROW_RE +takes the name of an exception, a regular expresion and a statement and raises a +failure if the statement does not throw the specified exception and if the +message of the exception does not match the regular expression. +.Pp +.Fn ATF_CHECK_ERRNO +and +.Fn ATF_REQUIRE_ERRNO +take, first, the error code that the check is expecting to find in the +.Va errno +variable and, second, a boolean expression that, if evaluates to true, +means that a call failed and +.Va errno +has to be checked against the first value. +.Ss Utility functions +The following functions are provided as part of the +.Nm +API to simplify the creation of a variety of tests. +In particular, these are useful to write tests for command-line interfaces. +.Pp +.Ft void +.Fo atf::utils::cat_file +.Fa "const std::string& path" +.Fa "const std::string& prefix" +.Fc +.Bd -ragged -offset indent +Prints the contents of +.Fa path +to the standard output, prefixing every line with the string in +.Fa prefix . +.Ed +.Pp +.Ft bool +.Fo atf::utils::compare_file +.Fa "const std::string& path" +.Fa "const std::string& contents" +.Fc +.Bd -ragged -offset indent +Returns true if the given +.Fa path +matches exactly the expected inlined +.Fa contents . +.Ed +.Pp +.Ft void +.Fo atf::utils::copy_file +.Fa "const std::string& source" +.Fa "const std::string& destination" +.Fc +.Bd -ragged -offset indent +Copies the file +.Fa source +to +.Fa destination . +The permissions of the file are preserved during the code. +.Ed +.Pp +.Ft void +.Fo atf::utils::create_file +.Fa "const std::string& path" +.Fa "const std::string& contents" +.Fc +.Bd -ragged -offset indent +Creates +.Fa file +with the text given in +.Fa contents . +.Ed +.Pp +.Ft void +.Fo atf::utils::file_exists +.Fa "const std::string& path" +.Fc +.Bd -ragged -offset indent +Checks if +.Fa path +exists. +.Ed +.Pp +.Ft pid_t +.Fo atf::utils::fork +.Fa "void" +.Fc +.Bd -ragged -offset indent +Forks a process and redirects the standard output and standard error of the +child to files for later validation with +.Fn atf::utils::wait . +Fails the test case if the fork fails, so this does not return an error. +.Ed +.Pp +.Ft bool +.Fo atf::utils::grep_collection +.Fa "const std::string& regexp" +.Fa "const Collection& collection" +.Fc +.Bd -ragged -offset indent +Searches for the regular expression +.Fa regexp +in any of the strings contained in the +.Fa collection . +This is a template that accepts any one-dimensional container of strings. +.Ed +.Pp +.Ft bool +.Fo atf::utils::grep_file +.Fa "const std::string& regexp" +.Fa "const std::string& path" +.Fc +.Bd -ragged -offset indent +Searches for the regular expression +.Fa regexp +in the file +.Fa path . +The variable arguments are used to construct the regular expression. +.Ed +.Pp +.Ft bool +.Fo atf::utils::grep_string +.Fa "const std::string& regexp" +.Fa "const std::string& str" +.Fc +.Bd -ragged -offset indent +Searches for the regular expression +.Fa regexp +in the string +.Fa str . +.Ed +.Ft void +.Fo atf::utils::redirect +.Fa "const int fd" +.Fa "const std::string& path" +.Fc +.Bd -ragged -offset indent +Redirects the given file descriptor +.Fa fd +to the file +.Fa path . +This function exits the process in case of an error and does not properly mark +the test case as failed. +As a result, it should only be used in subprocesses of the test case; specially +those spawned by +.Fn atf::utils::fork . +.Ed +.Pp +.Ft void +.Fo atf::utils::wait +.Fa "const pid_t pid" +.Fa "const int expected_exit_status" +.Fa "const std::string& expected_stdout" +.Fa "const std::string& expected_stderr" +.Fc +.Bd -ragged -offset indent +Waits and validates the result of a subprocess spawned with +.Fn atf::utils::wait . +The validation involves checking that the subprocess exited cleanly and returned +the code specified in +.Fa expected_exit_status +and that its standard output and standard error match the strings given in +.Fa expected_stdout +and +.Fa expected_stderr . +.Pp +If any of the +.Fa expected_stdout +or +.Fa expected_stderr +strings are prefixed with +.Sq save: , +then they specify the name of the file into which to store the stdout or stderr +of the subprocess, and no comparison is performed. +.Ed +.Sh ENVIRONMENT +The following variables are recognized by +.Nm +but should not be overridden other than for testing purposes: +.Pp +.Bl -tag -width ATFXBUILDXCXXFLAGSXX -compact +.It Va ATF_BUILD_CC +Path to the C compiler. +.It Va ATF_BUILD_CFLAGS +C compiler flags. +.It Va ATF_BUILD_CPP +Path to the C/C++ preprocessor. +.It Va ATF_BUILD_CPPFLAGS +C/C++ preprocessor flags. +.It Va ATF_BUILD_CXX +Path to the C++ compiler. +.It Va ATF_BUILD_CXXFLAGS +C++ compiler flags. +.El +.Sh EXAMPLES +The following shows a complete test program with a single test case that +validates the addition operator: +.Bd -literal -offset indent +#include <atf-c++.hpp> + +ATF_TEST_CASE(addition); +ATF_TEST_CASE_HEAD(addition) +{ + set_md_var("descr", "Sample tests for the addition operator"); +} +ATF_TEST_CASE_BODY(addition) +{ + ATF_REQUIRE_EQ(0, 0 + 0); + ATF_REQUIRE_EQ(1, 0 + 1); + ATF_REQUIRE_EQ(1, 1 + 0); + + ATF_REQUIRE_EQ(2, 1 + 1); + + ATF_REQUIRE_EQ(300, 100 + 200); +} + +ATF_TEST_CASE(open_failure); +ATF_TEST_CASE_HEAD(open_failure) +{ + set_md_var("descr", "Sample tests for the open function"); +} +ATF_TEST_CASE_BODY(open_failure) +{ + ATF_REQUIRE_ERRNO(ENOENT, open("non-existent", O_RDONLY) == -1); +} + +ATF_TEST_CASE(known_bug); +ATF_TEST_CASE_HEAD(known_bug) +{ + set_md_var("descr", "Reproduces a known bug"); +} +ATF_TEST_CASE_BODY(known_bug) +{ + expect_fail("See bug number foo/bar"); + ATF_REQUIRE_EQ(3, 1 + 1); + expect_pass(); + ATF_REQUIRE_EQ(3, 1 + 2); +} + +ATF_INIT_TEST_CASES(tcs) +{ + ATF_ADD_TEST_CASE(tcs, addition); + ATF_ADD_TEST_CASE(tcs, open_failure); + ATF_ADD_TEST_CASE(tcs, known_bug); +} +.Ed +.Sh SEE ALSO +.Xr atf-test-program 1 , +.Xr atf-test-case 4 Modified: head/contrib/atf/atf-c++/atf_c++_test.cpp ============================================================================== --- head/contrib/atf/atf-c++/atf_c++_test.cpp Sat Nov 1 11:07:59 2014 (r273928) +++ head/contrib/atf/atf-c++/atf_c++_test.cpp Sat Nov 1 11:17:54 2014 (r273929) @@ -1,6 +1,3 @@ -// -// Automated Testing Framework (atf) -// // Copyright (c) 2009 The NetBSD Foundation, Inc. // All rights reserved. // @@ -25,11 +22,10 @@ // IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR // OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN // IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -// -#include "macros.hpp" +#include <atf-c++.hpp> -#include "detail/test_helpers.hpp" +#include "atf-c++/detail/test_helpers.hpp" // ------------------------------------------------------------------------ // Tests cases for the header file. Modified: head/contrib/atf/atf-c++/build.cpp ============================================================================== --- head/contrib/atf/atf-c++/build.cpp Sat Nov 1 11:07:59 2014 (r273928) +++ head/contrib/atf/atf-c++/build.cpp Sat Nov 1 11:17:54 2014 (r273929) @@ -1,6 +1,3 @@ -// -// Automated Testing Framework (atf) -// // Copyright (c) 2009 The NetBSD Foundation, Inc. // All rights reserved. // @@ -25,7 +22,8 @@ // IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR // OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN // IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -// + +#include "atf-c++/build.hpp" extern "C" { #include "atf-c/build.h" @@ -33,10 +31,8 @@ extern "C" { #include "atf-c/utils.h" } -#include "build.hpp" - -#include "detail/exceptions.hpp" -#include "detail/process.hpp" +#include "atf-c++/detail/exceptions.hpp" +#include "atf-c++/detail/process.hpp" namespace impl = atf::build; #define IMPL_NAME "atf::build" Modified: head/contrib/atf/atf-c++/build.hpp ============================================================================== --- head/contrib/atf/atf-c++/build.hpp Sat Nov 1 11:07:59 2014 (r273928) +++ head/contrib/atf/atf-c++/build.hpp Sat Nov 1 11:17:54 2014 (r273929) @@ -1,6 +1,3 @@ -// -// Automated Testing Framework (atf) -// // Copyright (c) 2009 The NetBSD Foundation, Inc. // All rights reserved. // @@ -25,10 +22,9 @@ // IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR // OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN // IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -// -#if !defined(_ATF_CXX_BUILD_HPP_) -#define _ATF_CXX_BUILD_HPP_ +#if !defined(ATF_CXX_BUILD_HPP) +#define ATF_CXX_BUILD_HPP #include <string> @@ -54,4 +50,4 @@ process::argv_array cxx_o(const std::str } // namespace build } // namespace atf -#endif // !defined(_ATF_CXX_BUILD_HPP_) +#endif // !defined(ATF_CXX_BUILD_HPP) Modified: head/contrib/atf/atf-c++/build_test.cpp ============================================================================== --- head/contrib/atf/atf-c++/build_test.cpp Sat Nov 1 11:07:59 2014 (r273928) +++ head/contrib/atf/atf-c++/build_test.cpp Sat Nov 1 11:17:54 2014 (r273929) @@ -1,6 +1,3 @@ -// -// Automated Testing Framework (atf) -// // Copyright (c) 2009 The NetBSD Foundation, Inc. // All rights reserved. // @@ -25,31 +22,25 @@ // IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR // OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN // IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -// + +#include "atf-c++/build.hpp" #include <cstring> #include <iostream> -#include "../atf-c/h_build.h" +#include <atf-c++.hpp> -#include "build.hpp" -#include "config.hpp" -#include "macros.hpp" - -#include "detail/env.hpp" -#include "detail/process.hpp" -#include "detail/test_helpers.hpp" +extern "C" { +#include "atf-c/h_build.h" +} + +#include "atf-c++/detail/env.hpp" +#include "atf-c++/detail/process.hpp" // ------------------------------------------------------------------------ // Auxiliary functions. // ------------------------------------------------------------------------ -namespace atf { - namespace config { - void __reinit(void); - } -} - template< class C > void print_col(const char* prefix, const C& c) @@ -168,7 +159,6 @@ ATF_TEST_CASE_BODY(c_o) verbose_set_env("ATF_BUILD_CC", test->cc); verbose_set_env("ATF_BUILD_CFLAGS", test->cflags); verbose_set_env("ATF_BUILD_CPPFLAGS", test->cppflags); - atf::config::__reinit(); atf::process::argv_array argv = atf::build::c_o(test->sfile, test->ofile, @@ -190,7 +180,6 @@ ATF_TEST_CASE_BODY(cpp) verbose_set_env("ATF_BUILD_CPP", test->cpp); verbose_set_env("ATF_BUILD_CPPFLAGS", test->cppflags); - atf::config::__reinit(); atf::process::argv_array argv = atf::build::cpp(test->sfile, test->ofile, @@ -213,7 +202,6 @@ ATF_TEST_CASE_BODY(cxx_o) verbose_set_env("ATF_BUILD_CXX", test->cxx); verbose_set_env("ATF_BUILD_CXXFLAGS", test->cxxflags); verbose_set_env("ATF_BUILD_CPPFLAGS", test->cppflags); - atf::config::__reinit(); atf::process::argv_array argv = atf::build::cxx_o(test->sfile, test->ofile, @@ -223,12 +211,6 @@ ATF_TEST_CASE_BODY(cxx_o) } // ------------------------------------------------------------------------ -// Tests cases for the header file. -// ------------------------------------------------------------------------ - -HEADER_TC(include, "atf-c++/build.hpp"); - -// ------------------------------------------------------------------------ // Main. // ------------------------------------------------------------------------ @@ -241,7 +223,4 @@ ATF_INIT_TEST_CASES(tcs) ATF_ADD_TEST_CASE(tcs, c_o); ATF_ADD_TEST_CASE(tcs, cpp); ATF_ADD_TEST_CASE(tcs, cxx_o); - - // Add the test cases for the header file. - ATF_ADD_TEST_CASE(tcs, include); } Modified: head/contrib/atf/atf-c++/check.cpp ============================================================================== --- head/contrib/atf/atf-c++/check.cpp Sat Nov 1 11:07:59 2014 (r273928) +++ head/contrib/atf/atf-c++/check.cpp Sat Nov 1 11:17:54 2014 (r273929) @@ -1,6 +1,3 @@ -// -// Automated Testing Framework (atf) -// // Copyright (c) 2007 The NetBSD Foundation, Inc. // All rights reserved. // @@ -25,7 +22,8 @@ // IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR // OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN // IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -// + +#include "atf-c++/check.hpp" #include <cstring> @@ -34,11 +32,9 @@ extern "C" { #include "atf-c/error.h" } -#include "check.hpp" - -#include "detail/exceptions.hpp" -#include "detail/process.hpp" -#include "detail/sanity.hpp" +#include "atf-c++/detail/exceptions.hpp" +#include "atf-c++/detail/process.hpp" +#include "atf-c++/detail/sanity.hpp" namespace impl = atf::check; #define IMPL_NAME "atf::check" *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201411011117.sA1BHtuQ065740>