Module: wine Branch: master Commit: 65261f3c80e6cfe96081d3903c7483f99648f9b6 URL: https://gitlab.winehq.org/wine/wine/-/commit/65261f3c80e6cfe96081d3903c7483f...
Author: Francois Gouget fgouget@codeweavers.com Date: Thu Sep 28 14:40:02 2023 +0200
tests: Update the documentation.
---
include/wine/test.h | 70 +++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 65 insertions(+), 5 deletions(-)
diff --git a/include/wine/test.h b/include/wine/test.h index 889923afacc..8f3f3bb0d50 100644 --- a/include/wine/test.h +++ b/include/wine/test.h @@ -148,6 +148,13 @@ extern void winetest_wait_child_process( HANDLE process ); # define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) #endif
+/* Records the location of the next check. + * See the xxx_(file, line) macros. + * + * Parameters: + * - file - source file name of the check + * - line - source line number of the check + */ static inline void winetest_set_location( const char *file, int line ) { struct winetest_thread_data *data = winetest_get_thread_data(); @@ -260,12 +267,13 @@ static LONG winetest_add_line( void ) }
/* - * Checks condition. + * Checks that a condition has the expected value, that is true except if + * preceded by a todo indicating the check is expected to fail. + * * Parameters: - * - condition - condition to check; - * - msg test description; - * - file - test application source code file name of the check - * - line - test application source code file line number of the check + * - condition - true if the check succeeded, false otherwise; + * - msg - failure message format; + * - args - arguments for the failure message * Return: * 0 if condition does not have the expected value, 1 otherwise */ @@ -400,6 +408,14 @@ static void winetest_vskip( const char *msg, va_list args ) else InterlockedIncrement( &winetest_muted_skipped ); }
+/* + * Prints a message to indicate that a group of tests is being skipped + * because the requirements for running them are not met. + * + * Parameters: + * - msg - failure message format; + * - args - arguments for the failure message + */ static void winetest_skip( const char *msg, ... ) __WINE_PRINTF_ATTR(1,2); static inline void winetest_skip( const char *msg, ... ) { @@ -421,6 +437,18 @@ static inline void winetest_win_skip( const char *msg, ... ) va_end(valist); }
+/* If is_flaky is true, indicates that the next test may occasionally fail due + * to unavoidable outside race conditions. Such failures will be flagged as + * flaky so they can be ignored by automated testing tools. + * + * Remarks: + * - This is not meant to paper over race conditions within the test itself. + * Those are bugs and should be fixed. + * - This is not meant to be used for tests that normally succeed but + * systematically fail on a specific platform or locale. + * - The failures should be rare to start with. If a test fails 25% of the time + * it is probably wrong. + */ static inline void winetest_start_flaky( int is_flaky ) { struct winetest_thread_data *data = winetest_get_thread_data(); @@ -442,6 +470,13 @@ static inline void winetest_end_flaky(void) data->flaky_level >>= 1; }
+/* If is_todo is true, indicates that the next test is expected to fail on this + * platform. This is used to identify tests that are known to fail in Wine. + * + * Remarks: + * - is_todo should never be true on Windows. To ensure this, always use + * todo_wine_if(). + */ static inline void winetest_start_todo( int is_todo ) { struct winetest_thread_data *data = winetest_get_thread_data(); @@ -463,6 +498,31 @@ static inline void winetest_end_todo(void) data->todo_level >>= 1; }
+/* Adds a string to be prepended to the test traces and failure messages. + * This must be paired with a winetest_pop_context() call. + * + * Parameters: + * - msg - failure message format; + * - args - arguments for the failure message + * + * Remarks: + * - Failure messages must always make it possible to figure out what was being + * tested. While not ideal the line number can usually be used for that + * purpose except when the test loops on a list of test parameters. In such + * cases either the test parameters or the loop index should be added to the + * context. + * + * Example: + * + * for (i = 0; i < ARRAY_SIZE(test_parameters); i++) + * { + * winetest_push_context("%d", i); + * ... + * ok(WinAPI(test_parameters[i]), ...); + * ... + * winetest_pop_context(); + * } + */ static void winetest_push_context( const char *fmt, ... ) __WINE_PRINTF_ATTR(1, 2); static inline void winetest_push_context( const char *fmt, ... ) {