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 <jan@casacondor.com>

1 files changed, 82 insertions, 0 deletions

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)