vendor/atf/atf-0.17

1 files changed, 230 insertions, 6 deletions

diff --git a/atf-c++/atf-c++-api.3 b/atf-c++/atf-c++-api.3
index 5d6618b4eb32a..d0579a9a75441 100644
--- a/atf-c++/atf-c++-api.3
+++ b/atf-c++/atf-c++-api.3
@@ -26,10 +26,11 @@
 .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
 .\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd January 21, 2012
+.Dd November 30, 2012
 .Dt ATF-C++-API 3
 .Os
 .Sh NAME
+.Nm atf-c++-api ,
 .Nm ATF_ADD_TEST_CASE ,
 .Nm ATF_CHECK_ERRNO ,
 .Nm ATF_FAIL ,
@@ -52,6 +53,17 @@
 .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
@@ -77,6 +89,61 @@
 .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 mostly-macro-based programming interface to implement test
 programs in C or C++.
@@ -205,7 +272,7 @@ 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
+.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.
@@ -348,7 +415,7 @@ in the collection.
 .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_EQ
+.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.
@@ -362,6 +429,163 @@ 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 -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 -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 -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 -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 -offset indent
+Checks if
+.Fa path
+exists.
+.Ed
+.Pp
+.Ft pid_t
+.Fo atf::utils::fork
+.Fa "void"
+.Fc
+.Bd -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 -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 -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 -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 -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 -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 EXAMPLES
 The following shows a complete test program with a single test case that
 validates the addition operator:
@@ -371,7 +595,7 @@ validates the addition operator:
 ATF_TEST_CASE(addition);
 ATF_TEST_CASE_HEAD(addition)
 {
-    set("descr", "Sample tests for the addition operator");
+    set_md_var("descr", "Sample tests for the addition operator");
 }
 ATF_TEST_CASE_BODY(addition)
 {
@@ -387,7 +611,7 @@ ATF_TEST_CASE_BODY(addition)
 ATF_TEST_CASE(open_failure);
 ATF_TEST_CASE_HEAD(open_failure)
 {
-    set("descr", "Sample tests for the open function");
+    set_md_var("descr", "Sample tests for the open function");
 }
 ATF_TEST_CASE_BODY(open_failure)
 {
@@ -397,7 +621,7 @@ ATF_TEST_CASE_BODY(open_failure)
 ATF_TEST_CASE(known_bug);
 ATF_TEST_CASE_HEAD(known_bug)
 {
-    set("descr", "Reproduces a known bug");
+    set_md_var("descr", "Reproduces a known bug");
 }
 ATF_TEST_CASE_BODY(known_bug)
 {