Unit testing in Fortran workshop

Instructor companion slides

Connor Aird

University College London

2026-11-11

Plan

  1. Setup our environment to run the exercises.
  2. What is a unit test?
  3. A unit test in standard Fortran.
  4. Writing our first pFUnit test.
  5. How to build pFUnit test with CMake.
  6. Parameterising pFUnit tests.
  7. Testing MPI parallelised Fortran

Setup

Example exercises

  1. Open the exercises repo: github.com/carpentries-incubator/fortran-unit-testing/tree/main/exercises
  2. Setup GitHub Codespaces.
    • If this doesn’t work, run the container image locally via vscode. You will need to login to ghcr.io with a personal access token with read:packages permissions.
    • OR, as a last resort, setup you local environment with CMake, pFUnit and gfortran.

What is a unit test?

“If the parts don’t work by themselves, they probably won’t work well together”

(Thomas and Hunt, 2019, The pragmatic programmer, Topic 51).

Definition of a unit test

Unit tests are:

  • Test which verify the correctness of a single unit of code.
  • Isolated
  • Minimal
  • Fast

Benefits of unit tests:

  • Confidence that your code does what you expect.
  • Easier to make changes to you code.
  • Catch bugs before they are introduced.

Our first unit test

Objectives

  • Understand what a unit test looks like.
  • Recognise the benefits of parameterized tests.
  • Be able to write a unit test which is isolated, minimal and fast.

Example libraries

Throughout this workshop we will look at two libraries:

Temperature conversions

You will be writing tests for the temperature conversion library provided in the exercises.

Matrix operations

I will provide worked examples from this matrix operations library

module matrix_ops
    implicit none
contains
    !> Returns the dot product (a.b) of the two inputted arrays a and b
    integer function dot(a, b)
        !> The two arrays to be dotted together
        integer :: a(:), b(:)

        dot = dot_product(a, b)
    end function dot
end module matrix_ops

Testing the temperature

First, how can we test this library using standard Fortran?

solution/standard_fortran/test_temp_conversions.f90

What makes this implementation good? What makes it bad?

Good:

  • The tests are parameterise
  • Good failure logs

Bad:

  • Unable to run a single test in isolation.
  • Extra maintenance of test runner logic.
  • Do not benefit from community development efforts

Our first pFUnit test

Objectives

  • Recognise the benefits of pFUnit vs standard Fortran.
  • Understand how to write a basic pFUnit test.
  • Be able to build and run a pFUnit test using CMake.

Why are we using pFUnit?

Supports testing MPI parallelised code, including parameterising tests by number of MPI ranks.

A few other reasons:

  • The most feature rich framework.
  • The most widely used framework.
  • Being maintained.
  • Dedicated CMake and Make integrations.

Standard Fortran to pFUnit

Live coding example

Starting with the standard Fortran test we saw earlier, follow along writing tests for the temperature conversion library.

Building with CMake

Live code example

Now that we have written a test using pFUnit, let’s build it using CMake. Follow along to build your newly written pFUnit test of the temperature conversion library

Key points

  • pFUnit removes the need to write custom test drivers.
  • Directives tell the pFUnit pre-processor how to convert .pf files into .F90.
  • Assertions can be defined using pre-processor directives such as @assertEqual.
  • pFUnit tests can be built with CMake using add_pfunit_ctest.

Parameterising with pFUnit

Objectives

  • Recognise the benefits of parameterising with derived-types.
  • Understand how to write parameterised pFUnit tests.

Why bother parameterising?

  • Reduce repeated test logic.
  • pFUnit handles reporting failed tests.
  • Ensures the full test suite runs.

And…

It will be much easier when testing MPI parallelised Fortran.

Basic to parameterised pFUnit

What problems are there with the test we’ve just written? What happens in the case when one test scenario fails?

Live coding example

Starting with the pFUnit tests we have just written, follow along parameterising your tests for the temperature conversion library.

Key points

  • We can handle state setup and teardown using derived-types which extend TestCase.
  • We can parameterise tests using derived-types which extend AbstractTestParameter.
  • These derived-types must be decorated with pre-processor directives.
  • Parameterising tests with pFUnit ensures all scenarios run, even if one fails.

Testing MPI parallelised Fortran

Objectives

  • Understand what is different when testing parallel vs serial code.

Writing testable MPI code

Some tips for writing testable MPI code:

Separate serial code from MPI code

  • Procedures which do not call the MPI library can be tested in serial.
  • Isolating MPI functionality from serial makes unit testing easier.

Pass the MPI communicator into each MPI procedure to be tested

  • Passing in the MPI communicator gives us full control of the system.
  • This allows us to use the communicator provided by pFUnit.

More example libraries

Despite what I said earlier, we will look at two more libraries:

MPI Matrix operations

I will continue with an MPI parallelised version of the matrix operations library.

MPI utility functions

You will be writing tests for the mpi_utils library provided in the exercises.

Testing MPI parallelised matrix operations

Live coding example

Let’s look at the MPI parallel matrix operations code we’ll be testing. Follow along writing MPI parallel tests for the MPI utilities library.

Testing more complex MPI procedures

Thus far, we have assumed all ranks should expected the same result during our tests. However, this is often not the case.

Live coding example

Let’s continue writing tests for the matrix operations library and remember to follow along.

Key points

  • If a procedure does not call the MPI library, we shouldn’t need to test it with parallel pfunit.
  • It is much easier to test MPI parallel procedures which take in a communicator.
  • pFUnit will handle the creation of MPI communicators for the requested number of ranks.
  • We extend special MPI derived types from pFUnit in our MPI tests.

Further reading

The full workshop notes can be found in the software carpentries incubator if you wish to read through them in your own time. More exercises can also be found in the exercises directory of the workshop notes repository.

Scan to view the slides

QR code linking to this talk's web page.