visualtest/include/SDL_visualtest_variator_common.h
author Ryan C. Gordon
Sun, 10 Nov 2013 00:32:23 -0500
changeset 7924 fcb86d323770
child 11382 2c50e79b19e0
permissions -rwxr-xr-x
Added Apoorv Upreti's GSoC2013 work: visual test suite.

See visualtest/README.txt for details.
     1 /* See COPYING.txt for the full license governing this code. */
     2 /**
     3  * \file SDL_visualtest_variator_common.h
     4  *
     5  * Header for common functionality used by variators.
     6  */
     7 
     8 #include <SDL_types.h>
     9 #include "SDL_visualtest_sut_configparser.h"
    10 
    11 #ifndef _SDL_visualtest_variator_common_h
    12 #define _SDL_visualtest_variator_common_h
    13 
    14 /** The number of variations one integer option would generate */
    15 #define SDL_SUT_INTEGER_OPTION_TEST_STEPS 3
    16 
    17 /* Set up for C function definitions, even when using C++ */
    18 #ifdef __cplusplus
    19 extern "C" {
    20 #endif
    21 
    22 /** enum for indicating the type of variator being used */
    23 typedef enum SDLVisualTest_VariatorType
    24 {
    25     SDL_VARIATOR_NONE = 0,
    26     SDL_VARIATOR_EXHAUSTIVE,
    27     SDL_VARIATOR_RANDOM
    28 } SDLVisualTest_VariatorType;
    29 
    30 /**
    31  * One possible value for a command line option to the SUT.
    32  */
    33 typedef union SDLVisualTest_SUTOptionValue
    34 {
    35     /*! Value if the option is of type boolean */
    36     SDL_bool bool_value;
    37     /*! Value if the option is of type integer. If on is true then the option
    38         will be passed to the SUT, otherwise it will be ignored. */
    39     struct {
    40         int value;
    41         SDL_bool on;
    42     } integer;
    43     /*! Index of the string in the enum_values field of the corresponding
    44         SDLVisualTest_SUTOption object. If on is true the option will passed
    45         to the SUT, otherwise it will be ignored. */
    46     struct {
    47         int index;
    48         SDL_bool on;
    49     } enumerated;
    50     /*! Value if the option is of type string. If on is true the option will 
    51         be passed to the SUT, otherwise it will be ignored. */
    52     struct {
    53         char* value;
    54         SDL_bool on;
    55     } string;
    56 } SDLVisualTest_SUTOptionValue;
    57 
    58 /**
    59  * Represents a valid combination of parameters that can be passed to the SUT.
    60  * The ordering of the values here is the same as the ordering of the options in
    61  * the SDLVisualTest_SUTConfig object for this variation.
    62  */
    63 typedef struct SDLVisualTest_Variation
    64 {
    65     /*! Pointer to array of option values */
    66     SDLVisualTest_SUTOptionValue* vars;
    67     /*! Number of option values in \c vars */
    68     int num_vars;
    69 } SDLVisualTest_Variation;
    70 
    71 /**
    72  * "Increments" the value of the option by one and returns the carry. We wrap
    73  * around to the initial value on overflow which makes the carry one.
    74  * For example: "incrementing" an SDL_FALSE option makes it SDL_TRUE with no
    75  * carry, and "incrementing" an SDL_TRUE option makes it SDL_FALSE with carry
    76  * one. For integers, a random value in the valid range for the option is used.
    77  *
    78  * \param var Value of the option
    79  * \param opt Object with metadata about the option
    80  *
    81  * \return 1 if there is a carry for enum and bool type options, 0 otherwise.
    82  *         1 is always returned for integer and string type options. -1 is
    83  *         returned on error.
    84  */
    85 int SDLVisualTest_NextValue(SDLVisualTest_SUTOptionValue* var,
    86                             SDLVisualTest_SUTOption* opt);
    87 
    88 /**
    89  * Converts a variation object into a string of command line arguments.
    90  *
    91  * \param variation Variation object to be converted.
    92  * \param config Config object for the SUT.
    93  * \param buffer Pointer to the buffer the arguments string will be copied into.
    94  * \param size Size of the buffer.
    95  *
    96  * \return 1 on success, 0 on failure
    97  */
    98 int SDLVisualTest_MakeStrFromVariation(SDLVisualTest_Variation* variation,
    99                                        SDLVisualTest_SUTConfig* config,
   100                                        char* buffer, int size);
   101 
   102 /**
   103  * Initializes the variation using the following rules:
   104  * - Boolean options are initialized to SDL_FALSE.
   105  * - Integer options are initialized to the minimum valid value they can hold.
   106  * - Enum options are initialized to the first element in the list of values they
   107  *   can take.
   108  * - String options are initialized to the name of the option.
   109  *
   110  * \return 1 on success, 0 on failure.
   111  */
   112 int SDLVisualTest_InitVariation(SDLVisualTest_Variation* variation,
   113                                 SDLVisualTest_SUTConfig* config);
   114 
   115 /* Ends C function definitions when using C++ */
   116 #ifdef __cplusplus
   117 }
   118 #endif
   119 
   120 #endif /* _SDL_visualtest_variator_common_h */