You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: demo/README.md
+73-59Lines changed: 73 additions & 59 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,43 +1,56 @@
1
-
Example Test Suite Classes
2
-
==========================
3
-
4
1
Getting Started
5
-
---------------
6
-
Likely the fastest way to get started with Julienne is to copy the source code in this directory and modify it for your purposes:
7
-
8
-
1. If you build your project with the Fortran Package Manager ([`fpm`](https://github.com/fotran-lang/fpm)), then you might move the `main.F90` and `specimen_test_m.F90` files from this subdirectory to a `test/` subdirectory in the root of your project's source tree.
2
+
===============
3
+
To get started with Julienne, review and test the demonstration project in this directory.
4
+
Then copy the `main.F90` and `specimen_test_m.F90` files to your project's test directory.
5
+
Finally, modify the files as described below to adapt them to your project.
6
+
7
+
Testing the Demonstration Project
8
+
--------------------------------
9
+
This demonstration project defines a trivial library named "specimen" in the `src`
10
+
subdirectory and a test suite the `test` subdirectory. The test suite includes five tests:
11
+
12
+
1. Two pass.
13
+
2. One intentionally fails to demonstrate diagnostic output.
14
+
3. One test is skipped to the reporting and tallying of skipped tests.
15
+
4. One test passes with three compilers but is skipped with GCC due to a compiler bug.
16
+
17
+
Test Julienne by setting your present working directory to the `demo/` subdirectory in a
18
+
terminal window and then building and running the demonstration project's test suite using
19
+
the command corresponding to your compiler in the table below.
1. If you build your project with the Fortran Package Manager ([`fpm`](https://github.com/fotran-lang/fpm)), then you might copy the `main.F90` and `specimen_test_m.F90` files from this subdirectory to a `test/` subdirectory in the root of your project's source tree.
9
32
2. Rename the `specimen_test_m.F90` file, the `specimen_test_m` module, and the `specimen_test_t` derived type and any references thereto, replacing `specimen` with the name of an entity that you intend to test -- most likely a module containing procedures or derived type with type-bound procedures.
10
33
3. Similarly replace occurrences of `specimen` in the resulting`test/main.F90` file.
11
-
4. Modify the `test_descriptions_t` array constructor in your new `*_test_m.F90` file, adding elements for each test to be performed:
12
-
```fortran
13
-
test_descriptions = [ &
14
-
test_description_t("the type-bound function zero() producing a result of 0", check_zero) &
15
-
]
16
-
```
17
-
5. Replace the above string (`"the type-bound..."`) with a description of your intended test. The test output will read most naturally if your description contains a gerund: a verb ending in "ing" and used as a noun, such as `producing` above.
18
-
6. Replace the `check_zero` function name with the name of a function that will perform your test.
19
-
7. Edit the correspondingly-renamed function to perform the test. The function must take no arguments and define a `test_diagnosis_t` result. An example result might be the following:
20
-
```fortran
21
-
test_diagnosis = test_diagnosis_t( &
22
-
test_passed = actual_value == expected_value &
23
-
,diagnostics_string = "expected value " // string_t(expected_value) //", actual value " // string_t(actual_value) &
24
-
)
25
-
```
26
-
The above `test_diagnosis_t` constructor function invocation demonstrates the recommended pattern for writing tests with Julienne:
34
+
4. In the `results()` function body of your new `*_test_m.F90` file, replace the `test_descriptions_t` array constructor elements with your own test descriptions. The test output will read most naturally if your description string (the first argument) contains a gerund: a verb ending in "ing" and used as a noun, such as `producing` above
35
+
5. Replace the function name (the second argument) with the name of a function that will perform your test.
36
+
7. Edit the correspondingly-renamed function to perform the test. The function must take no arguments and define a `test_diagnosis_t` result.
37
+
38
+
The functions in `specimen_test_m` demonstrate several common options for constructing a `test_diagnosis_t` as the diagnosis function result.
39
+
The options include
27
40
28
-
* Define the `test_passed` keyword argument by writing an expression that will evaluate to `.true.` if and only if the test succeeds.
29
-
* Define the `diagnostics_string` keyword argument from character literal values interspersed with`string_t`constructor, all strung together by instances of the string concatenation operator `//`.
41
+
1. Writing an expression using Julienne's operators such as `.approximate.`, `.within`., and `.equalsExpected.`.
42
+
2. Invoking the `test_diagnosis_t` constructor and using Julienne's `string_t`constructors to form a diagnostic string.
30
43
31
44
`String_t` is a generic interface to various specific functions, each of which takes an argument of a different data type, kind, and rank (TKR) and defines a `string_t` result containing a charater representation of the function argument.
32
-
Please see Julienne's online [documentation](https:///berkeleylab.github.io/julienne/) for the currently supported TKR.
45
+
Please see Julienne's online [documentation] for the currently supported TKR.
33
46
Please submit an issue to request support for additional TKR or submit a pull request to contribute such support.
34
47
35
48
#### Forming diagnostic strings from array data
36
49
37
-
An especially useful pattern for forming diagnostic string involves invoking Julienne's `operator(.csv.)` to produce a string of comma-separated values (CSV) from a one-dimensional (1D) array.
50
+
An especially useful pattern for forming diagnostic strings involves invoking Julienne's `operator(.csv.)` to produce a string of comma-separated values (CSV) from a one-dimensional (1D) array.
38
51
For example, consider the following test description:
39
52
```fortran
40
-
test_description_t("returning the counting numbers up to 3", check_counting_numbers)
53
+
test_description_t("returning the counting numbers up to 3", check_counting_numbers)
41
54
```
42
55
and the following corresponding test:
43
56
```fortran
@@ -59,13 +72,8 @@ FAILS on returning the counting numbers up to 3
59
72
```
60
73
To support a common array notation, Julienne also supports bracketing strings.
61
74
62
-
**Exercise 1:** Make `check_counting_numbers` more robust by testing the equivalence of `expected_array` and `actual_array` only if the array sizes match and by treating a size-mismatch as a test failure.
63
-
64
-
**Exercise 2:** Revise `check_counting_numbers` by defining CSV strings `expected_string` and `actual_string`_before_ invoking `test_diagnostics_t`.
65
-
Bracket the CSV strings in the `diagnostics_string` keyword argument by invoking `bracket` type-bound procedure, e.g., `expected_string%bracket()`.
66
-
67
-
Scalar Diagnosis Function
68
-
-------------------------
75
+
Diagnosis Functions
76
+
-------------------
69
77
The Unified Modeling Language ([UML](https://wikipedia.org/Unified_modeling_langauge)) class diagram below depicts the class relationships involved in making the above example work:
70
78
71
79
```mermaid
@@ -104,33 +112,10 @@ class test_diagnosis_t{
104
112
}
105
113
```
106
114
107
-
Vector Diagnosis Function
108
-
-------------------------
109
-
The UML class diagram below depicts the class relationships involved when test function performs multiple checks and defines a result containing an array of corresponding `test_diagnosis_t` objects:
When a test is known to cause a compile-time or runtime crash in a specific scenario, e.g., with a specific compiler or compiler version, including that test will prevent the test suite from building or running to completion.
133
-
It can be useful to skip a test with the problematic compiler but to report the test as skipped and account for the skipped tests in the tally of test results..
118
+
It can be useful to skip a test with the problematic compiler but to report the test as skipped and account for the skipped tests in the tally of test results.
134
119
For this purpose, the `test_description_t` and `vector_test_description_t` constructor functions have optional second arguments `diagnosis_function` and `vector_diagnosis_function`, respectively.
135
120
When these arguments are not `present`, the `test_t`'s `report` procedure will report the test as skipped but will terminate normally as long as the sum of the passing tests and skipped tests equals the total number of tests.
136
121
One might accomplish this with the compiler's predefined preprocessor macro:
@@ -175,3 +160,32 @@ class string_t{
175
160
base_name(string_t) string_t
176
161
}
177
162
```
163
+
164
+
Deprecated: Vector Diagnosis Function
165
+
-------------------------------------
166
+
Julienne's `vector_diagnosis_function_i` abstract interface and the corresponding `vector_test_description_t` type were developed before Julienne's `operator(.all.)` and `operator(.and.)`.
167
+
Because the operators replace the interface and type with simpler functionality, it is likely that a future release will remove the `vector_*` entities.
168
+
169
+
The Unified Modeling Language ([UML]) class diagram below depicts the class relationships involved when test function performs multiple checks and defines a result containing an array of corresponding `test_diagnosis_t` objects:
0 commit comments