Dev/add simulator tests in GitHub workflows (#1337)

* added simulator tests in github workflows * indentation error * typo * debug * Logging for debugging * added more debug lines * more debugging * debug * debug * debug * dont throw if process does not exist * debug * added absolute path to sls_detector commands * some refactoring in test scripts * added absolute path to all slsdet command * typo * ../tests/scripts/test_frame_synchronizer.py * raise exception upon failure for github workflows * removed hidden tags * some refactoring in test scripts * some refactoring * fixed CMakeLists * fixed unsuccesful merge * updated python tests using simulators * debug import error * debug module import * python -m runs module pytest as script - everything in path available * removed integartion tests * enable file write not to log files * run tests without log files * increased sleep time for udp packets * added logg level variable to cmake * added testing policies to documenattion * disabled check for num_frames for jungfrau & xilinx * set log level as cmake cached variable * disable tests for jungfrau and xilinx_ctb * check frames for HDF5 * updated Documentation of Testing * changed withdetectorsimulators to detectorintegration * replaced [.cmdcall] with [.detectorintegration] * check_file_size only disabled for jungfrau - disable for all roi tests * changed time to wait after receive to 5 ms * take into account half modules of eiger * num udp interfaces needs to be consistent across modules * suppressed warning enclosing if * config added 2 udp ports per default for moench and jungfrau * write detector output to console * allow jungfrau to tests num frames, remove unused variable (numinterfaces), add comment for future to handle traceback to know which calling function threw the files unmatched, added documentation for tests (examples for .detectoritnegration and how to disable marked tests, removed addditional argumetns to disable for test_simulator as one can just use ~, removed the check that checks for jungfrau checking number of frames at master attributes and at rx test, removed unused advanced_test_settings in test_simulator script, the num_mods check for multiple modules is removed and default num modules set to 1 for test_simulator (to be increased later), back to raising exception for killprocess * removed integration tests from cmakelists.txt and cmk.sh, modified the tests workflow command to reflect the disable argument and removed xilinx_ctb from test (fix fromdeveloper merge to be done) * filtering by actual name for disable certain tests on github workflow * minor refactor * wip * wip * changes to run on local rh9 runner instead of github workfloa * modified yml to remove some leftover from github workflow * test * fix build_dir in scripts (github workflow) and pytest dir in gitea workflow * making the local machine use python3.13 binary * pythonpath added * changes for build_Dir back * allowing ctb api tests * allowed ctb api tests and set up slsdetname envt variable for shared memory being reserved just for these tests * added rh8 workflow for local runner on gitea * remnants from rh9 local runner * remnants from rh9 local runner * conda env for all shell for local runner * allowing hdf5 to build on local runner * run all tests for both the runners * refactored fixtures a bit and merged some tests that use one session for entire server * test fail * test fix * adding github workflow to test without data file checks and without logs * documentation changes * unnecessary import in conftest * allowing the session_simulator to test for multiple modules and interfaces etc * allow test_simulator script to run for 2 modules for all modules except ctb and xilinx ctb * run upon push * removing the disable file check on github workflow * minor adjustment * testing without synch * reverting to previous * with log file * without the space * summary from file and more error extracts from file to terminal * minor * trying nlf for more details * updated with no log file to print everything to screen also for det and rxr * trying a no throw * stoi was more about indent in yaml * tries * wip * debug * number of frames inconsistent fix=>just take first one, only test xilinx * jungfrau tests without frames caught check * extend the disable file check to everywhere that creates files * specify path for test_simulator * withoutprinting == * wip * back with printing===, but not parsing file for errors anymore * lang? * wip * safe log? * wip2 * wip * dont split error as its streaming live, just raise * with log files * lang? * last resort * wip * test no det with general tests * show tests live * also include hidden integration tests * without extra summary? * revert * last resort again * tsquash on int64_t? * tsquash on int64_t? mroe print * writing to /tmp? * all tests * might be the fix? * write to file * fixed a few quiet mode no log file tests * work on any branch for github tests, work on also release candidates for gitea tests * added frame synchronizer tests to github workflow * moved tests to run_tests.yaml from cmake.yaml * documentation * disabled general tests --------- Co-authored-by: Dhanya Thattil <dhanya.thattil@psi.ch>
2026-02-07 08:48:41 +01:00 · 2026-02-03 11:45:12 +01:00
parent a390e580d2
commit 28b2aa9673
42 changed files with 1243 additions and 1758 deletions
--- a/docs/src/Testing.rst
+++ b/docs/src/Testing.rst
@@ -0,0 +1,166 @@
+Testing
+==========
+
+We use ``catch2`` and ``pytest`` for unit testing the C++ and Python code. 
+
+CATCH2 Tests
+----------------
+
+To build and run the catch2 tests use the following commands: 
+
+.. code-block:: console
+
+    cd build
+    cmake -DSLS_USE_TESTS=ON ../
+    bin/tests 
+
+Note that this requires that you have catch2 installed on your system.
+
+Naming Policy: 
+-----------------
+
+Per default all tests should be visible to catch2. 
+
+If a test fails in the github or gitea actions hide the test by adding the tag ``[.]`` to the test name.
+
+.. code-block:: cpp
+
+    TEST_CASE("This test is hidden from default runs", "[.]") {
+        REQUIRE(1 == 2);
+    }
+
+You can run all tests requiring a detector by running the following command: 
+
+.. code-block:: console
+
+    tests "[.detectorintegration]"
+
+
+.. note ::   
+
+    This only works if a configured simulator (or an actual configured detector) and receiver are already set up to run the tests. There is a script that automatically sets up virtual detectors and runs all integration tests. See Section :ref:`Simulator Script. <python simulator script>`  below.
+
+
+If you want to disable testing that involves a data file that require pc tuning optimizations, add the hidden tag ``[.disable_check_data_file]`` to the test case. Please note that only some specific disable tests have been implemented so far.
+
+.. code-block:: console
+
+    tests "[detectorintegration]~[disable_check_data_file]"
+
+.. note ::   
+
+    Ensure that there are no spaces betweent the tags and no '.', else hardly any test will be matched.
+
+.. _python simulator script:
+
+Simulator Script: 
+-----------------
+
+One can also just run the following script, which will run your tests for all the detector types (simulators only) with a pre-determined configuration.
+
+.. code-block:: console
+
+    cd build 
+    python bin/test_simulators.py 
+
+This runs all tests marked with the tag ``[.detectorintegration]`` for all detector simulators.
+If you want to run them for a specific virtual detector or a specific test use the following command:
+
+.. code-block:: console
+    cd build
+    python bin/test_simulators.py --servers jungfrau --test "[.rx]"
+
+You can exclude specific tests by adding the option ``~[<disable_test_name>]``. Again, we assume that this marker is added to the tests that you want to exclude. 
+
+.. code-block:: console
+    cd build
+    python bin/test_simulators.py --servers eiger jungfrau moench --test "[detectorintegration]~[disable_check_data_file]"
+
+You can additionally run all the tests not requiring detectors using the script ``bin/test_simulators.py`` by passing the option ``--general-tests``. 
+
+One can use ``--no-log-file`` if you dont want to create a log files and instead print to console. If you prefer to not print to console either, add ``--quiet``.
+
+
+Pytest Tests
+-----------------
+
+To run the python tests use the following commands:
+
+.. code-block:: console
+
+    cd build
+    cmake ../ -DSLS_USE_PYTHON=ON
+    export PYTHONPATH=$PWD/bin 
+    python -m pytest ../python/tests/ 
+
+If a test requires a detector mark them with the pytest marker ``@pytest.mark.detectorintegration``.
+
+To run only tests requiring virtual detectors use the following command:
+
+.. code-block:: console
+    #in build
+    python -m pytest -m detectorintegration ../python/tests/
+
+There is a helper test fixture in ``slsDetectorSoftware/python/tests/conftest.py`` called ``test_with_simulators`` that sets up virtual detectors and yields the test for all detectors. The set up is done for every test automatically.
+
+Example usage: 
+
+.. code-block:: python
+
+    import pytest
+
+    @pytest.mark.detectorintegration
+    def test_example_with_simulator(test_with_simulators):
+        # your test code here
+
+If you want to run the test only for a specific test use the parametrized test fixture: 
+
+Example usage: 
+
+.. code-block:: python
+
+    import pytest
+
+    @pytest.mark.detectorintegration
+    @pytest.mark.parametrize("setup_parameters", [(["<my_detector>"], <num_modules>)], indirect=True)
+    def test_example_with_specific_simulators(test_with_simulators, setup_parameters):
+        # your test code here
+
+
+There is another helper test fixture in ``slsDetectorSoftware/python/tests/conftest.py`` called ``session_simulator`` that sets up virtual detectors and yields the test for all detectors. The difference with the previous fixture ``test_with_simulators`` is that this fixture will set up one detector at a time and run all the tests using this fixture before cleaning up and moving on to the next detector. It saves time if the setup and cleanup is expensive.
+
+Example usage: 
+
+.. code-block:: python
+
+    import pytest
+
+    @pytest.mark.detectorintegration
+    def test_define_reg(session_simulator, request):
+        """ Test setting define_reg for ctb and xilinx_ctb."""
+        det_type, num_interfaces, num_mods, d = session_simulator
+        assert d is not None
+
+        from slsdet import RegisterAddress
+
+        if det_type in ['ctb', 'xilinx_ctb']:
+        # your test code here
+
+For more specific parameters, you can parametrize the fixture like below:
+
+.. code-block:: python
+
+    import pytest
+
+    @pytest.mark.detectorintegration
+    @pytest.mark.parametrize(
+        "session_simulator",
+        [
+            ("ctb", 1, 1),
+            ("xilinx_ctb", 1, 1),
+        ],
+        indirect=True,
+    )
+    def test_define_reg(session_simulator):
+        det_type, num_interfaces, num_mods, d = session_simulator
+        # your test code here
--- a/docs/src/index.rst
+++ b/docs/src/index.rst
@@ -66,6 +66,7 @@ slsDetectorPackage
    container_utils
    type_traits
    ToString
+    Testing

 .. toctree::
    :caption: Firmware