test/automated/SDL_at.h
author David Ludwig <dludwig@pobox.com>
Tue, 12 Feb 2013 12:57:06 -0500
changeset 8424 3cf9501008f1
parent 3482 78db4f7ae2f3
permissions -rw-r--r--
WinRT: fixed bug: SDL_CreateWindow wouldn't work after an initial window was created + destroyed
     1 /*
     2  * Common code for automated test suite.
     3  *
     4  * Written by Edgar Simo "bobbens"
     5  *
     6  * Released under Public Domain.
     7  */
     8 
     9 
    10 /**
    11  * @file SDL_at.h
    12  *
    13  * @brief Handles automatic testing functionality.
    14  *
    15  * The basic approach with SDL_AT is to divide the tests into what are called
    16  *  test suites and test cases. Each test suite should have multiple test
    17  *  cases, each test case can have multiple asserts.
    18  *
    19  * To actually test for conditions within the testcase you check asserts, if
    20  *  the asserts fail the failures will be logged in the testsuite and
    21  *  displayed.
    22  *
    23  *  Syntax is similar to OpenGL. An example would be:
    24  *
    25  * @code
    26  * int f; // Number failed
    27  * SDL_ATinit( "My testsuite" );
    28  *
    29  * SDL_ATbegin( "My first testcase" );
    30  * if (!SDL_ATassert( (1+1)==2, "Trying '1+1=2'."))
    31  *    return; // Implicitly calls SDL_ATend if assert fails
    32  * SDL_ATend(); // Finish testcase
    33  *
    34  * SDL_ATbegin( "My second testcase" );
    35  * if (!SDL_ATassert( (4/2)==2, "Trying '4/2=2'."))
    36  *    return; // Implicitly calls SDL_ATend if assert fails
    37  * SDL_ATend(); // Finish testcase
    38  *
    39  * f = SDL_ATfinish();
    40  * @endcode
    41  *
    42  * @author Edgar Simo "bobbens"
    43  */
    44 
    45 
    46 #ifndef _SDL_AT_H
    47 #  define _SDL_AT_H
    48 
    49 
    50 
    51 enum {
    52    SDL_AT_VERBOSE, /**< Sets the verbose level. */
    53    SDL_AT_QUIET /**< Sets quietness. */
    54 };
    55 
    56 
    57 /*
    58  * Suite level actions.
    59  */
    60 /**
    61  * @brief Starts the testsuite.
    62  *
    63  *    @param suite Name of the suite to start testing.
    64  */
    65 void SDL_ATinit( const char *suite );
    66 /**
    67  * @brief Finishes the testsuite printing out global results if verbose.
    68  *
    69  *    @return 0 if no errors occurred, otherwise number of failures.
    70  */
    71 int SDL_ATfinish (void);
    72 /**
    73  * @brief Sets a global property value.
    74  *
    75  *    @param property Property to set.
    76  *    @param value Value to set property to.
    77  */
    78 void SDL_ATseti( int property, int value );
    79 /**
    80  * @brief Gets a global property value.
    81  *
    82  *    @param property Property to get.
    83  *    @param[out] value Value of the property.
    84  */
    85 void SDL_ATgeti( int property, int *value );
    86 
    87 
    88 /*
    89  * Testcase level actions.
    90  */
    91 /**
    92  * @brief Begins a testcase.
    93  *
    94  *    @param testcase Name of the testcase to begin.
    95  */
    96 void SDL_ATbegin( const char *testcase );
    97 /**
    98  * @brief Checks a condition in the testcase.
    99  *
   100  * Will automatically call SDL_ATend if the condition isn't met.
   101  *
   102  *    @param condition Condition to make sure is true.
   103  *    @param msg Message to display for failure.
   104  *    @return Returns 1 if the condition isn't met.
   105  */
   106 int SDL_ATassert( const char *msg, int condition );
   107 /**
   108  * @brief Checks a condition in the testcase.
   109  *
   110  * Will automatically call SDL_ATend if the condition isn't met.
   111  *
   112  *    @param condition Condition to make sure is true.
   113  *    @param msg Message to display for failure with printf style formatting.
   114  *    @return Returns 1 if the condition isn't met.
   115  */
   116 int SDL_ATvassert( int condition, const char *msg, ... );
   117 /**
   118  * @brief Ends a testcase.
   119  */
   120 void SDL_ATend (void);
   121 
   122 
   123 /*
   124  * Misc functions.
   125  */
   126 /**
   127  * @brief Prints an error.
   128  *
   129  *    @param msg printf formatted string to display.
   130  *    @return Number of character printed.
   131  */
   132 int SDL_ATprintErr( const char *msg, ... );
   133 /**
   134  * @brief Prints some text.
   135  *
   136  *    @param msg printf formatted string to display.
   137  *    @return Number of character printed.
   138  */
   139 int SDL_ATprint( const char *msg, ... );
   140 /**
   141  * @brief Prints some verbose text.
   142  *
   143  * Verbosity levels are as follows:
   144  *
   145  *  - 0 standard stdout, enabled by default
   146  *  - 1 additional information
   147  *  - 2 detailed information (spammy)
   148  *
   149  *    @param level Level of verbosity to print at.
   150  *    @param msg printf formatted string to display.
   151  *    @return Number of character printed.
   152  */
   153 int SDL_ATprintVerbose( int level, const char *msg, ... );
   154 
   155 
   156 #endif /* _SDL_AT_H */
   157 
   158