GitLab CI

Here you find the Documentation für CI Tests with AixLib

What is CI?

Continuous integration is a term from software development that describes the process of continuously assembling components to form an application. The goal of continuous integration is to increase software quality. Typical actions are translating and linking the application parts, but in principle any other operations to generate derived information are performed. Usually, not only the entire system is rebuilt, but also automated tests are performed and software metrics are created to measure software quality. The whole process is automatically triggered by checking into the version control system.

Interaction with the CI

CI commands

CI Command	Description
git commit -m "ci_create_model_wh"	create a whitelist with models that failed the check job
git commit -m "ci_create_html_wh"	create a whitelist with models that should not go through the html check
git commit -m "ci_create_example_wh"	create a whitelist with models that failed the simulate job
git commit -m "ci_simulate"	Simulate all examples
git commit -m "ci_check"	Check all models
git commit -m "ci_regression_test"	Start the regression test
git commit -m "ci_html"	Test only the html of models
git commit -m "ci_style_check"	Test only the dymola-style of models
git commit -m "ci_setting"	Test the CI settings
git commit -m "ci_trigger_ibpsa"	trigger IBPSA merge
git commit -m "ci_build_structure"	Build the CI structure
git commit -m " <commit_msg> [skip ci]"	Skip the CI pipeline

How to update/create reference results?

You might come across failed regression tests, because the results after you changed something in a model might differ from the results before. Regression testing is particularly useful for showing changes in results. These can be intentional changes, but also unintentional ones. Especially for the last case, the check is useful, because it prevents accidental errors from creeping into the library. In more detail, there are two groups of reasons why a regression test fails:

1. The model results still should be the same:

• You changed a model that is used in others models that you were not aware of
• You simply changed a model you didn't want to change
• You made a mistake in your modeling

→ In this case you need to fix your errors, so that the model again fits the existing regression results

2. The results still should be the same:

• You made changes to a model that were required, maybe even a bugfix but this changed the results. But in this case the new results are correct or at least "more correct" than the old ones. → in this case you have to update the reference results. This again can be done by the CI, you simply need to delete the existing <full_model_path>.txt under AixLib\Resources\ReferenceResults\Dymola. The CI will check if a .mos script exists, but no .txt regression results and create them. After deleting the existing reference results and pushing this to remote branch, the CI will create the results and push them directly to the branch. Please make sure that a pull request already exists, otherwise the CI won't create reference results.

For the Creation of reference results, you simply need to add the corresponding .mosscript and push it to the remote branch. The CI will then generate the reference results in the same way as the update described above.

What CI Tests are implemented?

1. The first stage is an HTML-check, which validates and corrects the HTML-code inside the annotation section of each model. Any corrections are made via an automatically created new branch. The user can subsequently review and merge the branch independently.
2. The Style-Check performs quality checks for each model using the Model Management Library of Dymola. Currently, this stage is allowed to fail for existing models, while new models will need to fulfill the requirements. The following three stages are performed for all packages separately for easier error tracking.
3. Check stage triggers triggers the Modelica Check function for all models. Any syntactic or logical errors (e.g. singularity of the system of equations) will cause this stage to fail.
4. Simulate performs a simulation for all examples of AixLib. These are found based on the Modelica.Icons.Example icon. Any non-successful simulation will cause this stage to fall.
5. Regressiontest is the final stage that verifies that the simulation results of models with existing reference results are in line with the prior results. The regressions are performed using the BuildingsPy library.
6. and 7) Failed regression tests will trigger the preparation of dynamic plots and the deployment of an additional GitLab page, which will display the new and existing, i.e., reference, results based on Google Charts.

CI Structure

The CI structure consists of three repositories.

1. The AixLib repository is a Github repository where for example Modelica models are. These are to be tested later with the CI. So that the CI pipelines has access to the gitlab templates, a reference to the templates in the template repository with the branch AixLib is made in the .gitlab-ci.yml via the command 'include'.

	include:
            project: 'EBC/EBC_all/gitlab_ci/templates'
            ref: AixLib
            file: 'dymola-ci-tests/ci_templates/.gitlab-ci.yml' 

2. The Template repository contains Gitlab templates according to whose syntax the Gitlab pipeline is later formed and triggered. To run the Dymola-python tests they must be cloned in each pipeline job.
3. The Dymola_Python_test Repository includes python scripts or tests.