/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
 57extern "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
284void startTests(char *testName);
285
286void endTests(char *testName);
287
288void subTest(char *subTestName);
289
290void testError(char *msg);
291
292extern PKIX_Error *
293_ErrorCheck(PKIX_Error *errorResult);
294
295extern PKIX_Error *
296_OutputError(PKIX_Error *errorResult);
297
298char* PKIX_String2ASCII(PKIX_PL_String *string, void *plContext);
299
300char* PKIX_Error2ASCII(PKIX_Error *error, void *plContext);
301
302char* PKIX_Object2ASCII(PKIX_PL_Object *object);
303
304char *PKIX_Cert2ASCII(PKIX_PL_Cert *cert);
305
306void
307testHashcodeHelper(
308        PKIX_PL_Object *goodObject,
309        PKIX_PL_Object *otherObject,
310        PKIX_Boolean match,
311        void *plContext);
312
313void
314testToStringHelper(
315        PKIX_PL_Object *goodObject,
316        char *expected,
317        void *plContext);
318
319void
320testEqualsHelper(
321        PKIX_PL_Object *goodObject,
322        PKIX_PL_Object *otherObject,
323        PKIX_Boolean match,
324        void *plContext);
325
326void
327testDuplicateHelper(
328        PKIX_PL_Object *object,
329        void *plContext);
330void
331testErrorUndo(char *msg);
332
333#ifdef __cplusplus
334}
335#endif
336
337#endif /* TESTUTIL_H */