WIP: first draft of explaining parameterised test syntax

Author: connoraird

episodes/4-pfunit-syntax.md

@@ -113,7 +113,7 @@ end module test_dot_product_intrinsic
 
 ## Handling state within tests
 
-If the code we wished to test required some state to be setup prior to running the test, such as allocating arrays, we could repeat this step within each test, like so:
+If multiple tests rely of the existence of some state such as the allocation of an array. We could repeat this step within each test, like so:
 
 ```fortran
 module test_dot_product_intrinsic
@@ -382,8 +382,109 @@ The key features of this the type **dot_product_test_parameters** are
 - It is decorated with the directive **@TestParameter**.
 - It extends the type **AbstractTestParameter** provided by the pFUnit library.
 - All inputs (**a** and **b**) and expected outputs (**expected_dot_product**) of **dot_product** are define as type-bound variables.
-- There is an extra type-bound variable - **description** - which is used alongside the type-bound procedure **toString => dot_product_test_parameters_toString**.
-  - pFUnit requires that a type which extends **AbstractTestParameter** defines a type-bound procedure called **toString**. This procedure is then used to provide a description of the specific parameter set within the name of each test.
-  - For simplicity, we have added the variable **description** which we can be defined and return from **dot_product_test_parameters_toString** (we will cover this shortly).
+- The type-bound variable **description** and procedure **toString** allow conversion of a single test parameter instance to a character array for logging (see below). 
+
+#### toString
+
+pFUnit requires that a type which extends **AbstractTestParameter** must define a type-bound procedure called **toString**:
+
+```fortran
+!> Trims and returns the description of the parameter set. The string returned
+!> by this function will be included by pFUnit in the name of this test
+function toString(this) result(string)
+    class (dot_product_test_parameters), intent(in) :: this
+    character(:), allocatable :: string
+
+    string = trim(this%description)
+end function toString
+```
+
+For simplicity, we utilise the variable **description** to define this string in its entirity.
+
+:::::::::: callout
+
+#### Default type constructor
+
+All derived types in Fortran are given a default constructor of the same name which can be invoked
+like a function. For example, we can create an instance of our type **dot_product_test_parameters**
+like so:
+
+```fortran
+type(dot_product_test_parameters) :: testParameters
+
+testParameters = dot_product_test_parameters(a, b, expected_dot_product, "10x10 incrementing values")
+```
+
+::::::::::::::::::
+
+::::::::::::
+
+:::::::::::: spoiler
+
+### 2. Parameterising the test case
+
+Now that we have a new test parameter type, we must update our test case type to make use of it:
+
+```fortran
+!> Custom test case type allowing a single definition of tearDown logic. 
+!! If teardown is not required, This could also be thought of as boilerplate
+!! required to make the parameters available within our @Test.
+@TestCase(constructor=dot_product_test_case_constructor)
+type, extends(ParameterizedTestCase) :: dot_product_test_case
+    !> The instance of our test parameters type to be used within the test logic
+    type(dot_product_test_parameters) :: params
+contains
+    procedure :: tearDown
+end type dot_product_test_case
+```
+
+The key points to highlight are:
+
+- We are now extending the base type **ParameterizedTestCase**.
+- To prevent duplication we simply define an instance of our test parameter type as a type-bound variable.
+- The type-bound procedure **teardown** remains the same.
+
+#### Test case constructor
+
+Whilst **teardown** remains almost unchanged, **dot_product_test_case_constructor** has changed considerably.
+We now no longer use this as a mechanism to setup state but instead we are converting an instance of our parameter
+type (**dot_product_test_parameters**) into an instance of our test case type (**dot_product_test_case**).
+
+```f90
+!> Boilerplate constructor required to convert our custom parameters type to
+!! the test case type.
+function dot_product_test_case_constructor(testParameters) result(newTestCase)
+    type(dot_product_test_parameters), intent(in) :: testParameters
+    type(dot_product_test_case) :: newTestCase
+
+    newTestCase%params = testParameters
+end function dot_product_test_case_constructor
+```
+
+:::::::::::: callout
+
+#### Setting up state
+
+Now that we are not using the test case constructor for setting up state we need a new place for this to be done.
+Thankfully, pFUnit allows us to do this in similar way to **teardown** by adding a new type-bound procedure within
+our test case type called **setUp**. 
+
+::::::::::::::::::::
+
+:::::::::::: spoiler
+
+### 3. Defining a suite of tests / parameter sets
+
+**TODO:**
+- Returns a list of parameter sets where each set represents a single test
+- If inputs need to be allocated, this is where we do it.
+
+::::::::::::
+
+:::::::::::: spoiler
+
+### 4. Passing the test suite into the @Test
+
+::::::::::::
 
 ::::::::::::