1. Preamble
- Repository with Actor Testing Framework: https://gitlab.eufus.psnc.pl/ach/actor_testing_framework
- Usage example: https://gitlab.eufus.psnc.pl/ach/nemo/-/tree/test_actor/pass
2. Framework directory structure
2.1. Your repository:
Assuming your repository looks something like this:
Project_root ├── root_files.extension ├── root_directiories/ │ ├── directories/ │ ├── ... │ └── files.extension └── tests # <- this is directory where the whole actor testing framework should be placed
Then the actor testing framework has to be in a directory called tests/ and this is mandatory.
2.2. Actor Testing Framework repository - inside your project:
The inside of the tests/ directory, inside your repository, should contain the entire actor testing framework repository like structure below:
tests
├── __init__.py
├── ci_scripts
│ ├── .gitlab-ci.yml
│ └── .iter-ci.sh
├── configs
│ ├── actor_configuration.yml
│ └── ids_configuration.yml
├── input_pulse_file
│ ├── ITER
│ │ └── 3
│ │ └── 0
│ │ └── {pulsefiles}
│ └── GITLAB
│ └── 3
│ └── 0
│ └── {pulsefiles}
├── main_code_run
│ └── run_actor.sh
├── modules
│ ├── modules_gitlab.yml
│ └── modules_iter.yml
├── native_codes_build
│ └── build_actor.sh
├── pytest_scripts
│ ├── conftest.py
│ ├── __init__.py
│ ├── pytest.ini
│ └── test_actor.py
├── README.md
├── test.sh
└── utils
├── get_actor_info.py
├── get_ids_info.py
└── get_ids_name.py
3. CI engine - ITER or GITLAB
Actor Testing Framework is prepared to run on both ITER CI (called Bamboo) and GITLAB CI (works like Gateway).
There is a slight difference between these platforms that causes the framework to be configured differently to run tests on each of them.
3.1. ITER CI Configuration
3.1.1. ITER Modules
To set up the ITER modules needed to build and run the actor, there is a file called modules/modules_iter.yml , where you need to provide all the necessary modules, preferably full versions.
├── modules │ ├── modules_gitlab.yml │ └── modules_iter.yml # <-- This is file dedicated for ITER modules ############################################## - example: inside modules_iter.yml: ############################################## modules: - IMAS - iWrap - INTERPOS/9.1.0-intel-2020b - XMLlib/3.3.1-intel-2020b
3.1.2. Configuration files
3.1.2.1. Actor configuration
There is YAML file in the configs directory called actor_configuration.yml that contain metadata about the actor being tested. For now, only the fields: actor name and relative path from the project root to the actor description file are to be set.
├── configs │ ├── actor_configuration.yml # <-- this file │ └── ids_configuration.yml ############################################## - example: inside actor_configuration.yml: ############################################## actor_name: NAME actor_path: actor/description/file.yaml
3.1.2.2. IDS configuration
The Actor Testing Framework assumes that the user needs to prepare input files, output files, and expected (reference) IDS pulse files to be used in the execution of the workflow and tests. On the user side, these files can be placed in the public, user, or custom imasdb path, but only the public and custom imasdb path can be used for the remote CI. This is set in the ids_configuration.yml file and must match the pulse files and IDS used by the actor workflow.
├── configs │ ├── actor_configuration.yml │ └── ids_configuration.yml # <-- this file ############################################## - example: inside ids_configuration.yml: ############################################## input_ids: user: ./tests/input_pulse_file output_ids: database: ITER user: ./tests/input_pulse_file/ shot: 114100 run: 42 expected_ids: database: ITER user: ./tests/input_pulse_file/ shot: 114100 run: 43
For your convenience, the Actor Testing Framework comes with a custom imasdb, located under: testing/input_pulse_file/ITER directory path that must be accessed from the relative path of the project root directory.
3.2. CI script
3.2.1. Repository side CI scripts
ITER has a convention to put all CI-related scripts in the ci_scripts/ directory. Actor Testing Framework follows this convention, but can be extended with an additional file in the root directory: ci_scripts/ci_atf.sh. Then, in this upper CI script, you need to execute the lower file: tests/ci_scripts/.iter-ci.sh.
Project_root ├── ci_scripts/ │ ├── ci_atf.sh # <-- Upper CI script │ ├── ... │ └── ci_...sh │ ├── root_files.extension ├── root_directiories/ │ └── tests/ └── ci_scripts/ └── .iter-ci.sh # <-- Lower CI script ############################################## - example: inside upper ci script: ci_atf.sh ############################################## #!/bin/sh ./$(dirname $0)/../tests/ci_scripts/.iter-ci.sh
3.2.2. Remote ITER CI side
On the remote side of ITER CI - Bamboo CI, you need to create a dedicated job for the Actor Testing Framework and a task to run the CI script. The image below shows how such a task can be configured with the top CI script.
3.3. Building Actor Native Codes
Inside the Actor Testing Framework test directory there is a dedicated directory for building native actor code instructions called: native_codes_build/. By default, there is a build_actor.sh script that should provide step-by-step instructions on how to build an actor. For example, it could be a simple make command, but first you need to change the directory your codes are in, basically it should be done the same way you build the codes from the root directory.
tests ├── native_codes_build │ └── build_actor.sh # <-- This file . . .