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 foamut command (v2.0.0)

foamut is built with bashly, making it easy to extend and customize.

Source code structure

The source code is organized under src/:

• src/bashly.yml - CLI configuration and help text
• src/initialize.sh - Pre-execution setup
• src/root_command.sh - Main orchestration logic
• src/lib/*.sh - Helper functions for compilation, test execution, and cleanup

To modify behavior, edit the relevant file and regenerate:

./generate.sh

Environment variables

Control foamut behavior with these environment variables:

Variable	Default	Description
CATCH_TIMEOUT	60	Test timeout in seconds
FOAM_FOAMUT_TESTS	-	External tests directory (auto-symlinked)
FOAM_FOAMUT	auto	Path to foamUT repository root
FOAM_FOAMUT_NPROCS	2	Number of processors for parallel standalone tests

Getting around compilation problems with multiple OpenFOAM versions

To support all OpenFOAM forks, foamut creates dummy libraries for missing dependencies. For example, Foam-Extend doesn't have libPstream.so (functionality is in libfoam.so).

This is handled in src/lib/create_dummy_libs.sh:

dummyLibChecks="Pstream dynamicFvMesh"

Dummy libraries are created if missing and cleaned up after tests finish.

Where OpenFOAM cases are run

Test cases are run off-tree to minimize interaction:

• Location: /tmp/foamUtCases (defined in src/root_command.sh)
• Cases are copied here before each test run
• Cleaned up automatically after tests complete

To change the location, edit caseRun variable in src/root_command.sh:

caseRun=/your/custom/path
./generate.sh

Set a timeout for tests

In CI environments, timeouts prevent hanging processes:

# Set custom timeout (default: 60 seconds)
export CATCH_TIMEOUT=120

# Run tests
./foamut

Timeout is automatically disabled when using --test-prefix (for debugging). Use --force-timeout to keep it:

./foamut --test-prefix "gdb --args" --force-timeout

The test driver

The test driver works with any OpenFOAM fork by letting each fork handle OpenFOAM initialization on its own.

Command-line argument separation

The test driver splits arguments using --- as separator:

/path/to/testDriver [Catch2_params] --- [OpenFOAM_params]

Example - run on cavity case in parallel:

mpirun -np 4 ./testDriver -s --- -case /dev/shm/cavity -parallel

Note: With foamut, you don't need to worry about this - it's handled automatically!

Custom test drivers

Use --test-driver to provide your own test driver source:

./foamut --test-driver /path/to/myTestDriver.C

Your custom driver will be compiled and used instead of the default one.

Exception handling

The test driver instructs FatalError to throw exceptions instead of aborting:

Foam::FatalError.throwExceptions();

This allows Catch2 to catch errors and continue with other tests. You won't see "FOAM FATAL ERROR" messages on the console anymore.

To see full error messages in a specific test:

TEST_CASE("My test", "[serial]") {
    // Disable exception throwing for this test only
    Foam::FatalError.dontThrowExceptions();

    // Your test code that might trigger FatalError
    // ...
}

Standalone mode support

In standalone mode (--standalone), the test driver sets:

argsPtr = nullptr;
timePtr = nullptr;

Your tests should check for this:

TEST_CASE("Standalone test", "[serial]") {
    if (timePtr == nullptr) {
        // Running in standalone mode - no OpenFOAM case
        // Test pure C++ logic without mesh/time objects
    }
}

Integration with text editors

Moved to its own Wiki page