X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/1ff90bc7103df77877d6860f1f117425afe1a516..72ce071e25e2cc2626355a11d3e1088853343bfe:/doc/doxygen/inside_tests.doc diff --git a/doc/doxygen/inside_tests.doc b/doc/doxygen/inside_tests.doc index 3c54491b9e..10a394a924 100644 --- a/doc/doxygen/inside_tests.doc +++ b/doc/doxygen/inside_tests.doc @@ -41,131 +41,27 @@ ctest -R msg- -j5 --output-on-failure # You changed MSG and want to check that y @section inside_tests_rununit Running the unit tests -All unit tests are packed into the testall binary, that lives at the +All unit tests are packed into the unit-tests binary, that lives at the source root. These tests are run when you launch ctest, don't worry. @verbatim -make testall # Rebuild the test runner on need -./testall # Launch all tests -./testall --help # revise how it goes if you forgot -./testall --tests=-all # run no test at all (yeah, that's useless) -./testall --dump-only # Display all existing test suites -./testall --tests=-all,+dict # Only launch the tests from the dict test suite -./testall --tests=-all,+foo:bar # run only the bar test from the foo suite. +make unit-tests # Rebuild the test runner on need +./unit-tests # Launch all tests +./unit-tests --help # revise how it goes if you forgot @endverbatim @section inside_tests_add_units Adding unit tests -@warning this section is outdated. New unit tests should be written -using the unit_test_framework component of Boost. There is no such -example so far in our codebase, but that's definitely the way to go -for the future. STOP USING XBT. +Our unit tests are written using the Catch2 library, that is included +in the source tree. Please check for examples, listed at the end of +tools/cmake/Tests.cmake. -If you want to test a specific function or set of functions, you need -a unit test. Edit the file tools/cmake/UnitTesting.cmake to -add your source file to the FILES_CONTAINING_UNITTESTS list. For -example, if you want to create unit tests in the file src/xbt/plouf.c, -your changes should look like that: - -@verbatim ---- a/tools/cmake/UnitTesting.cmake -+++ b/tools/cmake/UnitTesting.cmake -@@ -11,6 +11,7 @@ set(FILES_CONTAINING_UNITTESTS - src/xbt/xbt_sha.c - src/xbt/config.c -+ src/xbt/plouf.c - ) - - if(SIMGRID_HAVE_MC) -@endverbatim - -Then, you want to actually add your tests in the source file. All the -tests must be protected by "#ifdef SIMGRID_TEST" so that they don't -get included in the regular build. The line SIMGRID_TEST must also be -written on the endif line for the extraction script to work properly. - -Tests are subdivided in three levels. The top-level, called test -suite, is created with the macro #XBT_TEST_SUITE. There can be -only one suite per source file. A suite contains test units -that you create with the #XBT_TEST_UNIT macro. Finally, you start -actual tests with #xbt_test_add. There is no closing marker of -any sort, and an unit is closed when the next unit starts, or when the -end of file is reached. - -Once a given test is started with #xbt_test_add, you use -#xbt_test_assert to specify that it was actually an assert, or -#xbt_test_fail to specify that it failed (if your test cannot easily -be written as an assert). #xbt_test_exception can be used to report -that it failed with an exception. There is nothing to do to report -that a given test succeeded, just start the next test without -reporting any issue. Finally, #xbt_test_log can be used to report -intermediate steps. The messages will be shown only if the -corresponding test fails. - -Here is a recaping example, inspired from src/xbt/dynar.h (see that -file for details). -@code -/* The rest of your module implementation */ - -#ifdef SIMGRID_TEST - -XBT_TEST_SUITE("dynar", "Dynar data container"); -XBT_LOG_EXTERNAL_DEFAULT_CATEGORY(xbt_dyn); // Just the regular logging stuff - -XBT_TEST_UNIT("int", test_dynar_int, "Dynars of integers") -{ - int i, cpt; - unsigned int cursor; - - xbt_test_add("==== Traverse the empty dynar"); - xbt_dynar_t d = xbt_dynar_new(sizeof(int), NULL); - xbt_dynar_foreach(d, cursor, i) { - xbt_test_fail( "Damnit, there is something in the empty dynar"); - } - xbt_dynar_free(&d); - - xbt_test_add("==== Push %d int and re-read them", NB_ELEM); - d = xbt_dynar_new(sizeof(int), NULL); - for (cpt = 0; cpt < NB_ELEM; cpt++) { - xbt_test_log("Push %d, length=%lu", cpt, xbt_dynar_length(d)); - xbt_dynar_push_as(d, int, cpt); - } - - for (cursor = 0; cursor < NB_ELEM; cursor++) { - int *iptr = xbt_dynar_get_ptr(d, cursor); - xbt_test_assert(cursor == *iptr, - "The retrieved value is not the same than the injected one (%u!=%d)",cursor, cpt); - } - - xbt_test_add("==== Check the size of that %d-long dynar", NB_ELEM); - xbt_test_assert(xbt_dynar_size(d) == NB_ELEM); - xbt_dynar_free(&d); -} - -XBT_TEST_UNIT("insert",test_dynar_insert,"Using the xbt_dynar_insert and xbt_dynar_remove functions") -{ - xbt_dynar_t d = xbt_dynar_new(sizeof(unsigned int), NULL); - unsigned int cursor; - int cpt; - - xbt_test_add("==== Insert %d int, traverse them, remove them",NB_ELEM); - // BLA BLA BLA -} - -#endif /* SIMGRID_TEST <-- that string must appear on the endif line */ -@endcode - -For more details on the macro used to write unit tests, see their -reference guide: @ref XBT_cunit. For details on on how the tests are -extracted from the module source, check the tools/sg_unit_extractor.pl -script directly. - -Last note: please try to keep your tests fast. We run them very very -very often, and you should strive to make it as fast as possible, to -not upset the other developers. Do not hesitate to stress test your -code with such unit tests, but make sure that it runs reasonably fast, -or nobody will run "ctest" before commiting code. +It is important to keep your tests fast. We run them very very often, +and you should strive to make them as fast as possible, to not bother +the other developers. Do not hesitate to stress test your code, but +make sure that it runs reasonably fast, or nobody will run "ctest" +before commiting code. @section inside_tests_add_integration Adding integration tests @@ -354,7 +250,7 @@ code scanners are provided as plugin. The one for C++ is not free, but open-source project can use it at no cost. That is what we are doing. Don't miss the great looking dashboard here: -https://sonarcloud.io/dashboard?id=simgrid +https://sonarcloud.io/dashboard?id=simgrid_simgrid This tool is enriched by the script @c tools/internal/travis-sonarqube.sh that is run from @c .travis.yml