howto test dependencies

How to test WaterTAP with specific versions of its dependencies

Scenario 1: Testing a bugfix in IDAES

For this scenario, let's imagine that a recently merged PR in IDAES fixes a bug that might affect WaterTAP. Our goal is to run WaterTAP against the version of IDAES containing the bugfix, and maybe the commit immediately before that (to verify that the bug was indeed fixed thanks to the commit).

• The bug was originally reported in the IDAES/idaes-pse issue tracker as issue #999 (this is just for reference)
• The partial hash for the commit in the IDAES repo that fixes the bug is abc1234
• The partial hash for the commit in the IDAES repo that still has the bug is def5678
• If the IDAES bug is present, the test file named test_my_model.py in the WaterTAP test suite will fail, and pass otherwise
• The version (Git ref) of the WaterTAP repository we want to use for testing is mybranch
• Our local clone of the WaterTAP repository is located at /home/myuser/projects/watertap-stuff/watertap

Step 1: Create a dedicated Conda environment

conda create --name test-fix-idaes-999 python=3.10 --yes && conda activate test-fix-idaes-999

Step 2: Install WaterTAP in editable mode inside the test-fix-idaes-999 environment

cd /home/myuser/projects/watertap-stuff/watertap
git checkout mybranch
pip install --editable ".[testing]"

NOTE pip install --editable ".[testing]" is similar to the usual "developer mode" command pip install -r requirements-dev.txt, but will only install WaterTAP and the dependencies strictly required to run its test suite, as opposed to the full set of developer dependencies (e.g. Sphinx, pylint, ...). The reason for this is that we want to minimize possible conflicts between WaterTAP and IDAES since they'll be installed in the same environment.

NOTE The [abc] syntax in pip install commands is used to specify one or more sets of optional dependencies. For more information, see e.g. this reference.

Step 3: Uninstall WaterTAP's upstream dependencies

• This is to ensure that versions of the upstream dependencies (IDAES, Pyomo) that are compatible with the IDAES commits we want to test are installed, as opposed to the versions specified in the WaterTAP requirements

pip uninstall --yes idaes-pse pyomo

Step 4: Clone the IDAES repository and checkout the first commit to test

cd /home/myuser/projects/watertap-stuff
git clone https://github.com/IDAES/idaes-pse.git && cd idaes-pse
git checkout abc1234

Step 5: Install IDAES in the environment

pip install --editable ".[prerelease]" && idaes get-extensions

We can run pip list to confirm that that both WaterTAP and IDAES are installed from the expected locations (i.e. /home/myuser/projects/watertap-stuff/watertap/ and /home/myuser/projects/watertap-stuff/idaes-pse/ respectively)

Step 6: Run the WaterTAP tests as needed to verify the presence of the bug

cd ../watertap
pytest --pyargs watertap -k test_my_model.py

• The -k pytest flag causes tests defined in other files to be excluded from the test run

Step 7: Check out a different commit in the IDAES repository

cd ../idaes-pse
git checkout def5678
pip install --editable ".[prerelease]" && idaes get-extensions

IMPORTANT Even if IDAES was installed in editable mode, we should make sure to always run the pip install and idaes get-extensions commands after we check out a different commit of the IDAES repository. The reason for this is that the new commit might contain different versions for IDAES's own dependencies and/or solvers, which won't be updated simply by checking out the code.

Step 8: Run the WaterTAP tests again

cd ../watertap
pytest --pyargs watertap -k test_my_model.py