diff options
Diffstat (limited to 'contrib/atf/atf-c++/atf-c++-api.3')
| -rw-r--r-- | contrib/atf/atf-c++/atf-c++-api.3 | 249 |
1 files changed, 232 insertions, 17 deletions
diff --git a/contrib/atf/atf-c++/atf-c++-api.3 b/contrib/atf/atf-c++/atf-c++-api.3 index 5d6618b..c086c90 100644 --- a/contrib/atf/atf-c++/atf-c++-api.3 +++ b/contrib/atf/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 15, 2013 .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,18 +89,64 @@ .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++. -This interface is backed by a C++ implementation, but this fact is -hidden from the developer as much as possible through the use of -macros to simplify programming. -However, the use of C++ is not hidden everywhere and while you can -implement test cases without knowing anything at all about the object model -underneath the provided calls, you might need some minimum notions of the -language in very specific circumstances. -.Pp -C++-based test programs always follow this template: +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 ... @@ -205,7 +263,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 +406,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 +420,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 -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 EXAMPLES The following shows a complete test program with a single test case that validates the addition operator: @@ -371,7 +586,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 +602,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 +612,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) { |
