From a9adfe3b0ce51db41b9c286e7c7ba23fdf8ff01f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?B=C3=A1lint=20Aradi?= Date: Tue, 12 Nov 2024 22:10:21 +0100 Subject: [PATCH] Add some more user documentation --- README.rst | 9 +++-- example/README.rst | 46 ++++++++++++++++++++++ example/coarray-fpp/test_simple_fpp.F90 | 8 ++++ example/coarray-fypp/test_simple_fypp.fypp | 9 +++++ example/coarray/test_simple.f90 | 10 ++++- example/mpi-fpp/test_simple_fpp.F90 | 4 ++ example/mpi-fypp/test_simple_fypp.fypp | 3 ++ example/mpi/test_simple.f90 | 4 ++ example/serial/test_fixtured.f90 | 8 ++-- example/serial/test_simple.f90 | 9 +++-- example/serial/testapp.f90 | 3 ++ 11 files changed, 102 insertions(+), 11 deletions(-) create mode 100644 example/README.rst diff --git a/README.rst b/README.rst index ecb75e0..66fe5b7 100644 --- a/README.rst +++ b/README.rst @@ -11,15 +11,18 @@ solutions. Fortuno provides: +- serial unit testing, + +- parallel unit testing for MPI- and coarray-parallel projects, + - simple unit tests, - fixtured tests, - parametrized tests, -- serial unit testing, - -- parallel unit testing for MPI- and coarray-parallel projects, and +- automatic test registration (in combination with the `Fypp-preprocessor + `_), and - integration with the `fpm `_, `CMake `_ and `Meson `_ build systems. diff --git a/example/README.rst b/example/README.rst new file mode 100644 index 0000000..575084e --- /dev/null +++ b/example/README.rst @@ -0,0 +1,46 @@ +**************** +Fortuno examples +**************** + +Documented examples demonstrating the usage of the Fortuno unit testing +framework for various test scenarios. + +**Serial unit tests** + +- `serial `_: Unit tests in pure Fortran. + +- `serial-fpp `_: Unit tests utilizing fpp-style macros (which are + natively understood by basically all Fortran compilers). Allows for + automatically added file and line information when reporting failure. + +- `serial-fypp `_: Unit tests utilizing Fypp macros (helpful if + your project uses the Fypp-preprocessor). Allows for automatic test + registration as well as for automatic file and line information when reporting + failure. + + +**MPI-parallel unit tests** + +- `mpi `_: Unit tests in pure Fortran. + +- `mpi-fpp `_: Unit tests utilizing fpp-style macros (which are + natively understood by basically all Fortran compilers). Allows for + automatically added file and line information when reporting failure. + +- `mpi-fypp `_: Unit tests utilizing Fypp macros (helpful if your + project uses the Fypp-preprocessor). Allows for automatic test registration as + well as for automatic file and line information when reporting failure. + + +**Coarray-parallel unit tests** + +- `coarray `_: Unit tests in pure Fortran. + +- `coarray-fpp `_: Unit tests utilizing fpp-style macros (which are + natively understood by basically all Fortran compilers). Allows for + automatically added file and line information when reporting failure. + +- `coarray-fypp `_: Unit tests utilizing Fypp macros (helpful if + your project uses the Fypp-preprocessor). Allows for automatic test + registration as well as for automatic file and line information when reporting + failure. diff --git a/example/coarray-fpp/test_simple_fpp.F90 b/example/coarray-fpp/test_simple_fpp.F90 index bf92d6f..c4da019 100644 --- a/example/coarray-fpp/test_simple_fpp.F90 +++ b/example/coarray-fpp/test_simple_fpp.F90 @@ -25,6 +25,10 @@ end function tests !> Broadcast test with collective communication + !! + !! Note: as coarray parallelism might be implemented via threads, coarray tests must be "pure" and + !! use the passed context object to signalize test events. + !! subroutine test_broadcast(ctx) class(context), intent(inout) :: ctx @@ -50,6 +54,10 @@ subroutine test_broadcast(ctx) end if ! THEN each rank must contain source rank's value + ! + ! Note: "CHECK()" and "CHECK_MSG()" calls are collective calls, all images must call them with + ! their local result synchronously. + ! CHECK_MSG(ctx, is_equal(buffer, sourceval), msg) end subroutine test_broadcast diff --git a/example/coarray-fypp/test_simple_fypp.fypp b/example/coarray-fypp/test_simple_fypp.fypp index 1adf679..9a2ecaa 100644 --- a/example/coarray-fypp/test_simple_fypp.fypp +++ b/example/coarray-fypp/test_simple_fypp.fypp @@ -15,6 +15,11 @@ contains !> Broadcast test with collective communication + !! + !! Note: as coarray parallelism might be implemented via threads, coarray tests must be "pure" and + !! use the passed context object to signalize test events. The Fypp macros automaticaly handle + !! this (using "ctx" as name for the context instance). + !! $:TEST("broadcast") integer, parameter :: sourceimg = 1, sourceval = 100, otherval = -1 integer :: buffer @@ -32,6 +37,10 @@ contains call broadcast(buffer, sourceimg) ! THEN each image must contain source image's value + ! + ! Note: CHECK() and ASSERT() calls are collective calls, all images must call them with their + ! local result synchronously. + ! @:CHECK(is_equal(buffer, sourceval), msg=msg) $:END_TEST() diff --git a/example/coarray/test_simple.f90 b/example/coarray/test_simple.f90 index 0220e29..6a44e35 100644 --- a/example/coarray/test_simple.f90 +++ b/example/coarray/test_simple.f90 @@ -22,7 +22,11 @@ function tests() end function tests - !> Broadcast test with collective communication + !> Broadcast test with collective communication. + !! + !! Note: as coarray parallelism might be implemented via threads, coarray tests must be "pure" and + !! use the passed context object to signalize test events. + !! subroutine test_broadcast(ctx) class(context), intent(inout) :: ctx @@ -48,6 +52,10 @@ subroutine test_broadcast(ctx) end if ! THEN each rank must contain source rank's value + ! + ! Note: check() calls are collective calls, all images must call it with their local result + ! synchronously. + ! call ctx%check(is_equal(buffer, sourceval), msg=msg) end subroutine test_broadcast diff --git a/example/mpi-fpp/test_simple_fpp.F90 b/example/mpi-fpp/test_simple_fpp.F90 index 78afb41..9a2f4e1 100644 --- a/example/mpi-fpp/test_simple_fpp.F90 +++ b/example/mpi-fpp/test_simple_fpp.F90 @@ -48,6 +48,10 @@ subroutine test_broadcast() end if ! THEN each rank must contain source rank's value + ! + ! Note: "CHECK()" and "CHECK_MSG()" calls are collective calls, all processes must call them + ! with their local result synchronously. + ! CHECK_MSG(is_equal(buffer, sourceval), msg) end subroutine test_broadcast diff --git a/example/mpi-fypp/test_simple_fypp.fypp b/example/mpi-fypp/test_simple_fypp.fypp index 5106436..3069c0f 100644 --- a/example/mpi-fypp/test_simple_fypp.fypp +++ b/example/mpi-fypp/test_simple_fypp.fypp @@ -64,6 +64,9 @@ contains ! ASSERT() causes the test code to return immediately, while CHECK() only logs the failure and ! continues. ! + ! Also note: CHECK() and ASSERT() calls are collective calls, all processes must call them with + ! their local result synchronously. + ! @:ASSERT(is_equal(buffer, sourceval), msg=msg) $:END_TEST() diff --git a/example/mpi/test_simple.f90 b/example/mpi/test_simple.f90 index a4996ef..6c003b5 100644 --- a/example/mpi/test_simple.f90 +++ b/example/mpi/test_simple.f90 @@ -46,6 +46,10 @@ subroutine test_broadcast() end if ! THEN each rank must contain source rank's value + ! + ! Note: check() calls are collective calls, all processes must call it with their local result + ! synchronously. + ! call check(is_equal(buffer, sourceval), msg=msg) end subroutine test_broadcast diff --git a/example/serial/test_fixtured.f90 b/example/serial/test_fixtured.f90 index 7a8d157..3669b35 100644 --- a/example/serial/test_fixtured.f90 +++ b/example/serial/test_fixtured.f90 @@ -5,9 +5,9 @@ !> Demo for realizing fixtured tests by overriding the run() method of the test_case object. module test_fixtured use mylib, only : factorial - use fortuno_serial, only : check => serial_check, is_equal, state_dict,& - & dict_item, suite => serial_suite_item, store_state => serial_store_state,& - & serial_case_base, test_item, test_list + use fortuno_serial, only : check => serial_check, is_equal, state_dict, dict_item,& + & suite => serial_suite_item, store_state => serial_store_state, serial_case_base,& + & test_item, test_list implicit none private @@ -17,7 +17,7 @@ module test_fixtured ! Fixtured test case creating a random number before running a test procedure. type, extends(serial_case_base) :: random_test_case - ! Test procedure to be called after fixture setup had finished. + ! Test procedure to be called after fixture setup had finished. procedure(test_recursion_down), pointer, nopass :: proc contains diff --git a/example/serial/test_simple.f90 b/example/serial/test_simple.f90 index 3ad1a92..eda19f6 100644 --- a/example/serial/test_simple.f90 +++ b/example/serial/test_simple.f90 @@ -21,7 +21,8 @@ function tests() tests = test_list([& ! Best practice is to create at least one suite with the name of the module and put the - ! tests in it, like below. You might further structure your test sets by nesting suites... + ! tests in it, like below. You might further structure your test sets by nesting further + ! suites into the top level one. suite("simple", test_list([& test("factorial_0", test_factorial_0),& test("factorial_1", test_factorial_1),& @@ -47,11 +48,13 @@ end subroutine test_factorial_1 ! Test: 2! = 2 (will fail due to the bug in the implementation of the factorial function) subroutine test_factorial_2() - ! Two failing checks, you should see info about both in the output + ! Both check will fail, you should see info about both in the output + ! The file and line information are provided manually. Check the examples in the fpp example + ! folders for automatic file name and line number generation. call check(is_equal(factorial(2), 2),& & msg="Test failed for demonstration purposes",& & file="test_simple.f90",& - & line=43) + & line=51) call check(factorial(2) == 2) end subroutine test_factorial_2 diff --git a/example/serial/testapp.f90 b/example/serial/testapp.f90 index 8839247..49f9979 100644 --- a/example/serial/testapp.f90 +++ b/example/serial/testapp.f90 @@ -11,6 +11,9 @@ program testapp use test_fixtured_suite, only : fixtured_suite_tests => tests implicit none + ! Creating and executing a command line app with the tests to be included. + ! Note: this function does not return but stops the code with the right exit code. + ! (0 on success, non-zero otherwise) call execute_serial_cmd_app(test_list([& simple_tests(),& parametrized_tests(),&