Why, oh why must I Unit Test!

Unit tests are an important part of making sure we don't, unintentionally, ruin our life or others. :face_palm:

--> Insert funny analogy here :expressionless: <--

In that spirit, contributors, let us all do our part! :yin_yang:

To Play with Existing Tests

To see what tests are already part of the system you can run (from your IDE) all the regression tests. This can be helpful in finding issues if the python regression system fails. To do so:

1. Copy runAll_Dymola.mos from /TRANSFORM-Library/ to your favorite place to run models. Recommended for that to be a directory such as /Documents/Dymola/.
2. Open up your IDE and execute the runAll_Dymola.mos script.

TADA!

Unit Test Setup --Modelica--

Unit tests are automagically added to the regression system from a python script if 3 simple things are followed.

1. The model to be added must be put in a package labeled Examples complete with the icon extension TRANSFORM.Icons.ExamplesPackage.

   /images/unitTesting/1_fluid.png

2. The model to be added must also extend the icon TRANSFORM.Icons.Example at the highest level.

   • Note: Currently a model's unit test in an Examples package can not have the same name as any other model in any other Examples package, regardless of path. I know, I know... super lame. This is a current "feature" of the buildingspy regression system we are piggybacking :pig2:. Fortunately, when you run the regression test system you'll get a friendly reminder letting you know you need to change it.

   /images/unitTesting/2_rankine.png

3. The unit test model TRANSFORM.Utilities.ErrorAnalysis.UnitTests must be placed on the model with the default name unitTests.

   • Note: The variable(s) set to unitTest.x will be added to the regression system. unitTest.x_reference provides a place to put the expected result if desired to make a comparison from the IDE. However, values other than x from UnitTests are not saved to the regression test reference result file.

   /images/unitTesting/3_unit.png

4. Lots of extraneous files get put to a Modelica library during development. Before running the python scripts to add files to the regression system you need to clean up files, either manually or using a directory saving approach (recommended) described below.

   • (From IDE) Right-click TRANSFORM and check "Store as one file".
   • (From IDE) Save TRANSFORM to a temporary location (e.g, Desktop).
   • Move the directory /TRANSFORM-Library/TRANSFORM/Resources up a level to /TRANSFORM-Library/. This file will not be retained in the single file version of the library.
   • Delete the directory /TRANSFORM-Library/TRANSFORM/
   • (From IDE) Right-click TRANSFORM and uncheck "Store as one file". If prompted, select "Directores - No Questions".
   • (From IDE) Save TRANSFORM back to the original location (i.e., /TRANSFORM-Library/).
   • Now is a good time to check Git to make sure the process performed as expected. You should now have a clean library.
   • Commit changes to Git.

Take a gander at existing examples to get a real feel for how it works. Next up, python!

Add Unit Tests to Regression System --Python--

1. Run createUnitScrips.py from its location (i.e., TRANSFORM-Library\TRANSFORM\Resources\python as the working directory)
   • This deletes the entire /Resources/Scripts/ directory and rebuilds it from scratch
2. Check that the expected .mos files were added to the /Resources/Scripts/ directory.
3. Run pip install buildingspy==1.6.0 from the terminal if buildingspy is not already installed
   • Currently this process is tied to an older version of buildingspy in Windows OS. Uncertain about Linux.
4. Run regression system from its location (i.e., TRANSFORM-Library\ as the working directory). Indicate y when prompted to add the results to testing system. These files are saved in /TRANSFORM-Library/TRANSFORM/Resources/ReferenceResults/.
   • Linux: regtestsLinux.py
   • Windows: regtestsWin_customBuildPy.py
   • Note: By default running this file will go through all tests. To simulate a single test use the TestSinglePackage function.
5. If everything looks good, stage and push your changes to your repository and create a merge request.

That's it! Treat yourself :ice_cream:

Troubleshooting :gun:

1. If having issues with buildingspy regression test on Windows system replace buildingspy file regressiontest.py with the one from ModelicaPy (pip install modelicapy or download zip file from Github/Gitlab)
   • regressiontest.py in buildingspy is normally located at C:\Users\USERNAME\AppData\Local\Continuum\anaconda2\Lib\site-packages\buildingspy\development
   • Once replaced, delete the old regressiontest.pyc file if present.
   • The new regressiontest.py file from ModelicaPy may need to be compiled before it can be used. If so, change to the buildingspy\development path and run the following in python (i.e., IPython) to get a new regressiontest.pyc file.
     • import py_compile
     • py_compile.compile('regressiontest.py')
2. It is highly recommended to simulate the runAll*.mos file from Dymola to ensure all unit tests are able to simulate. The current regression system has little to no inspection ability in the event a model fails to simulate.