security/nss/cmd/libpkix/testutil/testutil.h

   1 /* ***** BEGIN LICENSE BLOCK *****
   2  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   3  *
   4  * The contents of this file are subject to the Mozilla Public License Version
   5  * 1.1 (the "License"); you may not use this file except in compliance with
   6  * the License. You may obtain a copy of the License at
   7  * http://www.mozilla.org/MPL/
   8  *
   9  * Software distributed under the License is distributed on an "AS IS" basis,
  10  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  11  * for the specific language governing rights and limitations under the
  12  * License.
  13  *
  14  * The Original Code is the PKIX-C library.
  15  *
  16  * The Initial Developer of the Original Code is
  17  * Sun Microsystems, Inc.
  18  * Portions created by the Initial Developer are
  19  * Copyright 2004-2007 Sun Microsystems, Inc.  All Rights Reserved.
  20  *
  21  * Contributor(s):
  22  *   Sun Microsystems, Inc.
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37 /*
  38  * testutil.h
  39  *
  40  * Utility functions for handling test errors
  41  *
  42  */
  43
  44 #ifndef _TESTUTIL_H
  45 #define _TESTUTIL_H
  46
  47 #include "pkix.h"
  48 #include "plstr.h"
  49 #include "prprf.h"
  50 #include "prlong.h"
  51 #include "pkix_pl_common.h"
  52 #include "secutil.h"
  53 #include <stdio.h>
  54 #include <ctype.h>
  55
  56 #ifdef __cplusplus
  57 extern "C" {
  58 #endif
  59
  60 /*
  61  * In order to have a consistent format for displaying test information,
  62  * all tests are REQUIRED to use the functions provided by this library
  63  * (libtestutil.a) for displaying their information.
  64  *
  65  * A test using this library begins with a call to startTests with the test
  66  * name as the arg (which is used only for formatting). Before the first
  67  * subtest, a call to subTest should be made with the subtest name as the arg
  68  * (again, for formatting). If the subTest is successful, then no action
  69  * is needed. However, if the subTest is not successful, then a call
  70  * to testError should be made with a descriptive error message as the arg.
  71  * Note that a subTest MUST NOT call testError more than once.
  72  * Finally, a call to endTests is made with the test name as the arg (for
  73  * formatting). Note that most of these macros assume that a variable named
  74  * "plContext" of type (void *) has been defined by the test. As such, it
  75  * is essential that the test satisfy this condition.
  76  */
  77
  78 /*
  79  * PKIX_TEST_STD_VARS should be called at the beginning of every function
  80  * that uses PKIX_TEST_RETURN (e.g. subTests), but it should be called only
  81  * AFTER declaring local variables (so we don't get compiler warnings about
  82  * declarations after statements). PKIX_TEST_STD_VARS declares and initializes
  83  * several variables needed by the other test macros.
  84  */
  85 #define PKIX_TEST_STD_VARS() \
  86         PKIX_Error *pkixTestErrorResult = NULL; \
  87         char *pkixTestErrorMsg = NULL;
  88
  89 /*
  90  * PKIX_TEST_EXPECT_NO_ERROR should be used to wrap a standard PKIX function
  91  * call (one which returns a pointer to PKIX_Error) that is expected to return
  92  * NULL (i.e. to succeed). If "pkixTestErrorResult" is not NULL,
  93  * "goto cleanup" is executed, where a testError call is made if there were
  94  * unexpected results. This macro MUST NOT be called after the "cleanup" label.
  95  *
  96  * Example Usage: PKIX_TEST_EXPECT_NO_ERROR(pkixFunc_expected_to_succeed(...));
  97  */
  98
  99 #define PKIX_TEST_EXPECT_NO_ERROR(func) \
 100         do { \
 101                 pkixTestErrorResult = (func); \
 102                 if (pkixTestErrorResult) { \
 103                         goto cleanup; \
 104                 } \
 105         } while (0)
 106
 107 /*
 108  * PKIX_TEST_EXPECT_ERROR should be used to wrap a standard PKIX function call
 109  * (one which returns a pointer to PKIX_Error) that is expected to return
 110  * a non-NULL value (i.e. to fail). If "pkixTestErrorResult" is NULL,
 111  * "pkixTestErrorMsg" is set to a standard string and "goto cleanup"
 112  * is executed, where a testError call is made if there were unexpected
 113  * results. This macro MUST NOT be called after the "cleanup" label.
 114  *
 115  * Example Usage:  PKIX_TEST_EXPECT_ERROR(pkixFunc_expected_to_fail(...));
 116  */
 117
 118 #define PKIX_TEST_EXPECT_ERROR(func) \
 119         do { \
 120                 pkixTestErrorResult = (func); \
 121                 if (!pkixTestErrorResult){ \
 122                         pkixTestErrorMsg = \
 123                                 "Should have thrown an error here."; \
 124                         goto cleanup; \
 125                 } \
 126                 PKIX_TEST_DECREF_BC(pkixTestErrorResult); \
 127         } while (0)
 128
 129 /*
 130  * PKIX_TEST_DECREF_BC is a convenience macro which should only be called
 131  * BEFORE the "cleanup" label ("BC"). If the input parameter is non-NULL, it
 132  * DecRefs the input parameter and wraps the function with
 133  * PKIX_TEST_EXPECT_NO_ERROR, which executes "goto cleanup" upon error.
 134  * This macro MUST NOT be called after the "cleanup" label.
 135  */
 136
 137 #define PKIX_TEST_DECREF_BC(obj) \
 138         do { \
 139                 if (obj){ \
 140                         PKIX_TEST_EXPECT_NO_ERROR \
 141                         (PKIX_PL_Object_DecRef \
 142                                 ((PKIX_PL_Object*)(obj), plContext)); \
 143                 obj = NULL; \
 144                 } \
 145         } while (0)
 146
 147 /*
 148  * PKIX_TEST_DECREF_AC is a convenience macro which should only be called
 149  * AFTER the "cleanup" label ("AC"). If the input parameter is non-NULL, it
 150  * DecRefs the input parameter. A pkixTestTempResult variable is used to prevent
 151  * incorrectly overwriting pkixTestErrorResult with NULL.
 152  * In the case DecRef succeeds, pkixTestTempResult will be NULL, and we won't
 153  * overwrite a previously set pkixTestErrorResult (if any). If DecRef fails,
 154  * then we do want to overwrite a previously set pkixTestErrorResult since a
 155  * DecRef failure is fatal and may be indicative of memory corruption.
 156  */
 157
 158 #define PKIX_TEST_DECREF_AC(obj) \
 159         do { \
 160                 if (obj){ \
 161                         PKIX_Error *pkixTestTempResult = NULL; \
 162                         pkixTestTempResult = \
 163                         PKIX_PL_Object_DecRef \
 164                                 ((PKIX_PL_Object*)(obj), plContext); \
 165                         if (pkixTestTempResult) \
 166                                 pkixTestErrorResult = pkixTestTempResult; \
 167                         obj = NULL; \
 168                 } \
 169         } while (0)
 170
 171 /*
 172  * PKIX_TEST_RETURN must always be AFTER the "cleanup" label. It does nothing
 173  * if everything went as expected. However, if there were unexpected results,
 174  * PKIX_TEST_RETURN calls testError, which displays a standard failure message
 175  * and increments the number of subtests that have failed. In the case
 176  * of an unexpected error, testError is called using the error's description
 177  * as an input and the error is DecRef'd. In the case of unexpected success
 178  * testError is called with a standard string.
 179  */
 180 #define PKIX_TEST_RETURN() \
 181         { \
 182                 if (pkixTestErrorMsg){ \
 183                         testError(pkixTestErrorMsg); \
 184                 } else if (pkixTestErrorResult){ \
 185                         pkixTestErrorMsg = \
 186                                 PKIX_Error2ASCII \
 187                                         (pkixTestErrorResult, plContext); \
 188                         if (pkixTestErrorMsg) { \
 189                                 testError(pkixTestErrorMsg); \
 190                                 PKIX_PL_Free \
 191                                         ((PKIX_PL_Object *)pkixTestErrorMsg, \
 192                                         plContext); \
 193                         } else { \
 194                                 testError("PKIX_Error2ASCII Failed"); \
 195                         } \
 196                         if (pkixTestErrorResult != PKIX_ALLOC_ERROR()){ \
 197                                 PKIX_PL_Object_DecRef \
 198                                 ((PKIX_PL_Object*)pkixTestErrorResult, \
 199                                 plContext); \
 200                                 pkixTestErrorResult = NULL; \
 201                         } \
 202                 } \
 203         }
 204
 205 /*
 206  * PKIX_TEST_EQ_HASH_TOSTR_DUP is a convenience macro which executes the
 207  * standard set of operations that test the Equals, Hashcode, ToString, and
 208  * Duplicate functions of an object type. The goodObj, equalObj, and diffObj
 209  * are as the names suggest. The expAscii parameter is the expected result of
 210  * calling ToString on the goodObj. If expAscii is NULL, then ToString will
 211  * not be called on the goodObj. The checkDuplicate parameter is treated as
 212  * a Boolean to indicate whether the Duplicate function should be tested. If
 213  * checkDuplicate is NULL, then Duplicate will not be called on the goodObj.
 214  * The type is the name of the function's family. For example, if the type is
 215  * Cert, this macro will call PKIX_PL_Cert_Equals, PKIX_PL_Cert_Hashcode, and
 216  * PKIX_PL_Cert_ToString.
 217  *
 218  * Note: If goodObj uses the default Equals and Hashcode functions, then
 219  * for goodObj and equalObj to be equal, they must have the same pointer value.
 220  */
 221 #define PKIX_TEST_EQ_HASH_TOSTR_DUP(goodObj, equalObj, diffObj, \
 222                                         expAscii, type, checkDuplicate) \
 223         do { \
 224                 subTest("PKIX_PL_" #type "_Equals   <match>"); \
 225                 testEqualsHelper \
 226                         ((PKIX_PL_Object *)(goodObj), \
 227                         (PKIX_PL_Object *)(equalObj), \
 228                         PKIX_TRUE, \
 229                         plContext); \
 230                 subTest("PKIX_PL_" #type "_Hashcode <match>"); \
 231                 testHashcodeHelper \
 232                         ((PKIX_PL_Object *)(goodObj), \
 233                         (PKIX_PL_Object *)(equalObj), \
 234                         PKIX_TRUE, \
 235                         plContext); \
 236                 subTest("PKIX_PL_" #type "_Equals   <non-match>"); \
 237                 testEqualsHelper \
 238                         ((PKIX_PL_Object *)(goodObj), \
 239                         (PKIX_PL_Object *)(diffObj), \
 240                         PKIX_FALSE, \
 241                         plContext); \
 242                 subTest("PKIX_PL_" #type "_Hashcode <non-match>"); \
 243                 testHashcodeHelper \
 244                         ((PKIX_PL_Object *)(goodObj), \
 245                         (PKIX_PL_Object *)(diffObj), \
 246                         PKIX_FALSE, \
 247                         plContext); \
 248                 if (expAscii){ \
 249                         subTest("PKIX_PL_" #type "_ToString"); \
 250                         testToStringHelper \
 251                                 ((PKIX_PL_Object *)(goodObj), \
 252                                 (expAscii), \
 253                                 plContext); } \
 254                 if (checkDuplicate){ \
 255                         subTest("PKIX_PL_" #type "_Duplicate"); \
 256                         testDuplicateHelper \
 257                                 ((PKIX_PL_Object *)goodObj, plContext); } \
 258         } while (0)
 259
 260 /*
 261  * PKIX_TEST_DECREF_BC is a convenience macro which should only be called
 262  * BEFORE the "cleanup" label ("BC"). If the input parameter is non-NULL, it
 263  * DecRefs the input parameter and wraps the function with
 264  * PKIX_TEST_EXPECT_NO_ERROR, which executes "goto cleanup" upon error.
 265  * This macro MUST NOT be called after the "cleanup" label.
 266  */
 267
 268 #define PKIX_TEST_ABORT_ON_NULL(obj) \
 269         do { \
 270                 if (!obj){ \
 271                         goto cleanup; \
 272                 } \
 273         } while (0)
 274
 275 #define PKIX_TEST_ARENAS_ARG(arena) \
 276         (arena? \
 277         (PORT_Strcmp(arena, "arenas") ? PKIX_FALSE : (j++, PKIX_TRUE)): \
 278         PKIX_FALSE)
 279
 280 #define PKIX_TEST_ERROR_RECEIVED (pkixTestErrorMsg || pkixTestErrorResult)
 281
 282 /* see source file for function documentation */
 283
 284 void startTests(char *testName);
 285
 286 void endTests(char *testName);
 287
 288 void subTest(char *subTestName);
 289
 290 void testError(char *msg);
 291
 292 extern PKIX_Error *
 293 _ErrorCheck(PKIX_Error *errorResult);
 294
 295 extern PKIX_Error *
 296 _OutputError(PKIX_Error *errorResult);
 297
 298 char* PKIX_String2ASCII(PKIX_PL_String *string, void *plContext);
 299
 300 char* PKIX_Error2ASCII(PKIX_Error *error, void *plContext);
 301
 302 char* PKIX_Object2ASCII(PKIX_PL_Object *object);
 303
 304 char *PKIX_Cert2ASCII(PKIX_PL_Cert *cert);
 305
 306 void
 307 testHashcodeHelper(
 308         PKIX_PL_Object *goodObject,
 309         PKIX_PL_Object *otherObject,
 310         PKIX_Boolean match,
 311         void *plContext);
 312
 313 void
 314 testToStringHelper(
 315         PKIX_PL_Object *goodObject,
 316         char *expected,
 317         void *plContext);
 318
 319 void
 320 testEqualsHelper(
 321         PKIX_PL_Object *goodObject,
 322         PKIX_PL_Object *otherObject,
 323         PKIX_Boolean match,
 324         void *plContext);
 325
 326 void
 327 testDuplicateHelper(
 328         PKIX_PL_Object *object,
 329         void *plContext);
 330 void
 331 testErrorUndo(char *msg);
 332
 333 #ifdef __cplusplus
 334 }
 335 #endif
 336
 337 #endif /* TESTUTIL_H */