Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
a31e13fa80ffe782439b8a8e5f9102974fe4e07b
[simgrid.git] / doc / doxygen / inside_tests.doc
1 /*! 
2 @page inside_tests Testing SimGrid
3
4 This page will teach you how to run the tests, selecting the ones you
5 want, and how to add new tests to the archive.
6
7 \tableofcontents
8
9 SimGrid code coverage is usually between 70% and 80%, which is much
10 more than most projects out there. This is because we consider SimGrid
11 to be a rather complex project, and we want to modify it with less fear.
12
13 We have two sets of tests in SimGrid: Each of the 10,000+ unit tests
14 check one specific case for one specific function, while the 500+
15 integration tests run a given simulation specifically intended to
16 exercise a larger amount of functions together. Every example provided
17 in examples/ is used as an integration test, while some other torture
18 tests and corner cases integration tests are located in teshsuite/.
19 For each integration test, we ensure that the output exactly matches
20 the defined expectations. Since SimGrid displays the timestamp of
21 every logged line, this ensures that every change of the models'
22 prediction will be noticed. All these tests should ensure that SimGrid
23 is safe to use and to depend on.
24
25 \section inside_tests_runintegration Running the tests
26
27 Running the tests is done using the ctest binary that comes with
28 cmake. These tests are run for every commit and the result is publicly
29 <a href="https://ci.inria.fr/simgrid/">available</a>.
30
31 \verbatim
32 ctest                     # Launch all tests
33 ctest -R msg              # Launch only the tests which name match the string "msg"
34 ctest -j4                 # Launch all tests in parallel, at most 4 at the same time
35 ctest --verbose           # Display all details on what's going on
36 ctest --output-on-failure # Only get verbose for the tests that fail
37
38 ctest -R msg- -j5 --output-on-failure # You changed MSG and want to check that you didn't break anything, huh?
39                                       # That's fine, I do so all the time myself.
40 \endverbatim
41
42 \section inside_tests_rununit Running the unit tests
43
44 All unit tests are packed into the testall binary, that lives at the
45 source root. These tests are run when you launch ctest, don't worry.
46
47 \verbatim
48 make testall                    # Rebuild the test runner on need
49 ./testall                       # Launch all tests
50 ./testall --help                # revise how it goes if you forgot
51 ./testall --tests=-all          # run no test at all (yeah, that's useless)
52 ./testall --dump-only           # Display all existing test suites
53 ./testall --tests=-all,+dict    # Only launch the tests from the dict test suite
54 ./testall --tests=-all,+foo:bar # run only the bar test from the foo suite.
55 \endverbatim
56
57
58 \section inside_tests_add_units Adding unit tests
59
60 \warning this section is outdated. New unit tests should be written
61 using the unit_test_framework component of Boost. There is no such
62 example so far in our codebase, but that's definitely the way to go
63 for the future. STOP USING XBT.
64
65 If you want to test a specific function or set of functions, you need
66 a unit test. Edit the file tools/cmake/UnitTesting.cmake to
67 add your source file to the FILES_CONTAINING_UNITTESTS list. For
68 example, if you want to create unit tests in the file src/xbt/plouf.c,
69 your changes should look like that:
70
71 \verbatim
72 --- a/tools/cmake/UnitTesting.cmake
73 +++ b/tools/cmake/UnitTesting.cmake
74 @@ -11,6 +11,7 @@ set(FILES_CONTAINING_UNITTESTS
75    src/xbt/xbt_sha.c
76    src/xbt/config.c
77 +  src/xbt/plouf.c
78    )
79
80  if(SIMGRID_HAVE_MC)
81 \endverbatim
82
83 Then, you want to actually add your tests in the source file. All the
84 tests must be protected by "#ifdef SIMGRID_TEST" so that they don't
85 get included in the regular build. The line SIMGRID_TEST must also be
86 written on the endif line for the extraction script to work properly. 
87
88 Tests are subdivided in three levels. The top-level, called <b>test
89 suite</b>, is created with the macro #XBT_TEST_SUITE. There can be
90 only one suite per source file. A suite contains <b>test units</b>
91 that you create with the #XBT_TEST_UNIT macro.  Finally, you start
92 <b>actual tests</b> with #xbt_test_add. There is no closing marker of
93 any sort, and an unit is closed when the next unit starts, or when the
94 end of file is reached. 
95
96 Once a given test is started with #xbt_test_add, you use
97 #xbt_test_assert to specify that it was actually an assert, or
98 #xbt_test_fail to specify that it failed (if your test cannot easily
99 be written as an assert). #xbt_test_exception can be used to report
100 that it failed with an exception. There is nothing to do to report
101 that a given test succeeded, just start the next test without
102 reporting any issue. Finally, #xbt_test_log can be used to report
103 intermediate steps. The messages will be shown only if the
104 corresponding test fails.
105
106 Here is a recaping example, inspired from src/xbt/dynar.h (see that
107 file for details).
108 @code
109 /* The rest of your module implementation */
110
111 #ifdef SIMGRID_TEST
112
113 XBT_TEST_SUITE("dynar", "Dynar data container");
114 XBT_LOG_EXTERNAL_DEFAULT_CATEGORY(xbt_dyn); // Just the regular logging stuff
115
116 XBT_TEST_UNIT("int", test_dynar_int, "Dynars of integers")
117 {
118   int i, cpt;
119   unsigned int cursor;
120
121   xbt_test_add("==== Traverse the empty dynar");
122   xbt_dynar_t d = xbt_dynar_new(sizeof(int), NULL);
123   xbt_dynar_foreach(d, cursor, i) {
124     xbt_test_fail( "Damnit, there is something in the empty dynar");
125   }
126   xbt_dynar_free(&d);
127
128   xbt_test_add("==== Push %d int and re-read them",  NB_ELEM);
129   d = xbt_dynar_new(sizeof(int), NULL);
130   for (cpt = 0; cpt < NB_ELEM; cpt++) {
131     xbt_test_log("Push %d, length=%lu", cpt, xbt_dynar_length(d));
132     xbt_dynar_push_as(d, int, cpt);
133   }
134
135   for (cursor = 0; cursor < NB_ELEM; cursor++) {
136     int *iptr = xbt_dynar_get_ptr(d, cursor);
137     xbt_test_assert(cursor == *iptr,
138        "The retrieved value is not the same than the injected one (%u!=%d)",cursor, cpt);
139   }
140   
141   xbt_test_add("==== Check the size of that %d-long dynar",  NB_ELEM);
142   xbt_test_assert(xbt_dynar_size(d) == NB_ELEM);
143   xbt_dynar_free(&d); 
144 }
145
146 XBT_TEST_UNIT("insert",test_dynar_insert,"Using the xbt_dynar_insert and xbt_dynar_remove functions")
147 {
148   xbt_dynar_t d = xbt_dynar_new(sizeof(unsigned int), NULL);
149   unsigned int cursor;
150   int cpt;
151
152   xbt_test_add("==== Insert %d int, traverse them, remove them",NB_ELEM);
153   // BLA BLA BLA
154 }
155
156 #endif  /* SIMGRID_TEST <-- that string must appear on the endif line */
157 @endcode
158
159 For more details on the macro used to write unit tests, see their
160 reference guide: @ref XBT_cunit.  For details on on how the tests are
161 extracted from the module source, check the tools/sg_unit_extractor.pl
162 script directly.
163
164 Last note: please try to keep your tests fast. We run them very very
165 very often, and you should strive to make it as fast as possible, to
166 not upset the other developers. Do not hesitate to stress test your
167 code with such unit tests, but make sure that it runs reasonably fast,
168 or nobody will run "ctest" before commiting code.
169
170 \section inside_tests_add_integration Adding integration tests
171
172 TESH (the TEsting SHell) is the test runner that we wrote for our
173 integration tests. It is distributed with the SimGrid source file, and
174 even comes with a man page. TESH ensures that the output produced by a
175 command perfectly matches the expected output. This is very precious
176 to ensure that no change modifies the timings computed by the models
177 without notice. 
178
179 To add a new integration test, you thus have 3 things to do:
180
181  - <b>Write the code exercising the feature you target</b>. You should
182    strive to make this code clear, well documented and informative for
183    the users. If you manage to do so, put this somewhere under
184    examples/ and modify the cmake files as explained on this page:
185    \ref inside_cmake_examples. If you feel like you should write a
186    torture test that is not interesting to the users (because nobody
187    would sanely write something similar in user code), then put it under 
188    teshsuite/ somewhere.
189    
190  - <b>Write the tesh file</b>, containing the command to run, the
191    provided input (if any, but almost no SimGrid test provide such an
192    input) and the expected output. Check the tesh man page for more
193    details.\n
194    Tesh is sometimes annoying as you have to ensure that the expected
195    output will always be exactly the same. In particular, your should
196    not output machine dependent informations such as absolute data
197    path, nor memory adresses as they would change on each run. Several
198    steps can be used here, such as the obfucation of the memory
199    adresses unless the verbose logs are displayed (using the
200    #XBT_LOG_ISENABLED() macro), or the modification of the log formats
201    to hide the timings when they depend on the host machine.\n
202    The script located in <project/directory>/tools/tesh/generate_tesh can
203    help you a lot in particular if the output is large (though a smaller output is preferable). 
204    There are also example tesh files in the <project/directory>/tools/tesh/ directory, that can be useful to understand the tesh syntax.
205    
206  - <b>Add your test in the cmake infrastructure</b>. For that, modify
207    the following file:
208    @verbatim
209    <project/directory>/teshsuite/<interface eg msg>/CMakeLists.txt
210    @endverbatim   
211    Make sure to pick a wise name for your test. It is often useful to
212    check a category of tests together. The only way to do so in ctest
213    is to use the -R argument that specifies a regular expression that
214    the test names must match. For example, you can run all MSG test
215    with "ctest -R msg". That explains the importance of the test
216    names.
217
218 Once the name is chosen, create a new test by adding a line similar to
219 the following (assuming that you use tesh as expected).
220
221 \verbatim
222 # Usage: ADD_TEST(test-name ${CMAKE_BINARY_DIR}/bin/tesh <options> <tesh-file>)
223 #  option --setenv bindir set the directory containing the binary
224 #         --setenv srcdir set the directory containing the source file
225 #         --cd set the working directory
226 ADD_TEST(my-test-name ${CMAKE_BINARY_DIR}/bin/tesh 
227          --setenv bindir=${CMAKE_BINARY_DIR}/examples/my-test/
228          --setenv srcdir=${CMAKE_HOME_DIRECTORY}/examples/my-test/
229          --cd ${CMAKE_HOME_DIRECTORY}/examples/my-test/
230          ${CMAKE_HOME_DIRECTORY}/examples/msg/io/io.tesh
231 )
232 \endverbatim             
233
234 As usual, you must run "make distcheck" after modifying the cmake files,
235 to ensure that you did not forget any files in the distributed archive.
236
237 \section inside_tests_ci Continous Integration
238
239 We use several systems to automatically test SimGrid with a large set
240 of parameters, across as many platforms as possible. 
241 We use <a href="https://ci.inria.fr/simgrid/">Jenkins on Inria
242 servers</a> as a workhorse: it runs all of our tests for many
243 configurations. It takes a long time to answer, and it often reports
244 issues but when it's green, then you know that SimGrid is very fit!
245 We use <a href="https://travis-ci.org/simgrid/simgrid">Travis</a> to
246 quickly run some tests on Linux and Mac. It answers quickly but may
247 miss issues. And we use <a href="https://ci.appveyor.com/project/mquinson/simgrid">AppVeyor</a>
248 to build and somehow test SimGrid on windows. 
249
250 \subsection inside_tests_jenkins Jenkins on the Inria CI servers
251
252 You should not have to change the configuration of the Jenkins tool
253 yourself, although you could have to change the slaves' configuration
254 using the <a href="https://ci.inria.fr">CI interface of INRIA</a> --
255 refer to the <a href="https://wiki.inria.fr/ciportal/">CI documentation</a>.
256
257 The result can be seen here: https://ci.inria.fr/simgrid/
258
259 We have 2 interesting projects on Jenkins:
260 \li <a href="https://ci.inria.fr/simgrid/job/SimGrid-Multi/">SimGrid-Multi</a>
261     is the main project, running the tests that we spoke about.\n It is
262     configured (on Jenkins) to run the script <tt>tools/jenkins/build.sh</tt>
263 \li <a href="https://ci.inria.fr/simgrid/job/SimGrid-DynamicAnalysis/">SimGrid-DynamicAnalysis</a>
264     runs the tests both under valgrind to find the memory errors and
265     under gcovr to report the achieved test coverage.\n It is configured
266     (on Jenkins) to run the script <tt>tools/jenkins/DynamicAnalysis.sh</tt>
267
268 In each case, SimGrid gets built in
269 /builds/workspace/$PROJECT/build_mode/$CONFIG/label/$SERVER/build 
270 with $PROJECT being for instance "SimGrid-Multi", $CONFIG "DEBUG" or
271 "ModelChecker" and $SERVER for instance "simgrid-fedora20-64-clang".
272
273 If some configurations are known to fail on some systems (such as
274 model-checking on non-linux systems), go to your Project and click on
275 "Configuration". There, find the field "combination filter" (if your
276 interface language is English) and tick the checkbox; then add a
277 groovy-expression to disable a specific configuration. For example, in
278 order to disable the "ModelChecker" build on host
279 "small-netbsd-64-clang", use:
280
281 \verbatim
282 (label=="small-netbsd-64-clang").implies(build_mode!="ModelChecker")
283 \endverbatim
284
285 \subsection inside_tests_travis Travis
286
287 Travis is a free (as in free beer) Continuous Integration system that
288 open-sourced project can use freely. It is very well integrated in the
289 GitHub ecosystem. There is a plenty of documentation out there. Our
290 configuration is in the file .travis.yml as it should be, and the
291 result is here: https://travis-ci.org/simgrid/simgrid
292
293 The .travis.yml configuration file can be useful if you fail to get
294 SimGrid to compile on modern mac systems. We use the \c brew package
295 manager there, and it works like a charm.
296
297 \subsection inside_tests_appveyor AppVeyor
298
299 AppVeyor aims at becoming the Travis of Windows. It is maybe less
300 mature than Travis, or maybe it is just that I'm less trained in
301 Windows. Our configuration is in the file appveyor.yml as it should
302 be, and the result is here: https://ci.appveyor.com/project/simgrid/simgrid
303
304 We use \c Choco as a package manager on AppVeyor, and it is sufficient
305 for us. In the future, we will probably move to the ubuntu subsystem
306 of Windows 10: SimGrid performs very well under these settings, but
307 unfortunately we have no continuous integration service providing it
308 yet, so we cannot drop AppVeyor yet.
309
310 \subsection inside_tests_debian Debian builders
311
312 Since SimGrid is packaged in Debian, we benefit from their huge
313 testing infrastructure. That's an interesting torture test for our
314 code base. The downside is that it's only for the released versions of
315 SimGrid. That is why the Debian build does not stop when the tests
316 fail: post-releases fixes do not fit well in our workflow and we fix
317 only the most important breakages.
318
319 The build results are here:
320 https://buildd.debian.org/status/package.php?p=simgrid
321
322 \subsection inside_tests_sonarqube SonarQube
323
324 SonarQube is an open-source code quality analysis solution. Their nice
325 code scanners are provided as plugin. The one for C++ is not free, but
326 open-source project can use it at no cost. That is what we are doing.
327
328 Don't miss the great looking dashboard here: 
329 https://nemo.sonarqube.org/overview?id=simgrid
330
331 This tool is enriched by the script @c tools/internal/travis-sonarqube.sh 
332 that is run from @c .travis.yml
333
334 */