Documentation/test-suite

   1
   2
   3         Sparse test suite
   4         ~~~~~~~~~~~~~~~~~
   5
   6 Sparse has a number of test cases in its validation directory. The test-suite
   7 script aims at making automated checking of these tests possible. It works by
   8 embedding tags in C comments in the test cases.
   9
  10 check-name: (mandatory)
  11         Name of the test.
  12
  13 check-description: (optional)
  14         A description of what the test checks.
  15
  16 check-command: (optional)
  17         There are different kinds of tests. Some can validate the sparse
  18         preprocessor, while others will use sparse, cgcc, or even other backends
  19         of the library. check-command allows you to give a custom command to
  20         run the test-case.
  21         The '$file' string is special. It will be expanded to the file name at
  22         run time.
  23         It defaults to "sparse $file".
  24
  25 check-exit-value: (optional)
  26         The expected exit value of check-command. It defaults to 0.
  27
  28 check-timeout: (optional)
  29         The maximum expected duration of check-command, in seconds.
  30         It defaults to 1.
  31
  32 check-output-start / check-output-end (optional)
  33         The expected output (stdout and stderr) of check-command lies between
  34         those two tags. It defaults to no output.
  35
  36 check-output-ignore / check-error-ignore (optional)
  37         Don't check the expected output (stdout or stderr) of check-command
  38         (useful when this output is not comparable or if you're only interested
  39         in the exit value).
  40         By default this check is done.
  41
  42 check-known-to-fail (optional)
  43         Mark the test as being known to fail.
  44
  45 check-output-contains: <pattern> (optional)
  46         Check that the output (stdout) contains the given pattern.
  47         Several such tags can be given, in which case the output
  48         must contains all the patterns.
  49
  50 check-output-excludes: <pattern> (optional)
  51         Similar than the above one, but with opposite logic.
  52         Check that the output (stdout) doesn't contain the given pattern.
  53         Several such tags can be given, in which case the output
  54         must contains none of the patterns.
  55
  56 check-output-pattern-<nbr>-times: <pattern> (optional)
  57         Similar to the contains/excludes above, but with full control
  58         of the number of times the pattern should occur in the output.
  59
  60         Using test-suite
  61         ~~~~~~~~~~~~~~~~
  62
  63 The test-suite script is called through the check target of the Makefile. It
  64 will try to check every test case it finds (find validation -name '*.c').
  65
  66 It can be called to check a single test with:
  67 $ cd validation
  68 $ ./test-suite single preprocessor/preprocessor1.c
  69      TEST     Preprocessor #1 (preprocessor/preprocessor1.c)
  70 preprocessor/preprocessor1.c passed !
  71
  72
  73         Writing a test
  74         ~~~~~~~~~~~~~~
  75
  76 test-suite comes with a format command to make a test easier to write:
  77
  78         test-suite format file [name [cmd]]
  79
  80 name:
  81         check-name value. If no name is provided, it defaults to the file name.
  82 cmd:
  83         check-command value. If no cmd is provided, it defaults to
  84         "sparse $file".
  85
  86 The output of the test-suite format command can be redirected into the
  87 test case to create a test-suite formatted file.
  88
  89 $ ./test-suite format bad-assignment.c Assignment >> bad-assignment.c
  90 $ cat !$
  91 cat bad-assignment.c
  92 /*
  93  * check-name: bad assignment
  94  *
  95  * check-command: sparse $file
  96  * check-exit-value: 1
  97  *
  98  * check-output-start
  99 bad-assignment.c:3:6: error: Expected ; at end of statement
 100 bad-assignment.c:3:6: error: got \
 101  * check-output-end
 102  */
 103
 104 You can define the check-command you want to use for the test. $file will be
 105 extended to the file name at run time.
 106
 107 $ ./test-suite format validation/preprocessor2.c "Preprocessor #2" \
 108                 "sparse -E \$file" >> validation/preprocessor2.c
 109 $ cat !$
 110 cat validation/preprocessor2.c
 111 /*
 112  * This one we happen to get right.
 113  *
 114  * It should result in a simple
 115  *
 116  *      a + b
 117  *
 118  * for a proper preprocessor.
 119  */
 120 #define TWO a, b
 121
 122 #define UNARY(x) BINARY(x)
 123 #define BINARY(x, y) x + y
 124
 125 UNARY(TWO)
 126 /*
 127  * check-name: Preprocessor #2
 128  *
 129  * check-command: sparse -E $file
 130  * check-exit-value: 0
 131  *
 132  * check-output-start
 133
 134 a + b
 135  * check-output-end
 136  */