Index: Doxyfile ================================================================== --- Doxyfile +++ Doxyfile @@ -1,8 +1,8 @@ PROJECT_NAME = "ObjFW" OUTPUT_DIRECTORY = docs/ -INPUT = src src/exceptions src/runtime +INPUT = src src/exceptions src/runtime src/test FILE_PATTERNS = *.h *.m HTML_OUTPUT = . HAVE_DOT = NO GENERATE_LATEX = NO HIDE_UNDOC_CLASSES = YES @@ -46,6 +46,6 @@ SIGHUP \ SIGUSR1 \ SIGUSR2 MACRO_EXPANSION = YES EXPAND_ONLY_PREDEF = YES -IGNORE_PREFIX = OF of_ +IGNORE_PREFIX = OF OF_ OT OT_ Index: src/test/OTAssert.h ================================================================== --- src/test/OTAssert.h +++ src/test/OTAssert.h @@ -17,26 +17,149 @@ * Unfortunately, that's the only way to make all compilers happy with the GNU * extensions for variadic macros that are being used here. */ #pragma GCC system_header -#define OTAssert(cond, ...) \ - OTAssertImpl(self, _cmd, cond, @#cond, @__FILE__, __LINE__, \ - ## __VA_ARGS__, nil) -#define OTAssertTrue(cond, ...) OTAssert(cond == true, ## __VA_ARGS__) -#define OTAssertFalse(cond, ...) OTAssert(cond == false, ## __VA_ARGS__) +/** @file */ + +/** + * @brief Asserts that the specified condition condition holds. + * + * @param condition The condition to check + * @param ... An optional format string to print if the assertion failed, + * followed by optional arguments + */ +#define OTAssert(condition, ...) \ + OTAssertImpl(self, _cmd, condition, @#condition, \ + @__FILE__, __LINE__, ## __VA_ARGS__, nil) + +/** + * @brief Asserts that the specified condition is true. + * + * @param condition The condition to check + * @param ... An optional format string to print if the assertion failed, + * followed by optional arguments + */ +#define OTAssertTrue(condition, ...) \ + OTAssert(condition == true, ## __VA_ARGS__) + +/** + * @brief Asserts that the specified condition is false. + * + * @param condition The condition to check + * @param ... An optional format string to print if the assertion failed, + * followed by optional arguments + */ +#define OTAssertFalse(condition, ...) \ + OTAssert(condition == false, ## __VA_ARGS__) + +/** + * @brief Asserts that the two values are equal. + * + * @param a The value to check + * @param b The expected value + * @param ... An optional format string to print if the assertion failed, + * followed by optional arguments + */ #define OTAssertEqual(a, b, ...) OTAssert(a == b, ## __VA_ARGS__) + +/** + * @brief Asserts that the two values are not equal. + * + * @param a The value to check + * @param b The value `a` should not have + * @param ... An optional format string to print if the assertion failed, + * followed by optional arguments + */ #define OTAssertNotEqual(a, b, ...) OTAssert(a != b, ## __VA_ARGS__) + +/** + * @brief Asserts that the value is less than another value. + * + * @param a The value to check + * @param b The value `a` should be less than + * @param ... An optional format string to print if the assertion failed, + * followed by optional arguments + */ #define OTAssertLessThan(a, b, ...) OTAssert(a < b, ## __VA_ARGS__) + +/** + * @brief Asserts that the value is less than or equal to another value. + * + * @param a The value to check + * @param b The value `a` should be less than or equal to + * @param ... An optional format string to print if the assertion failed, + * followed by optional arguments + */ #define OTAssertLessThanOrEqual(a, b, ...) OTAssert(a <= b, ## __VA_ARGS__) + +/** + * @brief Asserts that the value is greater than another value. + * + * @param a The value to check + * @param b The value `a` should be greater than + * @param ... An optional format string to print if the assertion failed, + * followed by optional arguments + */ #define OTAssertGreaterThan(a, b, ...) OTAssert(a > b, ## __VA_ARGS__) + +/** + * @brief Asserts that the value is greater than or equal to another value. + * + * @param a The value to check + * @param b The value `a` should be greater than or equal to + * @param ... An optional format string to print if the assertion failed, + * followed by optional arguments + */ #define OTAssertGreaterThanOrEqual(a, b, ...) OTAssert(a >= b, ## __VA_ARGS__) + +/** + * @brief Asserts that the two objects are equal. + * + * @param a The object to check + * @param b The object `a` is expected to be equal to + * @param ... An optional format string to print if the assertion failed, + * followed by optional arguments + */ #define OTAssertEqualObjects(a, b, ...) OTAssert([a isEqual: b], ## __VA_ARGS__) + +/** + * @brief Asserts that the two objects are not equal. + * + * @param a The object to check + * @param b The object `a` is expected to be not equal to + * @param ... An optional format string to print if the assertion failed, + * followed by optional arguments + */ #define OTAssertNotEqualObjects(a, b, ...) \ OTAssert(![a isEqual: b], ## __VA_ARGS__) + +/** + * @brief Asserts that the specified object is `nil`. + * + * @param object The object to should be `nil` + * @param ... An optional format string to print if the assertion failed, + * followed by optional arguments + */ #define OTAssertNil(object, ...) OTAssert(object == nil, ## __VA_ARGS__) + +/** + * @brief Asserts that the specified object is not `nil`. + * + * @param object The object to should not be `nil` + * @param ... An optional format string to print if the assertion failed, + * followed by optional arguments + */ #define OTAssertNotNil(object, ...) OTAssert(object != nil, ## __VA_ARGS__) + +/** + * @brief Asserts that the specified expression throws an exception. + * + * @param expression The expression that should throw + * @param ... An optional format string to print if the assertion failed, + * followed by optional arguments + */ #define OTAssertThrows(expression, ...) \ { \ bool OTThrown = false; \ @try { \ expression; \ @@ -43,10 +166,20 @@ } @catch (id e) { \ OTThrown = true; \ } \ OTAssert(OTThrown, ## __VA_ARGS__); \ } + +/** + * @brief Asserts that the specified expression throws a specific exception. + * + * @param expression The expression that should throw + * @param exception The exception the expression should throw (as just the + * class name, without quotes) + * @param ... An optional format string to print if the assertion failed, + * followed by optional arguments + */ #define OTAssertThrowsSpecific(expression, exception, ...) \ { \ bool OTThrown = false; \ @try { \ expression; \ @@ -53,10 +186,17 @@ } @catch (exception *e) { \ OTThrown = true; \ } \ OTAssert(OTThrown, ## __VA_ARGS__); \ } + +/** + * @brief Skips the current test, making it neither fail nor succeeed. + * + * @param ... An optional format string to print why the test was skipped, + * followed by optional arguments + */ #define OTSkip(...) \ OTSkipImpl(self, _cmd, @__FILE__, __LINE__, ## __VA_ARGS__, nil) #ifdef __cplusplus extern "C" { Index: src/test/OTOrderedDictionary.h ================================================================== --- src/test/OTOrderedDictionary.h +++ src/test/OTOrderedDictionary.h @@ -19,13 +19,21 @@ # import #endif OF_ASSUME_NONNULL_BEGIN +/** + * @brief A dictionary that enumerates keys and objects in the same order they + * were specified during initialization. + * + * @warning This class is only for testing! It is slow and only to be used to + * test extensions of OFDictionary, for example serializations such as + * JSON, where it is desirable to compare to an expected output. + */ @interface OTOrderedDictionary: OFDictionary { OFArray *_keys; OFArray *_objects; } @end OF_ASSUME_NONNULL_END Index: src/test/OTTestCase.h ================================================================== --- src/test/OTTestCase.h +++ src/test/OTTestCase.h @@ -19,17 +19,39 @@ # import #endif OF_ASSUME_NONNULL_BEGIN +/** + * @brief A class meant for subclassing to create a test case, consisting of + * one or more tests. + * + * All methods with the prefix `test` that take no arguments of all classes + * that subclass this class are automatically executed by ObjFWTest. + */ @interface OTTestCase: OFObject #ifdef OF_HAVE_CLASS_PROPERTIES @property (class, readonly, nullable, nonatomic) OFArray OF_GENERIC(OFPair OF_GENERIC(OFString *, id) *) *summary; #endif +/** + * @brief Returns a summary for the test case that should be printed once all + * tests in all test cases were run. + * + * This is mostly useful to print something at the end of all tests that needs + * manual verification. + */ + (nullable OFArray OF_GENERIC(OFPair OF_GENERIC(OFString *, id) *) *)summary; + +/** + * @brief Set up method that is run before every test in the test case. + */ - (void)setUp; + +/** + * @brief Tear down method that is run after every test in the test case. + */ - (void)tearDown; @end OF_ASSUME_NONNULL_END