From a4b0519303834905aa783af14f37160db738d667 Mon Sep 17 00:00:00 2001 From: John Ralls Date: Tue, 28 Jul 2015 12:44:25 -0700 Subject: [PATCH] Fix up and improve the Doxygen documentation in unittest-support.h. --- src/test-core/unittest-support.h | 85 ++++++++++++++++++++++++-------- test-templates/README | 3 +- 2 files changed, 67 insertions(+), 21 deletions(-) diff --git a/src/test-core/unittest-support.h b/src/test-core/unittest-support.h index fa4d07bbf6..3497d902f0 100644 --- a/src/test-core/unittest-support.h +++ b/src/test-core/unittest-support.h @@ -25,11 +25,22 @@ #include #include +/** @file unittest-support.h + * @brief Macros and logging-capture functions to ease writing GLib-testing + * based unit tests. + */ + +/** @name Unit Test Macros + * These macros facilitate combining a suite name and a test name to make a path + * when registering a test function with the corresponding g_test_add and + * g_test_add_func. Create a const char* suitename somewhere in the file and + * pass it as the first parameter, and the test name as the second. The + * remaining parameters are the same as in the underlying function. + */ /** - * Use this macro to format informative test path output when using g_test_add. - * Suite stands for tests' pack, while path for individual test name. -*/ + * Wraps gnc_test_add() for test functions needing a fixture. + */ #define GNC_TEST_ADD( suite, path, fixture, data, setup, test, teardown )\ {\ @@ -39,9 +50,8 @@ } /** - * Use this macro to format informative test path output when using g_test_add_func. - * Suite stands for tests' pack, while path for individual test name. -*/ + * Wraps gnc_test_add_func() for test functions which don't require a fixture. + */ #define GNC_TEST_ADD_FUNC( suite, path, test )\ {\ @@ -49,9 +59,8 @@ g_test_add_func( testpath, test );\ g_free( testpath );\ } - -/** - * Suppressing Expected Errors +/** @} */ +/** @name Suppressing Expected Errors * * Functions for suppressing expected errors during tests. Pass * @@ -74,6 +83,7 @@ * NB: If you have more than one fatal error in a test function be * sure to use the test_list_handler: You can have only one fatal * handler. + * @{ */ /** @@ -115,6 +125,11 @@ TestErrorStruct* test_error_struct_new (gchar *log_domain, */ void test_error_struct_free (TestErrorStruct *); +/** + * Holds a handler instance with its TestErrorStruct, handler id, and whether + * it's a list handler. A test fixture can be set up to hold a GSList of these + * so that they can be automatically unregistered and freed during teardown. + */ typedef struct { TestErrorStruct *error; @@ -158,7 +173,9 @@ GSList *test_log_set_handler (GSList *list, TestErrorStruct *error, GSList *test_log_set_fatal_handler (GSList *list, TestErrorStruct *error, GLogFunc handler); -/* Clears all the log handlers. Pass this to g_slist_free() in teardown */ +/** + * Clears all the log handlers. Pass this to g_slist_free() in teardown. + */ void test_free_log_handler (gpointer item); /** @@ -193,8 +210,7 @@ gboolean test_null_handler (const char *log_domain, GLogLevelFlags log_level, * Call test_add_error for each TestErrorStruct to check against and * test_clear_error_list when you no longer expect the errors. */ -void test_add_error (TestErrorStruct *error); -void test_clear_error_list (void); +void test_add_error (TestErrorStruct *error)voidvoid test_clear_error_list (void); /** * Checks received errors against the list created by @@ -236,7 +252,14 @@ gpointer test_reset_data( void ); */ void test_free( gpointer data ); -/* TestSignal is an opaque struct used to mock handling signals +/** @} + */ +/** @name Test Signals + * Test the emission of signals from objects. Signals are used to coordinate the + * behavior of the GUI with events in other parts of the program. @{ + */ +/** + * TestSignal is an opaque struct used to mock handling signals * emitted by functions-under-test. It registers a handler and counts * how many times it is called with the right instance and type. The * struct is allocated using g_slice_new, and it registers a @@ -249,30 +272,51 @@ void test_free( gpointer data ); * passed to test_signal_new should be NULL to avoid the test. */ typedef gpointer TestSignal; + +/** + * Create a test signal. + * @param entity: The QofInstance emitting the signal + * @param eventType: The type of the signal + * @param event_data: Any data required by the signal or NULL if none is. + * @return A newly created TestSignal. Use test_signal_free to release it. + */ + TestSignal test_signal_new (QofInstance *entity, QofEventId eventType, gpointer event_data); -/* test_signal_return_hits gets the number of times the TestSignal has - * been called. +/** + * gets the number of times the TestSignal has been called. */ guint test_signal_return_hits (TestSignal sig); -/* test_signal_assert_hits is a convenience macro which wraps - * test_signal_return_hits with and equality assertion. +/** + * Convenience macro which wraps test_signal_return_hits with and equality + * assertion. */ #define test_signal_assert_hits(sig, hits) \ g_assert_cmpint (test_signal_return_hits (sig), ==, hits) +/** + * Free a test signal. + */ void test_signal_free (TestSignal sig); -/* test_object_checked_destroy unrefs obj and returns true if its finalize - * method was called. +/** @} + */ + +/** @name Testing for object disposal + * Sometimes we need to make sure that certain objects that we've created aren't leaking. These functions can help. + * @{ + */ + +/** + * Unrefs obj and returns true if its finalize method was called. */ gboolean test_object_checked_destroy (GObject *obj); /** - * test_destroy() ensures that a GObject is still alive at the time + * Ensures that a GObject is still alive at the time * it's called and that it is finalized. The first assertion will * trigger if you pass it a ponter which isn't a GObject -- which * could be the case if the object has already been finalized. Then it @@ -284,6 +328,7 @@ gboolean test_object_checked_destroy (GObject *obj); g_assert (obj != NULL && G_IS_OBJECT (obj)); \ g_assert (test_object_checked_destroy (G_OBJECT (obj))) +/** @} */ /* For Scheme testing access: void gnc_log_init_filename_special (gchar *filename); void gnc_log_shutdown (void); diff --git a/test-templates/README b/test-templates/README index 0a5a026dc3..10d8fa6baf 100644 --- a/test-templates/README +++ b/test-templates/README @@ -40,4 +40,5 @@ and http://library.gnome.org/devel/glib/stable/glib-Testing.html for detailed documentation. There are some helpful macros and message-trapping functions in -src/test-core/unittest-support.h. +src/test-core/unittest-support.h, whose Doxygen documentation is at +http://code.gnucash.org/docs/head/unittest-support_8h_source.html