Docs/tests instructions

CONTRIBUTING.md

@@ -11,6 +11,7 @@
       - [Rule type](#rule-type)
   - [Coding Guidelines](#coding-guidelines)
     - [C++](#c)
+    - [Unit testing](/tests/README.md)
   - [Developer Certificate Of Origin](#developer-certificate-of-origin)
 
 ## Code of Conduct

tests/CMakeLists.txt

@@ -18,6 +18,8 @@ set(FALCO_TESTS_SOURCES test_base.cpp engine/test_token_bucket.cpp falco/test_we
 
 set(FALCO_TESTED_LIBRARIES falco_engine)
 
+SET(FALCO_TESTS_ARGUMENTS "" CACHE STRING "Test arguments to pass to the Falco test suite")
+
 option(FALCO_BUILD_TESTS "Determines whether to build tests." ON)
 
 if(FALCO_BUILD_TESTS)
@@ -47,6 +49,6 @@ if(FALCO_BUILD_TESTS)
   include(CTest)
   include(Catch)
   catch_discover_tests(falco_test)
-
-  add_custom_target(tests COMMAND ${CMAKE_CTEST_COMMAND} DEPENDS falco_test)
+  separate_arguments(FALCO_TESTS_ARGUMENTS)
+  add_custom_target(tests COMMAND ${CMAKE_CTEST_COMMAND} ${FALCO_TESTS_ARGUMENTS} DEPENDS falco_test)
 endif()

tests/README.md

@@ -0,0 +1,57 @@
+# Falco unit tests
+
+This folder contains the unit-tests suite for Falco.
+The framework we use for unit-tests is [Catch2](https://github.com/catchorg/Catch2), while the one we use for mocking is [FakeIt](https://github.com/eranpeer/FakeIt).
+
+
+## How to write tests
+
+When you want to test a new file or test a non tested file, remember four steps:
+
+- The folder structure here is the same as the one in the `userspace` folder, so `userspace/engine` becomes `tests/engine`.
+- We call test files with this format `test_<original-file-name>.cpp`
+- Update the `CMakeLists.txt` file to include your file in `FALCO_TESTS_SOURCES` and change the `FALCO_TESTED_LIBRARIES` accordingly. You might also need to add dependencies, in that case, look at `target_link_libraries` and `target_include_directories`
+- If you are unsure on how to write tests, refer to our existing tests in this folder and to the [Catch2](https://github.com/catchorg/Catch2/tree/master/docs) documentation.
+
+## How to execute tests
+
+The suite can be configured with `cmake` and run with `make`.
+
+
+In the root folder of Falco, after creating the build directory:
+
+```bash
+cd falco
+mkdir build
+cd build
+```
+
+You can prepare the tests with:
+
+```
+cmake ..
+```
+
+Optionally, you can customize the test suite by passing custom arguments like the examples below:
+
+**filter all tests containing the word ctor**
+
+```bash
+cmake -DFALCO_TESTS_ARGUMENTS:STRING="-R ctor" ..
+```
+
+**verbose execution**
+
+```bash
+cmake -DFALCO_TESTS_ARGUMENTS:STRING="-V" ..
+```
+
+
+To see a list of all the custom arguments you may pass, execute `ctest --help` in your terminal.
+
+
+Once you are ready, you can run your configuration with:
+
+```bash
+make tests
+```