Skip to content

Commit

Permalink
Updating testing docs for atmos_phys.
Browse files Browse the repository at this point in the history
  • Loading branch information
mwaxmonsky committed Nov 6, 2024
1 parent c909257 commit bf8fca3
Showing 1 changed file with 47 additions and 0 deletions.
47 changes: 47 additions & 0 deletions docs/atmospheric_physics/development_workflow.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,53 @@ where `cool_new_feature` is an example branch name (you can use any name you wan

**2. Apply your code modifications and/or script additions, and perform at least one test making sure that your modifications work as expected.**

Also make sure that the unit tests all pass and verify if your changes can be unit tested and added to the test suite.

Early development has started for integration of [pFUnit](https://github.com/Goddard-Fortran-Ecosystem/pFUnit) as the toolkit for unit testing Fortran codes. It is similar to [googletest](https://github.com/google/googletest) in providing an explicit interface/setup procedure to make it clear what you are testing and how.

To run the tests, you will need to build pFUnit manually (see either the github workflow for atmospheric_physics or the pFUnit documentation on how to build) and then use that to build the tests:

```bash
$ cmake -DCMAKE_PREFIX_PATH=<path_to_pfunit>/build/installed \
-S./test/unit-test \
-B./build
$ cd build && make
$ ctest
```
This should print something along the lines of
```bash
100% tests passed, 0 tests failed out of 1
```

or show an error if a test failed.

For modules that are testable, it is recommended to add relevant tests that cover those new lines of code. As unit test development is just as much an art form as source code development, we will deffer a discussion on what constitutes as "good tests" to other sources such as [MS.net](https://learn.microsoft.com/en-us/dotnet/core/testing/unit-testing-best-practices), [abseil](https://abseil.io/resources/swe-book/html/ch12.html), [googletest](https://github.com/google/googletest/blob/main/docs/primer.md), [Martin Fowler](https://martinfowler.com/testing/), etc. Just like with source code, philosophical/technical conventions will evolve with the code over time as well.

As of right now, integration is limited but expanding. As new modules become testable, tests should be added for those modules as new modifications are developed in the source directory.

If a module is independent of any external library modules or is dependent on modules already unit tested, it is very likely that it can be added to the testing infrastructure.

To add a test, you need to have a currently existing CMake infrastructure and the code being tested added to a library via `add_library(LIBNAME ...)` in a `CMakeLists.txt` file, then you can use `add_pfunit_ctest(TESTNAME TEST_SOURCES source1.pf ... LINK_LIBRARIES LIBNAME)`. The `test_source.pf` library will contain subroutines of the form:
```fortran
@test
subroutine test_addded_element_equals_get_element()
use funit
use module_under_test_mod
...
@assertEqual(expectedValue, atualValue)
```
The remaining CMake integration details as well as the different assertion methods can be found in pFUnit's [github](https://github.com/Goddard-Fortran-Ecosystem/pFUnit) documentation and the [pFUnit demo](https://github.com/Goddard-Fortran-Ecosystem/pFUnit_demos) repository as well.

Currently only certain `utilities` modules are being tested but this will expand to the rest of atmospheric_physics so check the files being built by the `test/unit-test/CMakeLists.txt` file regularly.

If you are adding a new file, attempt to add it to the list of files being built by the `CMakeLists.txt` and if it builds successfuly, add a corresponding unit test. The current workflow is to take your new file in `schemes/{path_to_file}/new_file.F90` and add a corresponding test file in `test/unit-test/tests/{path_to_file}/test_{new_file}.pf`.

At a minimum, unit tests for ESCOMP source code should:
1) Keep the setup code to the absolute minimum needed to effectively assert object/state data (ie, each line before calling `assert`s should be modifying or preparing state data/objects to be modified exactly as a client or user would do).
2) There should only be 1 block/set of `assert` statements per test. If there are multiple sets of `assert`s with module API calls in between each set, that _probably_ would constitute a new test with a different name.
3) Test names should be as explicit as possible. There are going to be hundreds of names in each test report and having the ability for a reviewer/contributor be able to look at a test and intuitively understand what said test is doing is paramount (this is obviously going to vary slightly based on preferrence but the goal is to have a test name be as intuitive as possible).


**3. Add all the files that you want to commit. There are multiple ways to do this, but one of the safer ways is to first check your status:**

```
Expand Down

0 comments on commit bf8fca3

Please sign in to comment.