1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
|
# Writing New Tests
A thorough test suite is an important part of any project. It is equally
important that the test suite be used frequently, and that the results
of the test suite be easy to evaluate. In MPICH, the tests are designed
to be run by scripts that are run nightly, including scripts that
analyze the results to identify success and failure. For a test to work
within this process, it must do the following:
1. Have the process with rank zero in `MPI_COMM_WORLD` print nothing
except the line (note the leading space; the "No" starts in the
second column. The `^` and `$` characters are only there to
show where the line begins and ends, respectively. This is to
simplify Fortran tests, where the first column is sometimes
interpreted and a blank is required for greatest portability).
```
^ No Errors$
```
if the test is successful; no other process should print anything at
all.
2. Print anything else on failure (from any process).
3. Run without any command line arguments or special environment
variables.
In addition, to make it easier to diagnose any failures, a good test
will write detailed diagnostic information about any failure.
To aid in writing tests, there are a set of utility routines in
`test/util/mtest.c` (with corresponding versions for Fortran and C++).
These routines include ones to print the required output, check the
command line and environment for options to produce more verbose output,
and routines to print additional information when so requested. They
also provide a variety of MPI communicators and datatypes to ensure that
tests are carried out with more than `MPI_COMM_WORLD` and basic MPI
datatypes. Until there is better documentation, the best way to use
these is to look at an existing test that makes use of these routines,
such as `test/mpi/pt2pt/sendrecv1.c` or `test/mpi/pt2pt/rqstatus.c`.
To avoid unnecessary complications for users, any test should either use
the routines in `mtest.c` to check for command line options or
environment variables, implement the same options for specifying verbose
output. Specifically, support the environment variables
- `MPITEST_DEBUG` - If set to a numeric value, turn on debugging output (the value may
be used to control the amount of output; for many tests, any
positive value should generate debugging output).
- `MPITEST_VERBOSE` - If set to a numeric value, turn on verbose output. As with
`MPITEST_DEBUG`, the value determines the amount of output.
Test programs may of course implement additional options, but for
consistency should use these where they make sense. If you want
additional features, such as command line control over verbose output,
consider enhancing the routines in `mtest.c`.
Once a test has been written, add it to the MPICH test suite by placing
it in the appropriate subdirectory of `mpich/test/mpi`. For example, a
test of `MPI_Send` should go into `mpich/test/mpi/pt2pt`. Tests in C++
or Fortran should go into their subdirectories (e.g., a Fortran test of
`MPI_Send` should go into `mpich/test/mpi/f77/pt2pt`). Add the test to
the Makefile.sm and to the testlist file in that directory. The format
of the entries in the testlist file are
```
executable-name number-of-processes
```
E.g., for a test name `sendtest` to be run on five processes, add the
line
```
sendtest 5
```
There are additional special options in the testlist file that can be
used to modify the way the test is conducted, but most tests should not
require those features.
For the `Makefile.sm` file, the most common entry that is needed is of
the form
```
mytest_SOURCES = mytest.c
```
for a program with name `mytest.c`. For more complicated needs, such as
examples that require multiple files, look for similar examples in the
`Makefile.sm` files in the test directories.
## Other Suggestions when Writing Tests
In the past, some tests have been written with code like this:
```
...
err = MPI_Send( ... );
if (err != MPI_SUCCESS) {
... report error;
}
```
However, if the code does not also include
```
MPI_Comm_set_errhandler( MPI_COMM_WORLD, MPI_ERRORS_RETURN );
```
(and similar code for every communicator used), the code misleads the
reader into believing that the MPI routine will return with an error
code instead of abort. It is better to either not use the error return
(an abort of the code will be detected by the test harness) or set the
error handler to MPI_ERRORS_RETURN.
Another common mistake is to select among datatypes with the C switch
statement, as in
```
switch (type) {
case MPI_INT: ...
}
```
This works for MPICH but is not portable to all valid MPI
implementations because the MPI predefined datatypes are not required to
be compile-time constants. Instead of using a switch statement, you need
to use an if-else chain:
```
if (type == MPI_INT) { ...
} else if (type ...
```
|
