test/cairo-test.h

   1 /*
   2  * Copyright © 2004 Red Hat, Inc.
   3  *
   4  * Permission to use, copy, modify, distribute, and sell this software
   5  * and its documentation for any purpose is hereby granted without
   6  * fee, provided that the above copyright notice appear in all copies
   7  * and that both that copyright notice and this permission notice
   8  * appear in supporting documentation, and that the name of
   9  * Red Hat, Inc. not be used in advertising or publicity pertaining to
  10  * distribution of the software without specific, written prior
  11  * permission. Red Hat, Inc. makes no representations about the
  12  * suitability of this software for any purpose.  It is provided "as
  13  * is" without express or implied warranty.
  14  *
  15  * RED HAT, INC. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
  16  * SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
  17  * FITNESS, IN NO EVENT SHALL RED HAT, INC. BE LIABLE FOR ANY SPECIAL,
  18  * INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER
  19  * RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
  20  * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
  21  * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  22  *
  23  * Author: Carl D. Worth <cworth@cworth.org>
  24  */
  25
  26 #ifndef _CAIRO_TEST_H_
  27 #define _CAIRO_TEST_H_
  28
  29 #include "cairo-boilerplate.h"
  30
  31 #include <stdarg.h>
  32
  33 CAIRO_BEGIN_DECLS
  34
  35 #if   HAVE_STDINT_H
  36 # include <stdint.h>
  37 #elif HAVE_INTTYPES_H
  38 # include <inttypes.h>
  39 #elif HAVE_SYS_INT_TYPES_H
  40 # include <sys/int_types.h>
  41 #elif defined(_MSC_VER)
  42 typedef __int8 int8_t;
  43 typedef unsigned __int8 uint8_t;
  44 typedef __int16 int16_t;
  45 typedef unsigned __int16 uint16_t;
  46 typedef __int32 int32_t;
  47 typedef unsigned __int32 uint32_t;
  48 typedef __int64 int64_t;
  49 typedef unsigned __int64 uint64_t;
  50 # ifndef HAVE_UINT64_T
  51 #  define HAVE_UINT64_T 1
  52 # endif
  53 #else
  54 #error Cannot find definitions for fixed-width integral types (uint8_t, uint32_t, \etc.)
  55 #endif
  56
  57 #ifdef _MSC_VER
  58 #define _USE_MATH_DEFINES
  59
  60 #include <float.h>
  61 #define isnan(x) _isnan(x)
  62
  63 #endif
  64
  65 #if HAVE_FENV_H
  66 # include <fenv.h>
  67 #endif
  68 /* The following are optional in C99, so define them if they aren't yet */
  69 #ifndef FE_DIVBYZERO
  70 #define FE_DIVBYZERO 0
  71 #endif
  72 #ifndef FE_INEXACT
  73 #define FE_INEXACT 0
  74 #endif
  75 #ifndef FE_INVALID
  76 #define FE_INVALID 0
  77 #endif
  78 #ifndef FE_OVERFLOW
  79 #define FE_OVERFLOW 0
  80 #endif
  81 #ifndef FE_UNDERFLOW
  82 #define FE_UNDERFLOW 0
  83 #endif
  84
  85 #include <math.h>
  86
  87 static inline double
  88 cairo_test_NaN (void)
  89 {
  90 #ifdef _MSC_VER
  91     /* MSVC strtod("NaN", NULL) returns 0.0 */
  92     union {
  93         uint32_t i[2];
  94         double d;
  95     } nan = {{0xffffffff, 0x7fffffff}};
  96     return nan.d;
  97 #else
  98     return strtod("NaN", NULL);
  99 #endif
 100 }
 101
 102 #ifndef MIN
 103 #define MIN(a, b) ((a) < (b) ? (a) : (b))
 104 #endif
 105
 106 #ifndef MAX
 107 #define MAX(a, b) ((a) > (b) ? (a) : (b))
 108 #endif
 109
 110 #ifndef ARRAY_LENGTH
 111 #define ARRAY_LENGTH(__array) ((int) (sizeof (__array) / sizeof (__array[0])))
 112 #endif
 113
 114 #define CAIRO_TEST_OUTPUT_DIR "output"
 115
 116 #define CAIRO_TEST_LOG_SUFFIX ".log"
 117
 118 #define CAIRO_TEST_FONT_FAMILY "DejaVu"
 119
 120 /* What is a fail and what isn't?
 121  * When running the test suite we want to detect unexpected output. This
 122  * can be caused by a change we have made to cairo itself, or a change
 123  * in our environment. To capture this we classify the expected output into 3
 124  * classes:
 125  *
 126  *   REF  -- Perfect output.
 127  *           Might be different for each backend, due to slight implementation
 128  *           differences.
 129  *
 130  *   NEW  -- A new failure. We have uncovered a bug within cairo and have
 131  *           recorded the current failure (along with the expected output
 132  *           if possible!) so we can detect any changes in our attempt to
 133  *           fix the bug.
 134  *
 135  *  XFAIL -- An external failure. We believe the cairo output is perfect,
 136  *           but an external renderer is causing gross failure.
 137  *           (We also use this to capture current WONTFIX issues within cairo,
 138  *           such as overflow in internal coordinates, so as not to distract
 139  *           us when regression testing.)
 140  *
 141  *  If no REF is given for a test, then it is assumed to be XFAIL.
 142  */
 143 #define CAIRO_TEST_REF_SUFFIX ".ref"
 144 #define CAIRO_TEST_XFAIL_SUFFIX ".xfail"
 145 #define CAIRO_TEST_NEW_SUFFIX ".new"
 146
 147 #define CAIRO_TEST_OUT_SUFFIX ".out"
 148 #define CAIRO_TEST_DIFF_SUFFIX ".diff"
 149
 150 #define CAIRO_TEST_PNG_EXTENSION ".png"
 151 #define CAIRO_TEST_OUT_PNG CAIRO_TEST_OUT_SUFFIX CAIRO_TEST_PNG_EXTENSION
 152 #define CAIRO_TEST_REF_PNG CAIRO_TEST_REF_SUFFIX CAIRO_TEST_PNG_EXTENSION
 153 #define CAIRO_TEST_DIFF_PNG CAIRO_TEST_DIFF_SUFFIX CAIRO_TEST_PNG_EXTENSION
 154
 155 typedef enum cairo_test_status {
 156     CAIRO_TEST_SUCCESS = 0,
 157     CAIRO_TEST_NO_MEMORY,
 158     CAIRO_TEST_FAILURE,
 159     CAIRO_TEST_NEW,
 160     CAIRO_TEST_XFAILURE,
 161     CAIRO_TEST_ERROR,
 162     CAIRO_TEST_CRASHED,
 163     CAIRO_TEST_UNTESTED = 77 /* match automake's skipped exit status */
 164 } cairo_test_status_t;
 165
 166 typedef struct _cairo_test_context cairo_test_context_t;
 167 typedef struct _cairo_test cairo_test_t;
 168
 169 typedef cairo_test_status_t
 170 (cairo_test_preamble_function_t) (cairo_test_context_t *ctx);
 171
 172 typedef cairo_test_status_t
 173 (cairo_test_draw_function_t) (cairo_t *cr, int width, int height);
 174
 175 struct _cairo_test {
 176     const char *name;
 177     const char *description;
 178     const char *keywords;
 179     const char *requirements;
 180     double width;
 181     double height;
 182     cairo_test_preamble_function_t *preamble;
 183     cairo_test_draw_function_t *draw;
 184 };
 185
 186 /* The standard test interface which works by examining result image.
 187  *
 188  * CAIRO_TEST() constructs a test which will be called once before (the
 189  * preamble callback), and then once for each testable backend (the draw
 190  * callback). The following checks will be performed for each backend:
 191  *
 192  * 1) If preamble() returns CAIRO_TEST_UNTESTED, the test is skipped.
 193  *
 194  * 2) If preamble() does not return CAIRO_TEST_SUCCESS, the test fails.
 195  *
 196  * 3) If draw() does not return CAIRO_TEST_SUCCESS then this backend
 197  *    fails.
 198  *
 199  * 4) Otherwise, if cairo_status(cr) indicates an error then this
 200  *    backend fails.
 201  *
 202  * 5) Otherwise, if the image size is 0, then this backend passes.
 203  *
 204  * 6) Otherwise, if every channel of every pixel exactly matches the
 205  *    reference image then this backend passes. If not, this backend
 206  *    fails.
 207  *
 208  * The overall test result is PASS if and only if there is at least
 209  * one backend that is tested and if all tested backend pass according
 210  * to the four criteria above.
 211  */
 212 #define CAIRO_TEST(name, description, keywords, requirements, width, height, preamble, draw) \
 213 void _register_##name (void); \
 214 void _register_##name (void) { \
 215     static cairo_test_t test = { \
 216         #name, description, \
 217         keywords, requirements, \
 218         width, height, \
 219         preamble, draw \
 220     }; \
 221     cairo_test_register (&test); \
 222 }
 223
 224 void
 225 cairo_test_register (cairo_test_t *test);
 226
 227 /* The full context for the test.
 228  * For ordinary tests (using the CAIRO_TEST()->draw interface) the context
 229  * is passed to the draw routine via user_data on the cairo_t.
 230  * The reason why the context is not passed as an explicit parameter is that
 231  * it is rarely required by the test itself and by removing the parameter
 232  * we can keep the draw routines simple and serve as example code.
 233  *
 234  * In contrast, for the preamble phase the context is passed as the only
 235  * parameter.
 236  */
 237 struct _cairo_test_context {
 238     const cairo_test_t *test;
 239     const char *test_name;
 240
 241     FILE *log_file;
 242     const char *output;
 243     const char *srcdir; /* directory containing sources and input data */
 244     const char *refdir; /* directory containing reference images */
 245
 246     char *ref_name; /* cache of the current reference image */
 247     cairo_surface_t *ref_image;
 248     cairo_surface_t *ref_image_flattened;
 249
 250     size_t num_targets;
 251     cairo_bool_t limited_targets;
 252     const cairo_boilerplate_target_t **targets_to_test;
 253     cairo_bool_t own_targets;
 254
 255     int malloc_failure;
 256     int last_fault_count;
 257
 258     int timeout;
 259 };
 260
 261 /* Retrieve the test context from the cairo_t, used for logging, paths etc */
 262 const cairo_test_context_t *
 263 cairo_test_get_context (cairo_t *cr);
 264
 265
 266 /* Print a message to the log file, ala printf. */
 267 void
 268 cairo_test_log (const cairo_test_context_t *ctx,
 269                 const char *fmt, ...) CAIRO_BOILERPLATE_PRINTF_FORMAT(2, 3);
 270 void
 271 cairo_test_logv (const cairo_test_context_t *ctx,
 272                 const char *fmt, va_list ap) CAIRO_BOILERPLATE_PRINTF_FORMAT(2, 0);
 273
 274 /* Helper functions that take care of finding source images even when
 275  * building in a non-srcdir manner, (i.e. the tests will be run in a
 276  * directory that is different from the one where the source image
 277  * exists). */
 278 cairo_surface_t *
 279 cairo_test_create_surface_from_png (const cairo_test_context_t *ctx,
 280                                     const char *filename);
 281
 282 cairo_pattern_t *
 283 cairo_test_create_pattern_from_png (const cairo_test_context_t *ctx,
 284                                     const char *filename);
 285
 286 void
 287 cairo_test_paint_checkered (cairo_t *cr);
 288
 289 #define CAIRO_TEST_DOUBLE_EQUALS(a,b)  (fabs((a)-(b)) < 0.00001)
 290
 291 cairo_bool_t
 292 cairo_test_is_target_enabled (const cairo_test_context_t *ctx,
 293                               const char *target);
 294
 295 char *
 296 cairo_test_get_name (const cairo_test_t *test);
 297
 298 cairo_bool_t
 299 cairo_test_malloc_failure (const cairo_test_context_t *ctx,
 300                            cairo_status_t status);
 301
 302 cairo_test_status_t
 303 cairo_test_status_from_status (const cairo_test_context_t *ctx,
 304                                cairo_status_t status);
 305
 306 char *
 307 cairo_test_reference_filename (const cairo_test_context_t *ctx,
 308                                const char *base_name,
 309                                const char *test_name,
 310                                const char *target_name,
 311                                const char *base_target_name,
 312                                const char *format,
 313                                const char *suffix,
 314                                const char *extension);
 315
 316 cairo_surface_t *
 317 cairo_test_get_reference_image (cairo_test_context_t *ctx,
 318                                 const char *filename,
 319                                 cairo_bool_t flatten);
 320
 321 CAIRO_END_DECLS
 322
 323 #endif