source commit: e716a59

Author: actions-user

1-intro-to-unit-tests.md

@@ -0,0 +1,134 @@
+---
+title: "Introduction to Unit Testing"
+teaching: 
+exercises: 
+---
+
+:::::::::::::::::::::::::::::::::::::: questions 
+
+- What is unit testing?
+- Why do we need unit tests?
+- What makes src code difficult to unit test?
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+::::::::::::::::::::::::::::::::::::: objectives
+
+- Define the key aspects of a good unit test (isolated, testing minimal functionality, fast, etc).
+- Understand the key anatomy of a unit test in any language.
+- Explain the benefit of unit tests on top of integration/e2e tests.
+- Understand when to run unit tests.
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+## What is unit testing?
+
+Unit testing is a way of verifying the validity of a code base by testing its smallest individual components, or **units**.
+
+>*"If the parts don't work by themselves, they probably won't work well together"*
+> --  (Thomas and Hunt, 2019, [The pragmatic programmer](https://search.worldcat.org/search?q=bn:9780135957059), Topic 51).
+
+Several key aspects define a unit test. They should be...
+
+- **Isolated** - Does not rely on any other unit of code within the repository.
+- **Minimal** - Tests only one unit of code.
+- **Fast** - Run on the scale of ms or s. 
+
+::::::::::::::::::::::::::::::::::::: callout
+
+#### Other forms of testing
+
+There are other forms of testing, such as integration testing in which two or more units of a code base are tested to verify that they work together, or that they are correctly **integrated**.
+However, today we are focusing on unit tests as it is often the case that many of these larger tests are written using the same test tools and frameworks, hence we will make progress with both by starting with unit testing.
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+### What does a unit test look like?
+
+All unit tests tend to follow the same pattern of Given-When-Then.
+
+- **Given** we are in some specific starting state
+    - Units of code almost always have some inputs. These inputs may be scalars to be passed into a function, but they may also be an external dependency such as a database, file or array which must be allocated.
+    - This database, file or array memory must exist before the unit can be tested. Hence, we must set up this state in advance of calling the unit we are testing.
+- **When** we carry out a specific action
+    - This is the step in which we call the unit of code to be tested, such as a call to a function or subroutine.
+    - We should limit the number of actions being performed here to ensure it is easy to determine which unit is failing in the event that a test fails.
+- **Then** some specific event/outcome will have occurred.
+    - Once we have called our unit of code, we must check that what we expected to happen did indeed happen.
+    - This could mean comparing a scalar or vector quantity returned from the called unit against some expected value. However, it could be something more complex such as validating the contents of a database or outputted file.
+
+::::::::::::::::::::::::::::::::::::: challenge 
+
+#### Challenge 1: Write a unit test in sudo code.
+
+Assuming you have a function `reverse_array` which reverses the order of an allocated array. Write a unit test in pseudo code for `reverse_array` using the pattern above.
+
+:::::::::::::::::::::::: solution 
+ 
+ ```
+! Given
+Allocate the input array `input_array`
+Fill `input_array`, for example with `(1,2,3,4)`
+Allocate the expected output array `expected_output_array`
+Fill `expected_output_array` with the correct expected output, i.e., `(4,3,2,1)`
+
+! When
+Call `reverse_array` with `input_array`
+
+! Then
+for each element in `input_array`:
+    Assert that the corresponding element of `expected_output_array` matches that of `input_array`
+```
+
+:::::::::::::::::::::::::::::::::
+::::::::::::::::::::::::::::::::::::::::::
+
+### When should unit tests be run?
+
+A major benefit of unit tests is the ability to identify bugs at the earliest possible stage. Therefore, unit tests should be run frequently throughout the development process. Passing unit tests give you and your collaborators confidence that changes to your code aren't modifying the previously expected behaviour, so run your unit tests...
+
+- if you make a change locally
+- if you raise a merge request
+- if you plan to do a release
+- if you are reviewing someone else's changes
+- if you have recently installed your code into a new environment
+- if your dependencies have been updated
+
+Basically, all the time.
+
+### Do we really need unit tests?
+
+Yes! 
+
+You may be thinking that you don't require unit tests as you already have some well-defined end-to-end test cases which demonstrate that your code base works as expected. However, consider the case where this end-to-end test begins to fail. The message for this failure is likely to be something along the lines of
+
+```
+Expected my_special_number to be 1.234 but got 5.678
+```
+
+If you have a comprehensive understanding of your code, perhaps this is all you need. However, assuming the newest feature that caused this failure was not written by you, it's going to be difficult to identify what is going wrong without some lengthy debugging. 
+
+Now imagine the situation where this developer added unit tests for their new code. When running these unit tests, you may see something like
+
+```
+test_populate_arrays Failed: Expected 1 for index 1 but got 0
+```
+
+This is much clearer. We immediately have an idea of what could be going wrong and the unit test itself will help us determine the problematic code to investigate.
+
+::::::::::::::::::::::::::::::::::::: challenge 
+
+### Challenge 2: Unit test bad practices
+
+Take a look at [1-into-to-unit-tests/challenge](https://github.com/UCL-ARC/fortran-unit-testing-exercises/tree/main/episodes/1-into-to-unit-tests/challenge) in the exercises repository.
+
+:::::::::::::::::::::::::::::::: solution
+
+A solution is provided in [1-into-to-unit-tests/solution](https://github.com/UCL-ARC/fortran-unit-testing-exercises/tree/main/episodes/1-into-to-unit-tests/solution).
+
+:::::::::::::::::::::::::::::::::::::::::
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+## References 
+
+- David Thomas and Andrew Hunt (2019). [The Pragmatic Programmer: your journey to mastery](https://search.worldcat.org/search?q=bn:9780135957059), 20th Anniversary Edition, 2nd Edition. Addison-Wesley Professional.

2-intro-to-fortran-unit-tests.md

@@ -0,0 +1,84 @@
+---
+title: "Introduction to Unit Testing in Fortran"
+teaching:
+exercises:
+---
+
+:::::::::::::::::::::::::::::::::::::: questions 
+
+- Why is there a lack of unit tests in existing Fortran codes?
+- Why do we need to write unit tests for Fortran code?
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+::::::::::::::::::::::::::::::::::::: objectives
+
+- Understand the need for unit testing Fortran code.
+- Identify Fortran code which is problematic for unit testing.
+- Understand steps to make Fortran more unit testable.
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+## Why your Fortran may not already be unit tested
+
+Many Fortran codes don't yet have unit tests. This can be for a number of reasons...
+
+- Lack of resources (time and/or money).
+    - Funding is earmarked for furthering science.
+- The code is not able be unit tested in its current state.
+    - Code is written in Fortran 77 or uses outdated paradigms which make unit testing near impossible.
+- Lack of skills.
+    - Developers don't have the skills to implement unit tests.
+
+## What's the matter with Fortran?
+
+Assuming we have the time, money and the skills to implement some unit tests in a Fortran project, what about the code makes it a challenge to do so?
+
+Various bad practices can make it difficult to unit test Fortran including...
+
+- Global variables
+- Large, multipurpose procedures
+
+::::::::::::::::::::::::::::::::::::: challenge 
+
+#### Challenge 1: Identify bad practice for unit testing Fortran
+
+Take a look at [2-intro-to-fortran-unit-tests/challenge](https://github.com/UCL-ARC/fortran-unit-testing-exercises/tree/main/episodes/2-intro-to-fortran-unit-tests/challenge) in the exercises repository.
+
+:::::::::::::::::::::::::::::::: solution
+
+A solution is provided in [2-intro-to-fortran-unit-tests/solution](https://github.com/UCL-ARC/fortran-unit-testing-exercises/tree/main/episodes/2-intro-to-fortran-unit-tests/solution).
+
+:::::::::::::::::::::::::::::::::::::::::
+::::::::::::::::::::::::::::::::::::::::::
+
+## How to start improving
+
+Unit tests do not need to be added to a Fortran project in one huge implementation. The best approach is to incrementally add unit tests 
+
+1. Ensure an end-to-end test exists
+    - This can be written in a different language if needed. Pytest is often a good choice.
+2. Identify a procedure with minimal dependencies 
+    - If one can't be found extract one into a procedure
+3. Ensure end-to-end test covers this procedure
+    - Try to break the procedure and check your test fails as expected.
+4. Remove all non-local state in the procedure
+5. Check end-to-end test passes
+6. Write unit test(s) for procedure
+7. Repeat steps 1-6
+
+This incremental approach will, over time, become smoother. As more unit tests exist the code will become easier to unit test as its infrastructure will become more mature and feature rich.
+
+::::::::::::::::::::::: callout
+
+### Working effectively with legacy code
+
+Untested codebase is effectively legacy code. Therefore, a great resource for us is *[Working Effectively with Legacy Code](https://search.worldcat.org/title/660166658)* (Feathers, 2004)
+
+If you don't have time to read the entire book, there is a good summary of the key point in this blog post [The key points of Working Effectively with Legacy Code](https://understandlegacycode.com/blog/key-points-of-working-effectively-with-legacy-code/)
+
+:::::::::::::::::::::::::::::::
+
+## References 
+
+- Michael Feathers (2004). [Working Effectively with Legacy Code](https://search.worldcat.org/title/660166658). Pearson.