sval: update check_snprintf.c
[smatch.git] / Documentation / test-suite
blob6c4f24f65b70cfe43925aa5589f71ba79433005d
3         Sparse test suite
4         ~~~~~~~~~~~~~~~~~
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.
10 check-name: (mandatory)
11         Name of the test.
13 check-description: (optional)
14         A description of what the test checks.
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".
25 check-exit-value: (optional)
26         The expected exit value of check-command. It defaults to 0.
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.
32 check-known-to-fail (optional)
33         Mark the test as being known to fail.
36         Using test-suite
37         ~~~~~~~~~~~~~~~~
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').
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 !
49         Writing a test
50         ~~~~~~~~~~~~~~
52 test-suite comes with a format command to make a test easier to write:
54         test-suite format file [name [cmd]]
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".
62 The output of the test-suite format command can be redirected into the
63 test case to create a test-suite formated file.
65 $ ./test-suite format bad-assignment.c Assignment >> bad-assignment.c
66 $ cat !$
67 cat bad-assignment.c
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  */
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.
83 $ ./test-suite format validation/preprocessor2.c "Preprocessor #2" \
84                 "sparse -E \$file" >> validation/preprocessor2.c
85 $ cat !$
86 cat validation/preprocessor2.c
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
98 #define UNARY(x) BINARY(x)
99 #define BINARY(x, y) x + y
101 UNARY(TWO)
103  * check-name: Preprocessor #2
105  * check-command: sparse -E $file
106  * check-exit-value: 0
108  * check-output-start
110 a + b
111  * check-output-end
112  */