11title: FTorch test suite
22author: Joe Wallwork
3- date: Last Updated: October 2025
3+ date: Last Updated: January 2026
44
55
66## Testing
@@ -12,7 +12,9 @@ tests based on a subset of the [worked examples](|page|/usage/worked_examples.ht
1212- [ Running Tests] ( #running )
1313 - [ Unit Tests] ( #unit-tests )
1414 - [ Integration Tests] ( #integration-tests )
15- - [ Adding Tests] ( #adding-tests )
15+ - [ Contributing Tests] ( #contributing-tests )
16+ - [ Contributing Unit Tests] ( #contributing-unit-tests )
17+ - [ Contributing Integration Tests] ( #contributing-integration-tests )
1618
1719
1820### Building
@@ -60,7 +62,7 @@ demonstrates 'good' versus 'bad' practice, as opposed to functionality.
6062
6163Ensure that the Python virtual environment used when
6264building is active and then run ` ctest ` from the build directory to execute all tests.
63- Use [ ctest arguments] ( https://cmake.org/cmake/help/latest/manual/ctest.1.html )
65+ Use [ CTest arguments] ( https://cmake.org/cmake/help/latest/manual/ctest.1.html )
6466for greater control over the testing configuration.
6567
6668This will produce a report on which of the requested tests passed, and which, if any,
@@ -70,39 +72,78 @@ failed for your build.
7072
7173Unit tests may be executed in the following ways:
7274
73- 1 . To run just the unit tests (tests whose names start with 'unittest') use
74- ` ctest -R unittest ` .
75- 2 . To run a specific unit test use
76- ` ctest -R unittest_tensor_constructors_destructors ` , for example.
75+ 1 . To run all unit tests, use ` ctest -R unittest ` .<br >
76+ (` ctest -R ` accepts a regular expression to search for and this works because
77+ all unit tests start with ` unittest ` .)
78+ 2 . Use a different regular expression to select a subset of unit tests, e.g.,
79+ ` ctest -R unittest_tensor ` to run all unit tests related to ` torch_tensor ` s.
80+ 3 . To run a specific unit test just use its full name, e.g.
81+ ` ctest -R unittest_tensor_constructors_destructors ` .
82+
83+ For a summary of the current unit tests, see the
84+ [ README] ( https://github.com/Cambridge-ICCS/FTorch/blob/main/test/README.md ) .
7785
7886#### Integration tests
7987
8088Integration tests may be executed in the following ways:
8189
82- 1 . To run just the integration tests (tests whose names start with 'example') use
83- ` ctest -R example `
90+ 1 . To run just the integration tests, use ` ctest -R example ` .<br >
91+ (` ctest -R ` accepts a regular expression to search for and this works because
92+ all integration tests start with ` example ` .)
84932 . To run a specific integration test use ` ctest -R example2 ` , for example.<br >
8594 Alternatively navigate to the corresponding example in ` ${BUILD_DIR}/examples `
8695 and call ` ctest ` .
8796
8897
89- ### Adding Tests
90-
91- New components should come with unit tests written using the pFUnit framework.
92-
93- - New unit tests should be added to the ` test/unit/ ` directory and start with
94- ` unittest_ ` .
95- - New tests need including in the ` CMakeLists.txt ` in that directory in order
96- to be built as part of the test suite.
98+ ### Contributing tests
99+
100+ #### Contributing unit tests
101+
102+ New components should come with unit tests written using the
103+ [ pFUnit] ( https://github.com/Goddard-Fortran-Ecosystem/pFUnit ) framework.
104+
105+ - New unit tests should be added to the ` test/unit/ ` directory, have names
106+ that start with ` unittest_ ` and use the ` .pf ` extension.
107+ - Unit test files should include a ` module ` with the same name as the file
108+ (minus the extension).
109+ - If MPI parallelism is required for the unit test, use the ` pfunit ` module
110+ that comes with pFUnit, otherwise its ` funit ` module should be sufficient.
111+ - Tests contained within the module should be written as subroutines with the
112+ ` @test ` decorator and name starting with ` test_ ` .
113+ - pFUnit's ` @assertTrue ` , ` @assertFalse ` , and ` @assertEqual ` decorators should be
114+ used to check expected outcomes.
115+ - In some cases, it can be useful to use parameterisation. This can be
116+ achieved by defining a derived type of ` AbstractTestParameter ` and giving it
117+ the ` @testParameter ` decorator. Additionally, define a derived type of
118+ ` ParameterizedTestCase ` and give it the ` @testCase ` decorator. The test case
119+ acts as a constructor that determines how to pass the parameters to the
120+ tests. Where parameterisation is used, parameter sets should be defined as
121+ functons to create instances of the derived test parameter type.
122+ Parameterised tests should pass the parameters through the ` @test `
123+ decorator. For example,
124+ ``` fortran
125+ @test(testparameters={get_parameters()})
126+ ```
127+ where `get_parameters` is such a function as mentioned above. See existing
128+ unit tests for examples of this.
129+ - New unit tests should be included in `test/unit/CMakeLists.txt` in order to
130+ be built as part of the test suite.
131+ - Don't forget to add a brief summary of the new unit test in the unit test
132+ [README](https://github.com/Cambridge-ICCS/FTorch/blob/main/test/README.md).
133+
134+ #### Contributing integration tests
97135
98136New functionalities should come with integration tests in the form of worked
99137examples.
100138
101139- These should take the form of a new example in the `examples/` directory.
140+ - Create a subdirectory named with the next sequential number and a descriptive
141+ name, e.g. `9_NewFeature`.
102142- In addition to a `CMakeLists.txt` to build the example code there
103143 should also be a section at the end setting up running of the example
104- using CTest.
105- - Integration test names should start with ` example_ `
106- - New examples will also need including in ` examples/CMakeLists.txt `
107- - Ensure the documentation on [ worked examples] ( |page|/usage/worked_examples.html ) is
108- updated accordingly.
144+ using [CTest](https://cmake.org/cmake/help/book/mastering-cmake/chapter/Testing%20With%20CMake%20and%20CTest.html).
145+ - Integration test names should start with `example` followed by the example
146+ number, e.g. `example9`.
147+ - New examples will also need including in `examples/CMakeLists.txt`
148+ - Ensure the documentation on
149+ [worked examples](|page|/usage/worked_examples.html) is updated accordingly.
0 commit comments