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-output-start / check-output-end (optional)
  29         The expected output (stdout and stderr) of check-command lies between
  30         those two tags. It defaults to no output.
  31
  32 check-known-to-fail (optional)
  33         Mark the test as being known to fail.
  34
  35
  36         Using test-suite
  37         ~~~~~~~~~~~~~~~~
  38
  39 The test-suite script is called through the check target of the Makefile. It
  40 will try to check every test case it finds (find validation -name '*.c').
  41
  42 It can be called to check a single test with:
  43 $ cd validation
  44 $ ./test-suite single preprocessor/preprocessor1.c
  45      TEST     Preprocessor #1 (preprocessor/preprocessor1.c)
  46 preprocessor/preprocessor1.c passed !
  47
  48
  49         Writing a test
  50         ~~~~~~~~~~~~~~
  51
  52 test-suite comes with a format command to make a test easier to write:
  53
  54         test-suite format file [name [cmd]]
  55
  56 name:
  57         check-name value. If no name is provided, it defaults to the file name.
  58 cmd:
  59         check-command value. If no cmd is provided, it defaults to
  60         "sparse $file".
  61
  62 The output of the test-suite format command can be redirected into the
  63 test case to create a test-suite formated file.
  64
  65 $ ./test-suite format bad-assignment.c Assignment >> bad-assignment.c
  66 $ cat !$
  67 cat bad-assignment.c
  68 /*
  69  * check-name: bad assignment
  70  *
  71  * check-command: sparse $file
  72  * check-exit-value: 1
  73  *
  74  * check-output-start
  75 bad-assignment.c:3:6: error: Expected ; at end of statement
  76 bad-assignment.c:3:6: error: got \
  77  * check-output-end
  78  */
  79
  80 You can define the check-command you want to use for the test. $file will be
  81 extended to the file name at run time.
  82
  83 $ ./test-suite format validation/preprocessor2.c "Preprocessor #2" \
  84                 "sparse -E \$file" >> validation/preprocessor2.c
  85 $ cat !$
  86 cat validation/preprocessor2.c
  87 /*
  88  * This one we happen to get right.
  89  *
  90  * It should result in a simple
  91  *
  92  *      a + b
  93  *
  94  * for a proper preprocessor.
  95  */
  96 #define TWO a, b
  97
  98 #define UNARY(x) BINARY(x)
  99 #define BINARY(x, y) x + y
 100
 101 UNARY(TWO)
 102 /*
 103  * check-name: Preprocessor #2
 104  *
 105  * check-command: sparse -E $file
 106  * check-exit-value: 0
 107  *
 108  * check-output-start
 109
 110 a + b
 111  * check-output-end
 112  */