From c8a2f680b9e9521eb930c18d41ffd970db92e5a5 Mon Sep 17 00:00:00 2001 From: jan Iversen Date: Tue, 24 Dec 2019 21:31:23 +0100 Subject: documentation: change filename to follow standard change Readme.testing --> README_TESTING.md and thereby not contain a mixture of upper/lower case letters. Signed-off-by: Jan Iversen --- README_TESTING.md | 82 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ Readme.testing | 82 ------------------------------------------------------- 2 files changed, 82 insertions(+), 82 deletions(-) create mode 100644 README_TESTING.md delete mode 100644 Readme.testing diff --git a/README_TESTING.md b/README_TESTING.md new file mode 100644 index 000000000..a8b96655d --- /dev/null +++ b/README_TESTING.md @@ -0,0 +1,82 @@ +Testing subsurface: + +Right now to test subsurface you need to have the 'cmake' executable +to compile the source code of the tests and run them. + +1 - create a folder 'build-tests' on the project root directory +2 - run cmake ( cmake .. ) +3 - compile the software by invoking make +4 - run the tests by invoking make test +(optional 5) if the tests are failing, a better way to see what's +happening is to run ctest -V , this way the tests will still fail, +but more verbosely - easier to track them down. + +to create a new test, just implement copy the one provided by +example in the tests folder and add the last three lines of the CMakeLists.txt file +adapted to your test. + +If you have multiple versions of Qt installed, you might get a "plugin missing error", you can fix that by doing + +export QT_QPA_PLATFORM_PLUGIN_PATH=~/Qt/5.13.2/clang_64/plugins +(of course substitute 5.13.2 with your preferred version) + +To create a new test you can do one of the following (information +provided by Tomaz on IRC): + +1) Create a new private slot on an already created test class +2) Implement the test there, and compare the expected result with the +correct result with QCOMPARE: + +void testRedCeiling(); +testRedCeiling() +{ + load_dive("../dive/testDive.xml"); + calculated_ceiling(); + QCOMPARE( dive->ceiling->color(), QColor("red")); +} + +3) Run the test case and see result + +$ make test + +If the color is not QColor("red"), when you run the test you will get a +failure. Then you run a command to get a more verbose output and see in +which part the test fails. + +$ ctest -V + +4) Fix the test case + +5) Look at the existing test cases if you run into trouble or need more +ideas. E.g. running following command will show the first test cases +written for unit conversions: + +$ git show 019edd065fd1eefd5f705c42bce23255bb5e20ac + +Also the Qt documentation is good source for more information: + +http://qt-project.org/doc/qt-4.8/qtest.html +http://qt-project.org/doc/qt-5/qtest.html + +6) To create a new test class, copy the last three lines of the CMake, +and duplicate it with the new class / file. + +Each "test" can have N test cases on it (each private slot counts as one +test) and is executable. When one runs make, these test cases are +compiled and when running "make test" they will be executed. Of course, +the test cases can be run manually as well. + +There are three main test macros that we use, but of course many more +are available (check the Qt documentation): + +QCOMPARE(value, expected) +QVERIFY(boolean) +QVERIFY2(boolean, "error message on fail") + +If expecting a test case to fail, use + +QEXPECT_FAIL("", "This test case fails, as it is not yet fully implemented", Continue); + +To link libraries, use the following macro: + +TARGET_LINK_LIBRARIES(TestCaseName ${QT_LIBRARIES} subsurface_corelib) diff --git a/Readme.testing b/Readme.testing deleted file mode 100644 index a8b96655d..000000000 --- a/Readme.testing +++ /dev/null @@ -1,82 +0,0 @@ -Testing subsurface: - -Right now to test subsurface you need to have the 'cmake' executable -to compile the source code of the tests and run them. - -1 - create a folder 'build-tests' on the project root directory -2 - run cmake ( cmake .. ) -3 - compile the software by invoking make -4 - run the tests by invoking make test -(optional 5) if the tests are failing, a better way to see what's -happening is to run ctest -V , this way the tests will still fail, -but more verbosely - easier to track them down. - -to create a new test, just implement copy the one provided by -example in the tests folder and add the last three lines of the CMakeLists.txt file -adapted to your test. - -If you have multiple versions of Qt installed, you might get a "plugin missing error", you can fix that by doing - -export QT_QPA_PLATFORM_PLUGIN_PATH=~/Qt/5.13.2/clang_64/plugins -(of course substitute 5.13.2 with your preferred version) - -To create a new test you can do one of the following (information -provided by Tomaz on IRC): - -1) Create a new private slot on an already created test class -2) Implement the test there, and compare the expected result with the -correct result with QCOMPARE: - -void testRedCeiling(); -testRedCeiling() -{ - load_dive("../dive/testDive.xml"); - calculated_ceiling(); - QCOMPARE( dive->ceiling->color(), QColor("red")); -} - -3) Run the test case and see result - -$ make test - -If the color is not QColor("red"), when you run the test you will get a -failure. Then you run a command to get a more verbose output and see in -which part the test fails. - -$ ctest -V - -4) Fix the test case - -5) Look at the existing test cases if you run into trouble or need more -ideas. E.g. running following command will show the first test cases -written for unit conversions: - -$ git show 019edd065fd1eefd5f705c42bce23255bb5e20ac - -Also the Qt documentation is good source for more information: - -http://qt-project.org/doc/qt-4.8/qtest.html -http://qt-project.org/doc/qt-5/qtest.html - -6) To create a new test class, copy the last three lines of the CMake, -and duplicate it with the new class / file. - -Each "test" can have N test cases on it (each private slot counts as one -test) and is executable. When one runs make, these test cases are -compiled and when running "make test" they will be executed. Of course, -the test cases can be run manually as well. - -There are three main test macros that we use, but of course many more -are available (check the Qt documentation): - -QCOMPARE(value, expected) -QVERIFY(boolean) -QVERIFY2(boolean, "error message on fail") - -If expecting a test case to fail, use - -QEXPECT_FAIL("", "This test case fails, as it is not yet fully implemented", Continue); - -To link libraries, use the following macro: - -TARGET_LINK_LIBRARIES(TestCaseName ${QT_LIBRARIES} subsurface_corelib) -- cgit v1.2.3-70-g09d2