diff options
Diffstat (limited to 'security/nss/cmd/libpkix/testutil/testutil.h')
| -rw-r--r-- | security/nss/cmd/libpkix/testutil/testutil.h | 292 |
1 files changed, 292 insertions, 0 deletions
diff --git a/security/nss/cmd/libpkix/testutil/testutil.h b/security/nss/cmd/libpkix/testutil/testutil.h new file mode 100644 index 000000000..9c594fa03 --- /dev/null +++ b/security/nss/cmd/libpkix/testutil/testutil.h @@ -0,0 +1,292 @@ +/* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ +/* + * testutil.h + * + * Utility functions for handling test errors + * + */ + +#ifndef _TESTUTIL_H +#define _TESTUTIL_H + +#include "pkix.h" +#include "plstr.h" +#include "prprf.h" +#include "prlong.h" +#include "pkix_pl_common.h" +#include "secutil.h" +#include <stdio.h> +#include <ctype.h> + +#ifdef __cplusplus +extern "C" { +#endif + +/* + * In order to have a consistent format for displaying test information, + * all tests are REQUIRED to use the functions provided by this library + * (libtestutil.a) for displaying their information. + * + * A test using this library begins with a call to startTests with the test + * name as the arg (which is used only for formatting). Before the first + * subtest, a call to subTest should be made with the subtest name as the arg + * (again, for formatting). If the subTest is successful, then no action + * is needed. However, if the subTest is not successful, then a call + * to testError should be made with a descriptive error message as the arg. + * Note that a subTest MUST NOT call testError more than once. + * Finally, a call to endTests is made with the test name as the arg (for + * formatting). Note that most of these macros assume that a variable named + * "plContext" of type (void *) has been defined by the test. As such, it + * is essential that the test satisfy this condition. + */ + +/* + * PKIX_TEST_STD_VARS should be called at the beginning of every function + * that uses PKIX_TEST_RETURN (e.g. subTests), but it should be called only + * AFTER declaring local variables (so we don't get compiler warnings about + * declarations after statements). PKIX_TEST_STD_VARS declares and initializes + * several variables needed by the other test macros. + */ +#define PKIX_TEST_STD_VARS() \ + PKIX_Error *pkixTestErrorResult = NULL; \ + char *pkixTestErrorMsg = NULL; + +/* + * PKIX_TEST_EXPECT_NO_ERROR should be used to wrap a standard PKIX function + * call (one which returns a pointer to PKIX_Error) that is expected to return + * NULL (i.e. to succeed). If "pkixTestErrorResult" is not NULL, + * "goto cleanup" is executed, where a testError call is made if there were + * unexpected results. This macro MUST NOT be called after the "cleanup" label. + * + * Example Usage: PKIX_TEST_EXPECT_NO_ERROR(pkixFunc_expected_to_succeed(...)); + */ + +#define PKIX_TEST_EXPECT_NO_ERROR(func) \ + do { \ + pkixTestErrorResult = (func); \ + if (pkixTestErrorResult) { \ + goto cleanup; \ + } \ + } while (0) + +/* + * PKIX_TEST_EXPECT_ERROR should be used to wrap a standard PKIX function call + * (one which returns a pointer to PKIX_Error) that is expected to return + * a non-NULL value (i.e. to fail). If "pkixTestErrorResult" is NULL, + * "pkixTestErrorMsg" is set to a standard string and "goto cleanup" + * is executed, where a testError call is made if there were unexpected + * results. This macro MUST NOT be called after the "cleanup" label. + * + * Example Usage: PKIX_TEST_EXPECT_ERROR(pkixFunc_expected_to_fail(...)); + */ + +#define PKIX_TEST_EXPECT_ERROR(func) \ + do { \ + pkixTestErrorResult = (func); \ + if (!pkixTestErrorResult) { \ + pkixTestErrorMsg = \ + "Should have thrown an error here."; \ + goto cleanup; \ + } \ + PKIX_TEST_DECREF_BC(pkixTestErrorResult); \ + } while (0) + +/* + * PKIX_TEST_DECREF_BC is a convenience macro which should only be called + * BEFORE the "cleanup" label ("BC"). If the input parameter is non-NULL, it + * DecRefs the input parameter and wraps the function with + * PKIX_TEST_EXPECT_NO_ERROR, which executes "goto cleanup" upon error. + * This macro MUST NOT be called after the "cleanup" label. + */ + +#define PKIX_TEST_DECREF_BC(obj) \ + do { \ + if (obj) { \ + PKIX_TEST_EXPECT_NO_ERROR(PKIX_PL_Object_DecRef((PKIX_PL_Object *)(obj), plContext)); \ + obj = NULL; \ + } \ + } while (0) + +/* + * PKIX_TEST_DECREF_AC is a convenience macro which should only be called + * AFTER the "cleanup" label ("AC"). If the input parameter is non-NULL, it + * DecRefs the input parameter. A pkixTestTempResult variable is used to prevent + * incorrectly overwriting pkixTestErrorResult with NULL. + * In the case DecRef succeeds, pkixTestTempResult will be NULL, and we won't + * overwrite a previously set pkixTestErrorResult (if any). If DecRef fails, + * then we do want to overwrite a previously set pkixTestErrorResult since a + * DecRef failure is fatal and may be indicative of memory corruption. + */ + +#define PKIX_TEST_DECREF_AC(obj) \ + do { \ + if (obj) { \ + PKIX_Error *pkixTestTempResult = NULL; \ + pkixTestTempResult = \ + PKIX_PL_Object_DecRef((PKIX_PL_Object *)(obj), plContext); \ + if (pkixTestTempResult) \ + pkixTestErrorResult = pkixTestTempResult; \ + obj = NULL; \ + } \ + } while (0) + +/* + * PKIX_TEST_RETURN must always be AFTER the "cleanup" label. It does nothing + * if everything went as expected. However, if there were unexpected results, + * PKIX_TEST_RETURN calls testError, which displays a standard failure message + * and increments the number of subtests that have failed. In the case + * of an unexpected error, testError is called using the error's description + * as an input and the error is DecRef'd. In the case of unexpected success + * testError is called with a standard string. + */ +#define PKIX_TEST_RETURN() \ + { \ + if (pkixTestErrorMsg) { \ + testError(pkixTestErrorMsg); \ + } else if (pkixTestErrorResult) { \ + pkixTestErrorMsg = \ + PKIX_Error2ASCII(pkixTestErrorResult, plContext); \ + if (pkixTestErrorMsg) { \ + testError(pkixTestErrorMsg); \ + PKIX_PL_Free((PKIX_PL_Object *)pkixTestErrorMsg, \ + plContext); \ + } else { \ + testError("PKIX_Error2ASCII Failed"); \ + } \ + if (pkixTestErrorResult != PKIX_ALLOC_ERROR()) { \ + PKIX_PL_Object_DecRef((PKIX_PL_Object *)pkixTestErrorResult, \ + plContext); \ + pkixTestErrorResult = NULL; \ + } \ + } \ + } + +/* + * PKIX_TEST_EQ_HASH_TOSTR_DUP is a convenience macro which executes the + * standard set of operations that test the Equals, Hashcode, ToString, and + * Duplicate functions of an object type. The goodObj, equalObj, and diffObj + * are as the names suggest. The expAscii parameter is the expected result of + * calling ToString on the goodObj. If expAscii is NULL, then ToString will + * not be called on the goodObj. The checkDuplicate parameter is treated as + * a Boolean to indicate whether the Duplicate function should be tested. If + * checkDuplicate is NULL, then Duplicate will not be called on the goodObj. + * The type is the name of the function's family. For example, if the type is + * Cert, this macro will call PKIX_PL_Cert_Equals, PKIX_PL_Cert_Hashcode, and + * PKIX_PL_Cert_ToString. + * + * Note: If goodObj uses the default Equals and Hashcode functions, then + * for goodObj and equalObj to be equal, they must have the same pointer value. + */ +#define PKIX_TEST_EQ_HASH_TOSTR_DUP(goodObj, equalObj, diffObj, \ + expAscii, type, checkDuplicate) \ + do { \ + subTest("PKIX_PL_" #type "_Equals <match>"); \ + testEqualsHelper((PKIX_PL_Object *)(goodObj), \ + (PKIX_PL_Object *)(equalObj), \ + PKIX_TRUE, \ + plContext); \ + subTest("PKIX_PL_" #type "_Hashcode <match>"); \ + testHashcodeHelper((PKIX_PL_Object *)(goodObj), \ + (PKIX_PL_Object *)(equalObj), \ + PKIX_TRUE, \ + plContext); \ + subTest("PKIX_PL_" #type "_Equals <non-match>"); \ + testEqualsHelper((PKIX_PL_Object *)(goodObj), \ + (PKIX_PL_Object *)(diffObj), \ + PKIX_FALSE, \ + plContext); \ + subTest("PKIX_PL_" #type "_Hashcode <non-match>"); \ + testHashcodeHelper((PKIX_PL_Object *)(goodObj), \ + (PKIX_PL_Object *)(diffObj), \ + PKIX_FALSE, \ + plContext); \ + if (expAscii) { \ + subTest("PKIX_PL_" #type "_ToString"); \ + testToStringHelper((PKIX_PL_Object *)(goodObj), \ + (expAscii), \ + plContext); \ + } \ + if (checkDuplicate) { \ + subTest("PKIX_PL_" #type "_Duplicate"); \ + testDuplicateHelper((PKIX_PL_Object *)goodObj, plContext); \ + } \ + } while (0) + +/* + * PKIX_TEST_DECREF_BC is a convenience macro which should only be called + * BEFORE the "cleanup" label ("BC"). If the input parameter is non-NULL, it + * DecRefs the input parameter and wraps the function with + * PKIX_TEST_EXPECT_NO_ERROR, which executes "goto cleanup" upon error. + * This macro MUST NOT be called after the "cleanup" label. + */ + +#define PKIX_TEST_ABORT_ON_NULL(obj) \ + do { \ + if (!obj) { \ + goto cleanup; \ + } \ + } while (0) + +#define PKIX_TEST_ARENAS_ARG(arena) \ + (arena ? (PORT_Strcmp(arena, "arenas") ? PKIX_FALSE : (j++, PKIX_TRUE)) : PKIX_FALSE) + +#define PKIX_TEST_ERROR_RECEIVED (pkixTestErrorMsg || pkixTestErrorResult) + +/* see source file for function documentation */ + +void startTests(char *testName); + +void endTests(char *testName); + +void subTest(char *subTestName); + +void testError(char *msg); + +extern PKIX_Error * +_ErrorCheck(PKIX_Error *errorResult); + +extern PKIX_Error * +_OutputError(PKIX_Error *errorResult); + +char *PKIX_String2ASCII(PKIX_PL_String *string, void *plContext); + +char *PKIX_Error2ASCII(PKIX_Error *error, void *plContext); + +char *PKIX_Object2ASCII(PKIX_PL_Object *object); + +char *PKIX_Cert2ASCII(PKIX_PL_Cert *cert); + +void +testHashcodeHelper( + PKIX_PL_Object *goodObject, + PKIX_PL_Object *otherObject, + PKIX_Boolean match, + void *plContext); + +void +testToStringHelper( + PKIX_PL_Object *goodObject, + char *expected, + void *plContext); + +void +testEqualsHelper( + PKIX_PL_Object *goodObject, + PKIX_PL_Object *otherObject, + PKIX_Boolean match, + void *plContext); + +void +testDuplicateHelper( + PKIX_PL_Object *object, + void *plContext); +void +testErrorUndo(char *msg); + +#ifdef __cplusplus +} +#endif + +#endif /* TESTUTIL_H */ |