1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/security/nss/cmd/libpkix/testutil/testutil.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,304 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +/*
1.8 + * testutil.h
1.9 + *
1.10 + * Utility functions for handling test errors
1.11 + *
1.12 + */
1.13 +
1.14 +#ifndef _TESTUTIL_H
1.15 +#define _TESTUTIL_H
1.16 +
1.17 +#include "pkix.h"
1.18 +#include "plstr.h"
1.19 +#include "prprf.h"
1.20 +#include "prlong.h"
1.21 +#include "pkix_pl_common.h"
1.22 +#include "secutil.h"
1.23 +#include <stdio.h>
1.24 +#include <ctype.h>
1.25 +
1.26 +#ifdef __cplusplus
1.27 +extern "C" {
1.28 +#endif
1.29 +
1.30 +/*
1.31 + * In order to have a consistent format for displaying test information,
1.32 + * all tests are REQUIRED to use the functions provided by this library
1.33 + * (libtestutil.a) for displaying their information.
1.34 + *
1.35 + * A test using this library begins with a call to startTests with the test
1.36 + * name as the arg (which is used only for formatting). Before the first
1.37 + * subtest, a call to subTest should be made with the subtest name as the arg
1.38 + * (again, for formatting). If the subTest is successful, then no action
1.39 + * is needed. However, if the subTest is not successful, then a call
1.40 + * to testError should be made with a descriptive error message as the arg.
1.41 + * Note that a subTest MUST NOT call testError more than once.
1.42 + * Finally, a call to endTests is made with the test name as the arg (for
1.43 + * formatting). Note that most of these macros assume that a variable named
1.44 + * "plContext" of type (void *) has been defined by the test. As such, it
1.45 + * is essential that the test satisfy this condition.
1.46 + */
1.47 +
1.48 +/*
1.49 + * PKIX_TEST_STD_VARS should be called at the beginning of every function
1.50 + * that uses PKIX_TEST_RETURN (e.g. subTests), but it should be called only
1.51 + * AFTER declaring local variables (so we don't get compiler warnings about
1.52 + * declarations after statements). PKIX_TEST_STD_VARS declares and initializes
1.53 + * several variables needed by the other test macros.
1.54 + */
1.55 +#define PKIX_TEST_STD_VARS() \
1.56 + PKIX_Error *pkixTestErrorResult = NULL; \
1.57 + char *pkixTestErrorMsg = NULL;
1.58 +
1.59 +/*
1.60 + * PKIX_TEST_EXPECT_NO_ERROR should be used to wrap a standard PKIX function
1.61 + * call (one which returns a pointer to PKIX_Error) that is expected to return
1.62 + * NULL (i.e. to succeed). If "pkixTestErrorResult" is not NULL,
1.63 + * "goto cleanup" is executed, where a testError call is made if there were
1.64 + * unexpected results. This macro MUST NOT be called after the "cleanup" label.
1.65 + *
1.66 + * Example Usage: PKIX_TEST_EXPECT_NO_ERROR(pkixFunc_expected_to_succeed(...));
1.67 + */
1.68 +
1.69 +#define PKIX_TEST_EXPECT_NO_ERROR(func) \
1.70 + do { \
1.71 + pkixTestErrorResult = (func); \
1.72 + if (pkixTestErrorResult) { \
1.73 + goto cleanup; \
1.74 + } \
1.75 + } while (0)
1.76 +
1.77 +/*
1.78 + * PKIX_TEST_EXPECT_ERROR should be used to wrap a standard PKIX function call
1.79 + * (one which returns a pointer to PKIX_Error) that is expected to return
1.80 + * a non-NULL value (i.e. to fail). If "pkixTestErrorResult" is NULL,
1.81 + * "pkixTestErrorMsg" is set to a standard string and "goto cleanup"
1.82 + * is executed, where a testError call is made if there were unexpected
1.83 + * results. This macro MUST NOT be called after the "cleanup" label.
1.84 + *
1.85 + * Example Usage: PKIX_TEST_EXPECT_ERROR(pkixFunc_expected_to_fail(...));
1.86 + */
1.87 +
1.88 +#define PKIX_TEST_EXPECT_ERROR(func) \
1.89 + do { \
1.90 + pkixTestErrorResult = (func); \
1.91 + if (!pkixTestErrorResult){ \
1.92 + pkixTestErrorMsg = \
1.93 + "Should have thrown an error here."; \
1.94 + goto cleanup; \
1.95 + } \
1.96 + PKIX_TEST_DECREF_BC(pkixTestErrorResult); \
1.97 + } while (0)
1.98 +
1.99 +/*
1.100 + * PKIX_TEST_DECREF_BC is a convenience macro which should only be called
1.101 + * BEFORE the "cleanup" label ("BC"). If the input parameter is non-NULL, it
1.102 + * DecRefs the input parameter and wraps the function with
1.103 + * PKIX_TEST_EXPECT_NO_ERROR, which executes "goto cleanup" upon error.
1.104 + * This macro MUST NOT be called after the "cleanup" label.
1.105 + */
1.106 +
1.107 +#define PKIX_TEST_DECREF_BC(obj) \
1.108 + do { \
1.109 + if (obj){ \
1.110 + PKIX_TEST_EXPECT_NO_ERROR \
1.111 + (PKIX_PL_Object_DecRef \
1.112 + ((PKIX_PL_Object*)(obj), plContext)); \
1.113 + obj = NULL; \
1.114 + } \
1.115 + } while (0)
1.116 +
1.117 +/*
1.118 + * PKIX_TEST_DECREF_AC is a convenience macro which should only be called
1.119 + * AFTER the "cleanup" label ("AC"). If the input parameter is non-NULL, it
1.120 + * DecRefs the input parameter. A pkixTestTempResult variable is used to prevent
1.121 + * incorrectly overwriting pkixTestErrorResult with NULL.
1.122 + * In the case DecRef succeeds, pkixTestTempResult will be NULL, and we won't
1.123 + * overwrite a previously set pkixTestErrorResult (if any). If DecRef fails,
1.124 + * then we do want to overwrite a previously set pkixTestErrorResult since a
1.125 + * DecRef failure is fatal and may be indicative of memory corruption.
1.126 + */
1.127 +
1.128 +#define PKIX_TEST_DECREF_AC(obj) \
1.129 + do { \
1.130 + if (obj){ \
1.131 + PKIX_Error *pkixTestTempResult = NULL; \
1.132 + pkixTestTempResult = \
1.133 + PKIX_PL_Object_DecRef \
1.134 + ((PKIX_PL_Object*)(obj), plContext); \
1.135 + if (pkixTestTempResult) \
1.136 + pkixTestErrorResult = pkixTestTempResult; \
1.137 + obj = NULL; \
1.138 + } \
1.139 + } while (0)
1.140 +
1.141 +/*
1.142 + * PKIX_TEST_RETURN must always be AFTER the "cleanup" label. It does nothing
1.143 + * if everything went as expected. However, if there were unexpected results,
1.144 + * PKIX_TEST_RETURN calls testError, which displays a standard failure message
1.145 + * and increments the number of subtests that have failed. In the case
1.146 + * of an unexpected error, testError is called using the error's description
1.147 + * as an input and the error is DecRef'd. In the case of unexpected success
1.148 + * testError is called with a standard string.
1.149 + */
1.150 +#define PKIX_TEST_RETURN() \
1.151 + { \
1.152 + if (pkixTestErrorMsg){ \
1.153 + testError(pkixTestErrorMsg); \
1.154 + } else if (pkixTestErrorResult){ \
1.155 + pkixTestErrorMsg = \
1.156 + PKIX_Error2ASCII \
1.157 + (pkixTestErrorResult, plContext); \
1.158 + if (pkixTestErrorMsg) { \
1.159 + testError(pkixTestErrorMsg); \
1.160 + PKIX_PL_Free \
1.161 + ((PKIX_PL_Object *)pkixTestErrorMsg, \
1.162 + plContext); \
1.163 + } else { \
1.164 + testError("PKIX_Error2ASCII Failed"); \
1.165 + } \
1.166 + if (pkixTestErrorResult != PKIX_ALLOC_ERROR()){ \
1.167 + PKIX_PL_Object_DecRef \
1.168 + ((PKIX_PL_Object*)pkixTestErrorResult, \
1.169 + plContext); \
1.170 + pkixTestErrorResult = NULL; \
1.171 + } \
1.172 + } \
1.173 + }
1.174 +
1.175 +/*
1.176 + * PKIX_TEST_EQ_HASH_TOSTR_DUP is a convenience macro which executes the
1.177 + * standard set of operations that test the Equals, Hashcode, ToString, and
1.178 + * Duplicate functions of an object type. The goodObj, equalObj, and diffObj
1.179 + * are as the names suggest. The expAscii parameter is the expected result of
1.180 + * calling ToString on the goodObj. If expAscii is NULL, then ToString will
1.181 + * not be called on the goodObj. The checkDuplicate parameter is treated as
1.182 + * a Boolean to indicate whether the Duplicate function should be tested. If
1.183 + * checkDuplicate is NULL, then Duplicate will not be called on the goodObj.
1.184 + * The type is the name of the function's family. For example, if the type is
1.185 + * Cert, this macro will call PKIX_PL_Cert_Equals, PKIX_PL_Cert_Hashcode, and
1.186 + * PKIX_PL_Cert_ToString.
1.187 + *
1.188 + * Note: If goodObj uses the default Equals and Hashcode functions, then
1.189 + * for goodObj and equalObj to be equal, they must have the same pointer value.
1.190 + */
1.191 +#define PKIX_TEST_EQ_HASH_TOSTR_DUP(goodObj, equalObj, diffObj, \
1.192 + expAscii, type, checkDuplicate) \
1.193 + do { \
1.194 + subTest("PKIX_PL_" #type "_Equals <match>"); \
1.195 + testEqualsHelper \
1.196 + ((PKIX_PL_Object *)(goodObj), \
1.197 + (PKIX_PL_Object *)(equalObj), \
1.198 + PKIX_TRUE, \
1.199 + plContext); \
1.200 + subTest("PKIX_PL_" #type "_Hashcode <match>"); \
1.201 + testHashcodeHelper \
1.202 + ((PKIX_PL_Object *)(goodObj), \
1.203 + (PKIX_PL_Object *)(equalObj), \
1.204 + PKIX_TRUE, \
1.205 + plContext); \
1.206 + subTest("PKIX_PL_" #type "_Equals <non-match>"); \
1.207 + testEqualsHelper \
1.208 + ((PKIX_PL_Object *)(goodObj), \
1.209 + (PKIX_PL_Object *)(diffObj), \
1.210 + PKIX_FALSE, \
1.211 + plContext); \
1.212 + subTest("PKIX_PL_" #type "_Hashcode <non-match>"); \
1.213 + testHashcodeHelper \
1.214 + ((PKIX_PL_Object *)(goodObj), \
1.215 + (PKIX_PL_Object *)(diffObj), \
1.216 + PKIX_FALSE, \
1.217 + plContext); \
1.218 + if (expAscii){ \
1.219 + subTest("PKIX_PL_" #type "_ToString"); \
1.220 + testToStringHelper \
1.221 + ((PKIX_PL_Object *)(goodObj), \
1.222 + (expAscii), \
1.223 + plContext); } \
1.224 + if (checkDuplicate){ \
1.225 + subTest("PKIX_PL_" #type "_Duplicate"); \
1.226 + testDuplicateHelper \
1.227 + ((PKIX_PL_Object *)goodObj, plContext); } \
1.228 + } while (0)
1.229 +
1.230 +/*
1.231 + * PKIX_TEST_DECREF_BC is a convenience macro which should only be called
1.232 + * BEFORE the "cleanup" label ("BC"). If the input parameter is non-NULL, it
1.233 + * DecRefs the input parameter and wraps the function with
1.234 + * PKIX_TEST_EXPECT_NO_ERROR, which executes "goto cleanup" upon error.
1.235 + * This macro MUST NOT be called after the "cleanup" label.
1.236 + */
1.237 +
1.238 +#define PKIX_TEST_ABORT_ON_NULL(obj) \
1.239 + do { \
1.240 + if (!obj){ \
1.241 + goto cleanup; \
1.242 + } \
1.243 + } while (0)
1.244 +
1.245 +#define PKIX_TEST_ARENAS_ARG(arena) \
1.246 + (arena? \
1.247 + (PORT_Strcmp(arena, "arenas") ? PKIX_FALSE : (j++, PKIX_TRUE)): \
1.248 + PKIX_FALSE)
1.249 +
1.250 +#define PKIX_TEST_ERROR_RECEIVED (pkixTestErrorMsg || pkixTestErrorResult)
1.251 +
1.252 +/* see source file for function documentation */
1.253 +
1.254 +void startTests(char *testName);
1.255 +
1.256 +void endTests(char *testName);
1.257 +
1.258 +void subTest(char *subTestName);
1.259 +
1.260 +void testError(char *msg);
1.261 +
1.262 +extern PKIX_Error *
1.263 +_ErrorCheck(PKIX_Error *errorResult);
1.264 +
1.265 +extern PKIX_Error *
1.266 +_OutputError(PKIX_Error *errorResult);
1.267 +
1.268 +char* PKIX_String2ASCII(PKIX_PL_String *string, void *plContext);
1.269 +
1.270 +char* PKIX_Error2ASCII(PKIX_Error *error, void *plContext);
1.271 +
1.272 +char* PKIX_Object2ASCII(PKIX_PL_Object *object);
1.273 +
1.274 +char *PKIX_Cert2ASCII(PKIX_PL_Cert *cert);
1.275 +
1.276 +void
1.277 +testHashcodeHelper(
1.278 + PKIX_PL_Object *goodObject,
1.279 + PKIX_PL_Object *otherObject,
1.280 + PKIX_Boolean match,
1.281 + void *plContext);
1.282 +
1.283 +void
1.284 +testToStringHelper(
1.285 + PKIX_PL_Object *goodObject,
1.286 + char *expected,
1.287 + void *plContext);
1.288 +
1.289 +void
1.290 +testEqualsHelper(
1.291 + PKIX_PL_Object *goodObject,
1.292 + PKIX_PL_Object *otherObject,
1.293 + PKIX_Boolean match,
1.294 + void *plContext);
1.295 +
1.296 +void
1.297 +testDuplicateHelper(
1.298 + PKIX_PL_Object *object,
1.299 + void *plContext);
1.300 +void
1.301 +testErrorUndo(char *msg);
1.302 +
1.303 +#ifdef __cplusplus
1.304 +}
1.305 +#endif
1.306 +
1.307 +#endif /* TESTUTIL_H */
