flap_test_utils

Utilities for FLAP test programs: assertions, output capture and self re-invocation.

Assertions end the program with error stop 1 on failure, so a failed check always gives a non-zero exit status.

Output capture: pass the unit returned by capture_open as usage_lun/error_lun/version_lun to cli%init, then read_back the text written to it.

Self re-invocation: reinvoke runs the calling program again in a child process with FLAP_TEST_CASE set, so the child knows (via child_case) which scenario to run. This is how a test exercises environment variables, standard input, exit statuses and the paths that end the program (--help, --version). It requires a POSIX sh and env.

Source: src/tests/flap_test_utils.F90

Dependencies

Contents

• assert_equal
• assert
• assert_contains
• assert_equal_character
• assert_equal_logical
• assert_equal_I4P
• assert_equal_R8P
• assert_equal_I4P_1d
• assert_equal_R8P_1d
• capture_open
• capture_close
• write_file
• delete_file
• run_command
• reinvoke
• fail
• read_back
• read_file
• scratch_file
• child_case
• read_all
• integer_to_string
• real_to_string
• logical_to_string
• reals_match

Variables

Name	Type	Attributes	Description
CASE_ENV	character(len=*)	parameter	Environment variable selecting the child scenario.

Interfaces

assert_equal

Assert that an actual value equals the expected one.

Module procedures: assert_equal_character, assert_equal_logical, assert_equal_I4P, assert_equal_R8P, assert_equal_I4P_1d, assert_equal_R8P_1d

Subroutines

assert

Assert that a condition holds.

subroutine assert(condition, message)

Arguments

Name	Type	Intent	Attributes	Description
condition	logical	in		Condition to check.
message	character(len=*)	in		Description of the check.

Call graph

assert_contains

Assert that a text contains a substring.

subroutine assert_contains(text, substring, message)

Arguments

Name	Type	Intent	Attributes	Description
text	character(len=*)	in		Text to search.
substring	character(len=*)	in		Substring expected in the text.
message	character(len=*)	in		Description of the check.

Call graph

assert_equal_character

Assert that two strings are equal (Fortran comparison: trailing blanks are not significant).

subroutine assert_equal_character(actual, expected, message)

Arguments

Name	Type	Intent	Attributes	Description
actual	character(len=*)	in		Actual value.
expected	character(len=*)	in		Expected value.
message	character(len=*)	in		Description of the check.

Call graph

assert_equal_logical

Assert that two logicals are equal.

subroutine assert_equal_logical(actual, expected, message)

Arguments

Name	Type	Intent	Attributes	Description
actual	logical	in		Actual value.
expected	logical	in		Expected value.
message	character(len=*)	in		Description of the check.

Call graph

assert_equal_I4P

Assert that two integers are equal.

subroutine assert_equal_I4P(actual, expected, message)

Arguments

Name	Type	Intent	Attributes	Description
actual	integer(kind=I4P)	in		Actual value.
expected	integer(kind=I4P)	in		Expected value.
message	character(len=*)	in		Description of the check.

Call graph

assert_equal_R8P

Assert that two reals are equal, exactly or within an absolute tolerance.

subroutine assert_equal_R8P(actual, expected, message, tol)

Arguments

Name	Type	Intent	Attributes	Description
actual	real(kind=R8P)	in		Actual value.
expected	real(kind=R8P)	in		Expected value.
message	character(len=*)	in		Description of the check.
tol	real(kind=R8P)	in	optional	Absolute tolerance (default: exact comparison).

Call graph

assert_equal_I4P_1d

Assert that two integer arrays are equal.

subroutine assert_equal_I4P_1d(actual, expected, message)

Arguments

Name	Type	Intent	Attributes	Description
actual	integer(kind=I4P)	in		Actual values.
expected	integer(kind=I4P)	in		Expected values.
message	character(len=*)	in		Description of the check.

Call graph

assert_equal_R8P_1d

Assert that two real arrays are equal, exactly or within an absolute tolerance.

subroutine assert_equal_R8P_1d(actual, expected, message, tol)

Arguments

Name	Type	Intent	Attributes	Description
actual	real(kind=R8P)	in		Actual values.
expected	real(kind=R8P)	in		Expected values.
message	character(len=*)	in		Description of the check.
tol	real(kind=R8P)	in	optional	Absolute tolerance (default: exact comparison).

Call graph

capture_open

Open a scratch unit to capture output.

subroutine capture_open(lun)

Arguments

Name	Type	Intent	Attributes	Description
lun	integer(kind=I4P)	out		Capture unit.

Call graph

capture_close

Close (and delete) a capture unit.

subroutine capture_close(lun)

Arguments

Name	Type	Intent	Attributes	Description
lun	integer(kind=I4P)	in		Capture unit.

write_file

Write a text to a new file byte by byte (no newline added), replacing any existing one.

subroutine write_file(path, text)

Arguments

Name	Type	Intent	Attributes	Description
path	character(len=*)	in		File path.
text	character(len=*)	in		Text to write, with its own new_line characters.

Call graph

delete_file

Delete a file.

subroutine delete_file(path)

Arguments

Name	Type	Intent	Attributes	Description
path	character(len=*)	in		File path.

Call graph

run_command

Run a shell command (by sh) and return its exit status and its standard output and error, merged.

subroutine run_command(cmd, exitstat, out)

Arguments

Name	Type	Intent	Attributes	Description
cmd	character(len=*)	in		Shell command.
exitstat	integer(kind=I4P)	out		Exit status of the command.
out	character(len=:)	out	allocatable	Standard output and error of the command.

Call graph

reinvoke

Run the calling program again as a child process executing scenario case (read by the child with child_case).

The command line is env [env] FLAP_TEST_CASE=case 'self' [args] < stdin > out 2> err, run by sh: args and env are passed verbatim, so shell quoting is the caller's responsibility. env takes env operands with options first, e.g. '-u OLD NEW=value' unsets OLD and sets NEW. Without stdin the child reads from /dev/null.

subroutine reinvoke(case, exitstat, out, err, args, env, stdin)

Arguments

Name	Type	Intent	Attributes	Description
case	integer(kind=I4P)	in		Scenario run by the child.
exitstat	integer(kind=I4P)	out		Exit status of the child.
out	character(len=:)	out	allocatable	Standard output of the child.
err	character(len=:)	out	allocatable	Standard error of the child.
args	character(len=*)	in	optional	Command line arguments for the child.
env	character(len=*)	in	optional	Extra env operands, options first: '-u OLD NEW=value'.
stdin	character(len=*)	in	optional	Standard input for the child.

Call graph

fail

Report a failed check and end the program with a non-zero exit status.

subroutine fail(message)

Arguments

Name	Type	Intent	Attributes	Description
message	character(len=*)	in		Failure description.

Call graph

Functions

read_back

Return the text written to a capture unit so far, then empty the unit: the next capture starts from scratch.

Returns: character(len=:)

function read_back(lun) result(text)

Arguments

Name	Type	Intent	Attributes	Description
lun	integer(kind=I4P)	in		Capture unit.

Call graph

read_file

Return the whole content of a text file.

Returns: character(len=:)

function read_file(path) result(text)

Arguments

Name	Type	Intent	Attributes	Description
path	character(len=*)	in		File path.

Call graph

scratch_file

Path of a scratch file next to the running executable (a build directory, never the source tree).

Returns: character(len=:)

function scratch_file(name) result(path)

Arguments

Name	Type	Intent	Attributes	Description
name	character(len=*)	in		File name suffix.

Call graph

child_case

Return the scenario requested by reinvoke, or 0 when the program was not re-invoked.

Returns: integer(kind=I4P)

function child_case() result(case)

Call graph

read_all

Read a formatted unit from its current position to the end; lines of any length are supported.

Returns: character(len=:)

function read_all(lun) result(text)

Arguments

Name	Type	Intent	Attributes	Description
lun	integer(kind=I4P)	in		Unit to read.

Call graph

integer_to_string

Convert an integer to a string without blanks.

Attributes: pure

Returns: character(len=:)

function integer_to_string(n) result(string)

Arguments

Name	Type	Intent	Attributes	Description
n	integer(kind=I4P)	in		Integer to convert.

Call graph

real_to_string

Convert a real to a string in scientific notation, with enough digits to tell neighbouring values apart.

Attributes: pure

Returns: character(len=:)

function real_to_string(x) result(string)

Arguments

Name	Type	Intent	Attributes	Description
x	real(kind=R8P)	in		Real to convert.

Call graph

logical_to_string

Convert a logical to '.true.' or '.false.'.

Attributes: pure

Returns: character(len=:)

function logical_to_string(l) result(string)

Arguments

Name	Type	Intent	Attributes	Description
l	logical	in		Logical to convert.

Call graph

reals_match

Compare two reals, exactly or within an absolute tolerance.

Attributes: pure

Returns: logical

function reals_match(actual, expected, tol) result(match)

Arguments

Name	Type	Intent	Attributes	Description
actual	real(kind=R8P)	in		Actual value.
expected	real(kind=R8P)	in		Expected value.
tol	real(kind=R8P)	in	optional	Absolute tolerance (default: exact comparison).

Call graph