Expand Unittest documentation

CMakeLists.txt

@@ -1,6 +1,8 @@
 # Cmake in OpenVPN3 core is mainly used to get Clion editior support and to run unit tests. For normal
 # Build instructions see the README.rst
 
+project(OpenVPN3-core)
+
 cmake_minimum_required(VERSION 3.5)
 
 add_subdirectory(test/unittests)

test/unittests/README.md

@@ -10,10 +10,13 @@ as described in the [README.rst](../../README.rst).
 The unit test cmake files assume here that the deps directory is on the same
 level as the openvpn3 directory unless overridden by the DEP_DIR variable.
 
+The directory for cmake to build a project can be everywhere, but it is recommended to keep
+it outside of the source tree. 
+
 Building unit tests (assuming you are in the openvpn3 directory):
 
-    ➜ mkdir ../unittests
-    ➜ cd ../unittests
+    ➜ mkdir ../unit_test_build
+    ➜ cd ../unit_test_build
     ➜ cmake ../openvpn3
     ➜ cmake --build . --target coreUnitTests
 
@@ -31,15 +34,47 @@ Using mbed TLS instead of OpenSSL
 
     ➜ cmake ../openvpn3 -DUSE_MBEDTLS
 
-A full list of build options can shown with
+A full list of build options can shown together with short descriptions can be shown with
 
-    ➜ cmake -LAH .
+    ➜ cmake -LH .
 
-Example for building and running on Windows:
+Examplary commands for building and running on Windows:
 
     ➜ cmake -DDEP_DIR=C:\o3\deps -DUSE_MBEDTLS=true -DCMAKE_GENERATOR_PLATFORM=x64 C:\o3\openvpn3
     ➜ cmake --build . --target coreUnitTests
     ➜ test\unittests\Debug\coreUnitTests.exe --gtest_output="xml:test_core.xml" --gtest_shuffle
+    
+### Frequently used command line options ###
+
+Show the help for gtest command line options:
+    
+    ➜ ./test/unittests/coreUnitTests --help
+    
+Run only tests starting with Base64 or a sepcific Base64 test:
+
+    ➜ ./test/unittests/coreUnitTests --gtest_filter='Base64.*'
+    ➜ ./test/unittests/coreUnitTests --gtest_filter=Base64.tooshortdest
+    
+Run all test but the Base64 tests
+
+    ➜ ./test/unittests/coreUnitTests --gtest_filter='-Base64.*'
+    
+Multiple pattern can be specified with a list separated by :
+
+    ➜ ./test/unittests/coreUnitTests --gtest_filter='OpenSSL_X509_get_serial.*:Base64.*'
+    
+    
+Shuffle order the order in which the tests are run:
+
+    ➜ ./test/unittests/coreUnitTests --gtest_shuffle
+
+If a certain order yields failures, repeat that order:
+
+    ➜ ./test/unittests/coreUnitTests --gtest_shuffle --gtest_random_seed=23
+    
+Run also the tests that are normally disabled
+
+    ➜ ./test/unittests/coreUnitTests --gtest_also_run_disabled_tests
 
 ## Writing unit tetss ##
 
@@ -55,4 +90,4 @@ requires special compile/includes or other options that are not compatible with
 the unit tests, another  compilation unit should be added to the CMAKELists.txt
 
 The `test_helper.cc` file adds helper functions that can be used for unit tests. See the file
-for more information.
+for more information.