Play around

Things to play around with

As a user of the framework, you have complete freedom in altering its behavior. This document describes some common ways to do so.

The Alltest script

Getting around compilation problems when attempting to compile with multiple OpenFOAM versions

To be able to compile your code with all OpenFOAM forks, all versions need to have the libraries you're linking the test driver to. This is not the case; because, at least, Foam-Extend doesn't have a libPstream.so. Its parallel functionality is still in libfoam.so.

The solution to this to have a list of vital libraries which need to be present on each system. If there is no such library file, we create a dummy one and remove it when all the tests are finished. This is translated into dummyLibChecks Bash variable near the start of the Alltest script.

This is a decent solution; because without that dummy file, you wouldn't be able to compile your tests. But it should never be actually loaded. If it gets accidentally loaded, the compiler will complain that it's too short.

Where to run the OpenFOAM cases

The test OpenFOAM cases are actually run off-tree, to minimize interaction between test cases. A case gets copied to /dev/shm by default (that's a path on your RAM, not on your hard disk). If you want to change this behavior, change the caseRun variable near the start of Alltest to some other part.

Set a TimeOut for tests

In CI environments, timing-out commands that might hang is crucial. Alltest makes sure your processes get killed even if they get into some sort of an infinite loop, or just hang for whatever reason.

The default timeout is 15 secs, and you can change it by simply setting the CATCH_TIMEOUT environment variable.

The proposed test driver

The example test driver is written in a way that works with any OpenFOAM fork, simply by letting the fork handle the OpenFOAM initialization parts on its own.

The idea is to split options passed to Catch and options passed to the OpenFOAM side with a ---:

/path/to/testDriver [Catch2_params] --- [OpenFOAM_params]
# Example: run the driver on the cavity case in parallel
# -s is passed to catch to make it show details on successful tests too
mpirun -np 4 ./testDriver -s --- -case /dev/shm/cavity -parallel

You don't have to stick to this design; you can always ship your own test driver with your tests and replace this file when needed.

Another thing the proposed test driver does is it instructs FoamFatal to throw exceptions so Catch2 can trap them and continue execution of other test cases even if one fails. The effect of this setting is that you won't see the "Foam FATAL ERROR" messages on the console anymore.

To reverse this effect, you can add FatalError.dontThrowExceptions(); at the start of the failing test to see the full error message as you normally do with solvers.

Integration with text editors

Moved to its own Wiki page