Restructure ep 6 and add pfunit task and solution

connoraird · connoraird · commit 331e09b0fe9c · 2025-10-03T16:17:46.000+01:00
diff --git a/.gitignore b/.gitignore
@@ -3,4 +3,4 @@
 **.mod
 **build
 **build-cmake
-pfunit
+./pfunit
diff --git a/episodes/6-writing-your-first-unit-test/challenge/CMakeLists.txt b/episodes/6-writing-your-first-unit-test/challenge/CMakeLists.txt
@@ -0,0 +1,15 @@
+cmake_minimum_required(VERSION 3.9 FATAL_ERROR)
+
+# Set project name
+project(
+  "temp_conversions"
+  LANGUAGES "Fortran"
+  VERSION "0.0.1"
+  DESCRIPTION "Library for converting between various temperatures"
+)
+
+# Define src file(s)
+set(PROJ_SRC_FILES "${PROJECT_SOURCE_DIR}/src/temp_conversions.f90")
+
+enable_testing()
+add_subdirectory("test")
diff --git a/episodes/6-writing-your-first-unit-test/challenge/README.md b/episodes/6-writing-your-first-unit-test/challenge/README.md
@@ -13,7 +13,9 @@ provided are...
 - **fahrenheit_to_celsius**: Which takes in a temperature in Fahrenheit and returns a temperature in Celsius.
 - **celsius_to_kelvin**: Which takes in a temperature in Celsius and returns a temperature in Kelvin.
 
-## The task
+## The tasks
+
+### Part 1 - Test with Standard Fortran
 
 Imagine you wish to use the temp_conversions library to convert Fahrenheit to Kelvin. We
 know that there is no function which does this direct conversion. With this is mind, write
@@ -28,3 +30,28 @@ the test was successful. The character array `failure_message`, should be popula
 message that will be printed to the terminal in the event that `passed` is `.false.`. Once
 the test subroutine is written it should be called within the main body of the test program
 as indicated in `test_temp_conversions.f90`.
+
+### Part 2 - Convert tests to use pFUnit
+
+Convert your tests from [Part 1](#part-1---test-with-standard-fortran), to use
+[pFUnit](https://github.com/Goddard-Fortran-Ecosystem/pFUnit).
+
+A file [test_temp_conversions.pf](./test/pfunit/test_temp_conversions.pf) containing a template
+for your pFUnit test(s) has been provided. Comments within this file indicate the aspects of
+the pFUnit test you must write.
+
+> Note: This template has been written to facilitate conversion of
+> [test_temp_conversions.f90](./test/test_temp_conversions.f90) as provided with this repo
+> to pFUnit. If your version of test_temp_conversions.f90, produced in Part 1, is significantly
+> different, You may prefer to use a different structure to the one provided in the template.
+
+To build and run your pFUnit test(s) you must add the pFUnit lib to the `CMAKE_PREFIX_PATH`
+when building via the following command.
+
+```bash
+cmake -B build -DCMAKE_PREFIX_PATH=/path/to/pfunit/install
+cmake --build build
+ctest --test-dir build --output-on-failure
+```
+
+> If you are using the devcontainer, there is an installation of pFUnit at /home/vscode/pfunit/build/installed
diff --git a/episodes/6-writing-your-first-unit-test/challenge/src/temp_conversions.f90 b/episodes/6-writing-your-first-unit-test/challenge/src/temp_conversions.f90
diff --git a/episodes/6-writing-your-first-unit-test/challenge/test/CMakeLists.txt b/episodes/6-writing-your-first-unit-test/challenge/test/CMakeLists.txt
@@ -0,0 +1,7 @@
+find_package(PFUNIT QUIET)
+
+if (PFUNIT_FOUND)
+    add_subdirectory("pfunit")
+else()
+    add_subdirectory("standard_fortran")
+endif()
diff --git a/episodes/6-writing-your-first-unit-test/challenge/test/pfunit/.gitignore b/episodes/6-writing-your-first-unit-test/challenge/test/pfunit/.gitignore
@@ -0,0 +1 @@
+*.f90
diff --git a/episodes/6-writing-your-first-unit-test/challenge/test/pfunit/CMakeLists.txt b/episodes/6-writing-your-first-unit-test/challenge/test/pfunit/CMakeLists.txt
@@ -0,0 +1,23 @@
+message(STATUS "Using pFUnit")
+
+set(TEST_DIR "${PROJECT_SOURCE_DIR}/test/pfunit")
+
+# Create library for src code
+add_library (sut STATIC ${PROJ_SRC_FILES})
+
+# List all test files
+file(GLOB
+    PROJ_TEST_FILES
+    "${TEST_DIR}/*.pf"
+)
+
+list(LENGTH test_srcs num_test_srcs)
+if (num_test_srcs EQUAL 0)
+    message(FATAL_ERROR "No .pf files found in: ${TEST_DIR}")
+endif()
+
+add_pfunit_ctest (pfunit_test_temp_conversions_exec
+    TEST_SOURCES ${test_srcs}
+    LINK_LIBRARIES sut # your application library
+    )
+
diff --git a/episodes/6-writing-your-first-unit-test/challenge/test/pfunit/test_temp_conversions.pf b/episodes/6-writing-your-first-unit-test/challenge/test/pfunit/test_temp_conversions.pf
@@ -0,0 +1,47 @@
+module test_temp_conversions
+    use temp_conversions, only : fahrenheit_to_celsius, celsius_to_kelvin
+    ! allow(C121)
+    use funit
+    implicit none
+
+    public
+
+    !> Test parameter type to package the test parameters
+    ! Your changes here...
+
+    !> Test case type to specify the style of test (paramaterized)
+    ! Your changes here...
+
+contains
+
+    !*************************************************************************!
+    !                      Test fahrenheit_to_celsius                         !
+    !*************************************************************************!
+
+    !> Test suite for tests of fahrenheit_to_celsius
+    ! Your changes here...
+
+    !> Unit test subroutine for fahrenheit_to_celsius
+    ! Your changes here...
+
+    !*************************************************************************!
+    !                         Test celsius_to_kelvin                          !
+    !*************************************************************************!
+
+    !> Test suite for tests of celsius_to_kelvin
+    ! Your changes here...
+
+    !> Unit test subroutine for celsius_to_kelvin
+    ! Your changes here...
+
+    !*************************************************************************!
+    !                              Constructors                               !
+    !*************************************************************************!
+
+    !> Constructor for converting test parameters into a test case
+    ! Your changes here...
+
+    !> Constructor for converting test parameters into a string
+    ! Your changes here...
+
+end module test_temp_conversions
diff --git a/episodes/6-writing-your-first-unit-test/challenge/test/standard_fortran/CMakeLists.txt b/episodes/6-writing-your-first-unit-test/challenge/test/standard_fortran/CMakeLists.txt
@@ -0,0 +1,21 @@
+message(STATUS "Using standard Fortran")
+
+set(TEST_DIR "${PROJECT_SOURCE_DIR}/test/standard_fortran")
+
+# Define test file(s)
+file(GLOB test_srcs "${TEST_DIR}/*.f90")
+
+list(LENGTH test_srcs num_test_srcs)
+if (num_test_srcs EQUAL 0)
+    message(FATAL_ERROR "No .f90 files found in: ${TEST_DIR}")
+endif()
+
+# Build test executable
+add_executable(test_temp_conversions_exec
+    "${PROJ_SRC_FILES}"
+    "${test_srcs}"
+)
+
+# Add test as ctest
+add_test(NAME test_temp_conversions COMMAND test_temp_conversions_exec)
+
diff --git a/episodes/6-writing-your-first-unit-test/challenge/test/standard_fortran/test_temp_conversions.f90 b/episodes/6-writing-your-first-unit-test/challenge/test/standard_fortran/test_temp_conversions.f90
diff --git a/episodes/6-writing-your-first-unit-test/solution/README.md b/episodes/6-writing-your-first-unit-test/solution/README.md
@@ -1,13 +1,16 @@
 # Writing your first unit test - Standard Fortran - Solution
 
+## Part 1 - Test with Standard Fortran
+
 The solution is provided in the form of a single test file [test_temp_conversions.f90](./test_temp_conversions.f90)
-which replaces the file of the same name provided in the [challenge/test](../challenge/test/) directory.
+which replaces the file of the same name provided in the
+[challenge/test/standard_fortran](../challenge/test/standard_fortran/) directory.
 
-## Key points
+### Key points
 
 There are several key aspects within the solution that are important to implement in any test.
 
-### Isolated test subroutine
+#### Isolated test subroutine
 
 Each test subroutine in [test_temp_conversions.f90](./test_temp_conversions.f90) calls and tests only one src
 function. For example, `test_fahrenheit_to_celsius` calls and tests `fahrenheit_to_celsius` and
@@ -18,21 +21,37 @@ If instead we had implemented a single test subroutine which calls both `test_fa
 `fahrenheit_to_celsius`, then a failure in such a test could have been caused by either of those src functions and further
 investigation would be required.
 
-### Parameterised tests
+#### Parameterised tests
 
 Each test subroutine in [test_temp_conversions.f90](./test_temp_conversions.f90) take in an `input` and an `expected_output`.
 This allows the same test subroutine to be called with multiple different inputs to test several scenarios with the same test
 code. Therefore, we are able to test edge cases and other key scenarios more easily.
 
-### Clear failure message
+#### Clear failure message
 
 Each test subroutine in [test_temp_conversions.f90](./test_temp_conversions.f90) populates `failure_message` with a clear
 message that aims to make it as easy as possible to diagnose a failing test. Importantly, the `failure_message` includes the
 `input`, the `expected_output` and the actual value which we have compared to the `expected_output`.
 
-### Comparing floats within an appropriate tolerance
+#### Comparing floats within an appropriate tolerance
 
 We cannot compare two floats directly as due to rounding errors they will almost always
 not be exactly the same. Therefore, we must check the difference between two floats that
 we expect to be equal and ensure it is less than some appropriate tolerance. This tolerance
 should be as small as possible whilst still making sense with the code we are testing.
+
+## Part 2 - Convert tests to use pFUnit
+
+The solution is provided in the form of a single test file [test_temp_conversions.pf](./test_temp_conversions.pf)
+which replaces the file of the same name provided in the [challenge/test/pfunit](../challenge/test/pfunit/) directory.
+
+### Key points
+
+All the key points mention within [Part 1](#key-points) are upheld in this solution. Any additional points are
+detailed below.
+
+#### Add a description for each test
+
+For each set of parameters in [test_temp_conversions.pf](./test_temp_conversions.pf) there is a description provided
+which aims to make clear what is being tested. This can be useful when thinking about test coverage of edge cases.
+It can also help in the event of a test failure to hint at what the problem may be.
diff --git a/episodes/6-writing-your-first-unit-test/solution/test_temp_conversions.f90 b/episodes/6-writing-your-first-unit-test/solution/test_temp_conversions.f90
@@ -11,11 +11,13 @@ program test_temp_conversions
     logical :: passed(7)
     character(len=200) :: failure_message(7)
 
-    call test_fahrenheit_to_celsius(0.0, -17.77778, passed(1), failure_message(1))
+    ! Define set of tests for fahrenheit_to_celsius by calling test with various inputs and expected outputs
+    call test_fahrenheit_to_celsius(0.0, -17.777779, passed(1), failure_message(1))
     call test_fahrenheit_to_celsius(32.0, 0.0, passed(2), failure_message(2))
-    call test_fahrenheit_to_celsius(-100.0, -73.33, passed(3), failure_message(3))
-    call test_fahrenheit_to_celsius(1.23,-17.09, passed(4), failure_message(4))
+    call test_fahrenheit_to_celsius(-100.0, -73.333336, passed(3), failure_message(3))
+    call test_fahrenheit_to_celsius(1.23,-17.094444, passed(4), failure_message(4))
 
+    ! Define set of tests for celsius_to_kelvin by calling test with various inputs and expected outputs
     call test_celsius_to_kelvin(0.0, 273.15, passed(5), failure_message(5))
     call test_celsius_to_kelvin(-273.15, 0.0, passed(6), failure_message(6))
     call test_celsius_to_kelvin(-173.15, 100.0, passed(7), failure_message(7))
@@ -52,8 +54,8 @@ subroutine test_fahrenheit_to_celsius(input, expected_output, passed, failure_me
         passed = abs(actual_output - expected_output) < tolerance
 
         ! Populate the failure message
-        write(failure_message, '(A,F7.2,A,F7.2,A,F7.2)') "Failed With ", input, ": Expected ", expected_output, " but got ", &
-                                                 actual_output
+        write(failure_message, '(A,F7.2,A,F7.2,A,F7.2,A)') "Failed With ", input, "°F: Expected ", expected_output, &
+                                                         "°C but got ", actual_output, "°C"
     end subroutine test_fahrenheit_to_celsius
 
     !> Unit test subroutine for celsius_to_kelvin
@@ -76,7 +78,7 @@ subroutine test_celsius_to_kelvin(input, expected_output, passed, failure_messag
         passed = abs(actual_output - expected_output) < tolerance
 
         ! Populate the failure message
-        write(failure_message, '(A,F7.2,A,F7.2,A,F7.2)') "Failed With ", input, ": Expected ", expected_output, " but got ", &
-                                                 actual_output
+        write(failure_message, '(A,F7.2,A,F7.2,A,F7.2,A)') "Failed With ", input, "°C: Expected ", expected_output, &
+                                                           "°K but got ", actual_output, "°K"
     end subroutine test_celsius_to_kelvin
 end program test_temp_conversions
diff --git a/episodes/6-writing-your-first-unit-test/solution/test_temp_conversions.pf b/episodes/6-writing-your-first-unit-test/solution/test_temp_conversions.pf
@@ -0,0 +1,122 @@
+module test_temp_conversions
+    use temp_conversions, only : fahrenheit_to_celsius, celsius_to_kelvin
+    ! allow(C121)
+    use funit
+    implicit none
+
+    public
+
+    !> Type to package the test parameters
+    @TestParameter
+    type, extends(AbstractTestParameter) :: temp_conversions_test_params_t
+        !> The temperature to input into the function being tested
+        real :: input
+        !> Theb temperature expected to be returned from the function being tested
+        real :: expected_output
+        !> A description of the test to be outputted for logging
+        character(len=100) :: description
+    contains
+        procedure :: toString => temp_conversions_test_params_t_toString
+    end type temp_conversions_test_params_t
+
+    !> Type to specify the style of test (paramaterized)
+    @TestCase(constructor=new_test_case)
+    type, extends(ParameterizedTestCase) :: temp_conversions_test_case_t
+        type(temp_conversions_test_params_t) :: params
+    end type temp_conversions_test_case_t
+
+contains
+
+    !*************************************************************************!
+    !                      Test fahrenheit_to_celsius                         !
+    !*************************************************************************!
+
+    !> Test suite for tests of fahrenheit_to_celsius
+    function fahrenheit_to_celsius_testsuite() result(params)
+        !> An array of test parameters, each specifying an individual test
+        class(temp_conversions_test_params_t), allocatable :: params(:)
+
+        params = [ &
+            temp_conversions_test_params_t(0.0, -17.777779, "0.0 °F"), &
+            temp_conversions_test_params_t(32.0, 0.0, "0.0 °C"), &
+            temp_conversions_test_params_t(-100.0, -73.333336, "100 °F"), &
+            temp_conversions_test_params_t(1.23,-17.094444, "Decimal °F") &
+        ]
+    end function fahrenheit_to_celsius_testsuite
+
+    !> Unit test subroutine for fahrenheit_to_celsius
+    @Test(testParameters={fahrenheit_to_celsius_testsuite()})
+    subroutine test_fahrenheit_to_celsius(this)
+        !> The test case which indicates the type of test we are running
+        class(temp_conversions_test_case_t), intent(inout) :: this
+
+        character(len=200) :: failure_message
+        real :: actual_output
+
+        ! Get the actual celsius value returned from fahrenheit_to_celsius
+        actual_output = fahrenheit_to_celsius(this%params%input)
+
+        ! Populate the failure message
+        write(failure_message, '(A,F7.2,A,F7.2,A,F7.2,A)') "Failed With ", this%params%input, " °F: Expected ", &
+                this%params%expected_output, "°C but got ", actual_output, "°C"
+        @assertEqual(this%params%expected_output, actual_output, tolerance=1e-6, message=trim(failure_message))
+
+    end subroutine test_fahrenheit_to_celsius
+
+    !*************************************************************************!
+    !                         Test celsius_to_kelvin                          !
+    !*************************************************************************!
+
+    !> Test suite for tests of celsius_to_kelvin
+    function celsius_to_kelvin_testsuite() result(params)
+        !> An array of test parameters, each specifying an individual test
+        class(temp_conversions_test_params_t), allocatable :: params(:)
+
+        params = [ &
+            temp_conversions_test_params_t(0.0, 273.15, "0.0 °C"), &
+            temp_conversions_test_params_t(-273.15, 0.0, "0.0 °K"), &
+            temp_conversions_test_params_t(-173.15, 100.0, "100.0 °K") &
+        ]
+    end function celsius_to_kelvin_testsuite
+
+    !> Unit test subroutine for celsius_to_kelvin
+    @Test(testParameters={celsius_to_kelvin_testsuite()})
+    subroutine test_celsius_to_kelvin(this)
+        !> The test case which indicates the type of test we are running
+        class(temp_conversions_test_case_t), intent(inout) :: this
+
+        character(len=200) :: failure_message
+        real :: actual_output
+
+        ! Get the actual kelvin value returned from celsius_to_kelvin
+        actual_output = celsius_to_kelvin(this%params%input)
+
+        ! Populate the failure message
+        write(failure_message, '(A,F7.2,A,F7.2,A,F7.2,A)') "Failed With ", this%params%input, "°C: Expected ", &
+                this%params%expected_output, "°K but got ", actual_output, "°K"
+        @assertEqual(this%params%expected_output, actual_output, tolerance=1e-6, message=trim(failure_message))
+
+    end subroutine test_celsius_to_kelvin
+
+    !*************************************************************************!
+    !                              Constructors                               !
+    !*************************************************************************!
+
+    !> Constructor for converting test parameters into a test case
+    function new_test_case(testParameter) result(tst)
+        !> The parameters to be converted to a test case
+        type(temp_conversions_test_params_t), intent(in) :: testParameter
+        !> The test case to return after conversion from parameters
+        type(temp_conversions_test_case_t) :: tst
+        tst%params = testParameter
+    end function new_test_case
+
+    !> Constructor for converting test parameters into a string
+    function temp_conversions_test_params_t_toString(this) result(string)
+        !> The parameters to be converted to a string
+        class(temp_conversions_test_params_t), intent(in) :: this
+        character(:), allocatable :: string
+        string = trim(this%description)
+    end function temp_conversions_test_params_t_toString
+
+end module test_temp_conversions
diff --git a/episodes/6-writing-your-first-unit-test/standard-fortran/challenge/CMakeLists.txt b/episodes/6-writing-your-first-unit-test/standard-fortran/challenge/CMakeLists.txt
