Add Test

Add Test

Add tests following Fluca's golden-output testing conventions.

Required Input

Ask the user for:

1. Module — test subdirectory (e.g., fd, cavity_flow)
2. Mode — new file (ex<N>.c) or new cases in an existing file
3. Description — what the test exercises
4. Test cases — suffix names and command-line args for each case

Mode A: New Test File

1. Determine next file number

ls fluca/tests/<module>/ex*.c

2. Generate source

#include <flucasys.h>
/* Module headers as needed */

static const char help[] = "<Description>\n"
                           "Options:\n"
                           "  -<opt> <type>  : <desc>\n";

int main(int argc, char **argv)
{
  /* Declarations at block top */

  PetscCall(FlucaInitialize(&argc, &argv, NULL, help));

  /* 1. Create DM(s)
     2. Create and configure objects under test
     3. SetFromOptions
     4. SetUp
     5. Exercise and print results
     6. Destroy in reverse creation order */

  PetscCall(FlucaFinalize());
}

/*TEST

  test:
    suffix: <name>
    nsize: 1
    args: <args>

TEST*/

3. Register in CMakeLists.txt

Add the file to TEST_SRCS in fluca/tests/<module>/CMakeLists.txt.

For a new module, also create its CMakeLists.txt and add add_subdirectory(<module>) to fluca/tests/CMakeLists.txt.

4. Build, capture, verify

cmake --build build
./build/fluca/tests/<module>/ex<N> <args> > fluca/tests/<module>/output/ex<N>_<suffix>.out
cmake build && ctest --test-dir build -R "ex<N>" --output-on-failure

Mode B: Add Cases to Existing File

1. Read the existing file
2. Append test: entries to the /*TEST*/ block (before TEST*/)
3. Build, capture golden output, re-configure, verify

Suffix Naming

• Use snake_case, descriptive of the specific scenario being tested
• Keep concise but unambiguous — a suffix should identify the case without reading the args
• Study existing suffixes in the same ex*.c file and follow their convention

Examples from the codebase: first_deriv, second_deriv_left_bc_dirichlet, all_second_deriv_all_loc_down, vanleer, cavity_flow_2d

Checklist

• Test validates an internal algorithm directly — no SNES or TS solve required
• Inputs are constructed analytically; expected outputs are known without running a solver
• /*TEST*/ block has suffix and args
• Source added to TEST_SRCS in CMakeLists.txt
• Golden output captured from actual run (never hand-written)
• All new tests pass via ctest

Converted and distributed by TomeVault — claim your Tome and manage your conversions.