share/examples/tests/tests/atf/printf_test.c

   1 /* $FreeBSD$
   2  *
   3  * SPDX-License-Identifier: BSD-3-Clause
   4  *
   5  * Copyright 2013 Google Inc.
   6  * All rights reserved.
   7  *
   8  * Redistribution and use in source and binary forms, with or without
   9  * modification, are permitted provided that the following conditions are
  10  * met:
  11  *
  12  * * Redistributions of source code must retain the above copyright
  13  *   notice, this list of conditions and the following disclaimer.
  14  * * 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  * * Neither the name of Google Inc. nor the names of its contributors
  18  *   may be used to endorse or promote products derived from this software
  19  *   without specific prior written permission.
  20  *
  21  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  22  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  23  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  24  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  25  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  26  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  27  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  28  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  29  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  30  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  31  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */
  32
  33 /*
  34  * INTRODUCTION
  35  *
  36  * This sample test program implements various test cases for the printf(3)
  37  * family of functions in order to demonstrate the usage of the ATF C API
  38  * (see atf-c-api(3)).
  39  *
  40  * Note that this test program is called printf_test because it is intended
  41  * to validate various functions of the printf(3) family.  For this reason,
  42  * each test is prefixed with the name of the function under test followed
  43  * by a description of the specific condition being validated.  You should
  44  * use a similar naming scheme for your own tests.
  45  */
  46
  47 #include <atf-c.h>
  48 #include <stdio.h>
  49 #include <string.h>
  50
  51 /*
  52  * This is the simplest form of a test case definition: a test case
  53  * without a header.
  54  *
  55  * In most cases, this is the definition you will want to use.  However,
  56  * make absolutely sure that the test case name is descriptive enough.
  57  * Multi-word test case names are encouraged.  Keep in mind that these
  58  * are exposed to the reader in the test reports, and the goal is for
  59  * the combination of the test program plus the name of the test case to
  60  * give a pretty clear idea of what specific condition the test is
  61  * validating.
  62  */
  63 ATF_TC_WITHOUT_HEAD(snprintf__two_formatters);
  64 ATF_TC_BODY(snprintf__two_formatters, tc)
  65 {
  66         char buffer[128];
  67
  68         /* This first require-style check invokes the function we are
  69          * interested in testing.  This will cause the test to fail if
  70          * the condition provided to ATF_REQUIRE is not met. */
  71         ATF_REQUIRE(snprintf(buffer, sizeof(buffer), "%s, %s!",
  72             "Hello", "tests") > 0);
  73
  74         /* This second check-style check compares that the result of the
  75          * snprintf call we performed above is correct.  We use a check
  76          * instead of a require. */
  77         ATF_CHECK_STREQ("Hello, tests!", buffer);
  78 }
  79
  80 /*
  81  * This is a more complex form of a test case definition: a test case
  82  * with a header and a body.  You should always favor the simpler
  83  * definition above unless you have to override specific metadata
  84  * variables.
  85  *
  86  * See atf-test-case(4) and kyua-atf-interface(1) for details on all
  87  * available properties.
  88  */
  89 ATF_TC(snprintf__overflow);
  90 ATF_TC_HEAD(snprintf__overflow, tc)
  91 {
  92         /* In this specific case, we define a textual description for
  93          * the test case, which is later exported to the reports for
  94          * documentation purposes.
  95          *
  96          * However, note again that you should favor highly descriptive
  97          * test case names to textual descriptions.  */
  98         atf_tc_set_md_var(tc, "descr", "This test case validates the proper "
  99             "truncation of the output string from snprintf when it does not "
 100             "fit the provided buffer.");
 101 }
 102 ATF_TC_BODY(snprintf__overflow, tc)
 103 {
 104         char buffer[10];
 105
 106         /* This is a similar test to the above, but in this case we do the
 107          * test ourselves and forego the ATF_* macros.  Note that we use the
 108          * atf_tc_fail() function instead of exit(2) or similar because we
 109          * want Kyua to have access to the failure message.
 110          *
 111          * In general, prefer using the ATF_* macros wherever possible.  Only
 112          * resort to manual tests when the macros are unsuitable (and consider
 113          * filing a feature request to get a new macro if you think your case
 114          * is generic enough). */
 115         if (snprintf(buffer, sizeof(buffer), "0123456789abcdef") != 16)
 116                 atf_tc_fail("snprintf did not return the expected number "
 117                     "of characters");
 118
 119         ATF_CHECK(strcmp(buffer, "012345678") == 0);
 120 }
 121
 122 /*
 123  * Another simple test case, but this time with side-effects.  This
 124  * particular test case modifies the contents of the current directory
 125  * and does not clean up after itself, which is perfectly fine.
 126  */
 127 ATF_TC_WITHOUT_HEAD(fprintf__simple_string);
 128 ATF_TC_BODY(fprintf__simple_string, tc)
 129 {
 130         const char *contents = "This is a message\n";
 131
 132         FILE *output = fopen("test.txt", "w");
 133         ATF_REQUIRE(fprintf(output, "%s", contents) > 0);
 134         fclose(output);
 135
 136         /* The ATF C library provides more than just macros to verify the
 137          * outcome of expressions.  It also includes various helper functions
 138          * to work with files and processes.  Here is just a simple
 139          * example. */
 140         ATF_REQUIRE(atf_utils_compare_file("test.txt", contents));
 141
 142         /* Of special note here is that we are NOT deleting the
 143          * temporary files we created in this test.  Kyua takes care of
 144          * this cleanup automatically and tests can (and should) rely on
 145          * this behavior. */
 146 }
 147
 148 /*
 149  * Lastly, we tell ATF which test cases exist in this program.  This
 150  * function should not do anything other than this registration.
 151  */
 152 ATF_TP_ADD_TCS(tp)
 153 {
 154         ATF_TP_ADD_TC(tp, snprintf__two_formatters);
 155         ATF_TP_ADD_TC(tp, snprintf__overflow);
 156         ATF_TP_ADD_TC(tp, fprintf__simple_string);
 157
 158         return (atf_no_error());
 159 }