ENH: Add ForceOocAlgorithm flag to test both algorithm paths in in-core builds

DispatchAlgorithm now checks a static ForceOocAlgorithm() flag in addition
to array storage type. Tests use ForceOocAlgorithmGuard with Catch2 GENERATE
to exercise both BFS and CCL paths regardless of build configuration.

Signed-off-by: Joey Kleingers <[email protected]>

Author: joeykleingers

docs/AlgorithmDispatch.md

@@ -79,7 +79,7 @@ template <typename InCoreAlgo, typename OocAlgo, typename... ArgsT>
 Result<> DispatchAlgorithm(std::initializer_list<const IDataArray*> arrays, ArgsT&&... args);
 ```
 
-Checks whether any array in `arrays` uses OOC storage. If so, constructs `OocAlgo(args...)` and calls `operator()()`. Otherwise, constructs `InCoreAlgo(args...)` and calls `operator()()`.
+Checks whether any array in `arrays` uses OOC storage, or if the global `ForceOocAlgorithm()` flag is set. If either condition is true, constructs `OocAlgo(args...)` and calls `operator()()`. Otherwise, constructs `InCoreAlgo(args...)` and calls `operator()()`.
 
 **Requirements for algorithm classes:**
 
@@ -166,7 +166,48 @@ Filters/Algorithms/
 
 5. **Register new files**: Add the new algorithm names to the plugin's `AlgorithmList` in `CMakeLists.txt`.
 
-6. **Test both paths**: Run the filter's tests with both in-core and OOC configurations. Both must produce identical results.
+6. **Test both paths**: Use `ForceOocAlgorithmGuard` with Catch2 `GENERATE` to exercise both algorithm paths in every build configuration (see below).
+
+## Testing Both Algorithm Paths
+
+CI typically only builds the in-core configuration, so the OOC algorithm path would never be exercised without an explicit override. The `ForceOocAlgorithm()` flag and `ForceOocAlgorithmGuard` RAII class solve this.
+
+### ForceOocAlgorithm
+
+```cpp
+bool& ForceOocAlgorithm();
+```
+
+Returns a reference to a static bool. When set to `true`, `DispatchAlgorithm` always selects the OOC algorithm class regardless of whether the data arrays use chunked storage. Defaults to `false`.
+
+### ForceOocAlgorithmGuard
+
+```cpp
+class ForceOocAlgorithmGuard
+{
+public:
+  ForceOocAlgorithmGuard(bool force);
+  ~ForceOocAlgorithmGuard();
+  // non-copyable, non-movable
+};
+```
+
+RAII guard that sets `ForceOocAlgorithm()` on construction and restores the previous value on destruction. Use with Catch2 `GENERATE` to run each test case twice — once with the in-core algorithm and once with the OOC algorithm:
+
+```cpp
+#include "simplnx/Utilities/AlgorithmDispatch.hpp"
+
+TEST_CASE("MyFilter", "[Plugin][MyFilter]")
+{
+  UnitTest::LoadPlugins();
+  bool forceOocAlgo = GENERATE(false, true);
+  const nx::core::ForceOocAlgorithmGuard guard(forceOocAlgo);
+
+  // ... test body runs identically for both algorithm paths ...
+}
+```
+
+This ensures both code paths are tested in every build configuration (in-core and OOC). The OOC algorithm class works correctly on in-core `DataStore` data because the chunk API methods are no-ops for `DataStore` (1 chunk spanning the full volume).
 
 ## Performance Expectations
 

src/Plugins/SimplnxCore/test/IdentifySampleTest.cpp

@@ -7,6 +7,7 @@
 #include "simplnx/DataStructure/IDataArray.hpp"
 #include "simplnx/Parameters/ChoicesParameter.hpp"
 #include "simplnx/UnitTest/UnitTestCommon.hpp"
+#include "simplnx/Utilities/AlgorithmDispatch.hpp"
 
 #include <catch2/catch.hpp>
 
@@ -22,6 +23,8 @@ const DataPath k_ExemplarArrayPath = Constants::k_DataContainerPath.createChildP
 TEST_CASE("SimplnxCore::IdentifySampleFilter", "[SimplnxCore][IdentifySampleFilter]")
 {
   UnitTest::LoadPlugins();
+  bool forceOocAlgo = GENERATE(false, true);
+  const nx::core::ForceOocAlgorithmGuard guard(forceOocAlgo);
   const UnitTest::PreferencesSentinel prefsSentinel("Zarr", 100, true);
 
   const nx::core::UnitTest::TestFileSentinel testDataSentinel(nx::core::unit_test::k_TestFilesDir, "identify_sample.tar.gz", "identify_sample", true, true);
@@ -82,6 +85,8 @@ TEST_CASE("SimplnxCore::IdentifySampleFilter", "[SimplnxCore][IdentifySampleFilt
 TEST_CASE("SimplnxCore::IdentifySampleFilter: Benchmark 200x200x200", "[SimplnxCore][IdentifySampleFilter][Benchmark]")
 {
   UnitTest::LoadPlugins();
+  bool forceOocAlgo = GENERATE(false, true);
+  const nx::core::ForceOocAlgorithmGuard guard(forceOocAlgo);
   // 200*200 * 1 byte = 40000 bytes per Z-slice for uint8 mask
   const UnitTest::PreferencesSentinel prefsSentinel("Zarr", 40000, true);
 

src/simplnx/Utilities/AlgorithmDispatch.hpp

@@ -44,20 +44,71 @@ inline bool AnyOutOfCore(std::initializer_list<const IDataArray*> arrays)
   return false;
 }
 
+/**
+ * @brief Returns a reference to the global flag that forces DispatchAlgorithm
+ *        to always select the out-of-core algorithm, regardless of storage type.
+ *
+ * This is primarily used in unit tests to exercise the OOC algorithm path
+ * even when data is stored in-core. Use ForceOocAlgorithmGuard for RAII-safe
+ * toggling in tests.
+ *
+ * @return Reference to the static force flag
+ */
+inline bool& ForceOocAlgorithm()
+{
+  static bool s_force = false;
+  return s_force;
+}
+
+/**
+ * @brief RAII guard that sets ForceOocAlgorithm() on construction and
+ *        restores the previous value on destruction.
+ *
+ * Usage in tests with Catch2 GENERATE:
+ * @code
+ *   bool forceOoc = GENERATE(false, true);
+ *   const nx::core::ForceOocAlgorithmGuard guard(forceOoc);
+ *   // ... test body runs with both algorithm paths ...
+ * @endcode
+ */
+class ForceOocAlgorithmGuard
+{
+public:
+  ForceOocAlgorithmGuard(bool force)
+  : m_Original(ForceOocAlgorithm())
+  {
+    ForceOocAlgorithm() = force;
+  }
+
+  ~ForceOocAlgorithmGuard()
+  {
+    ForceOocAlgorithm() = m_Original;
+  }
+
+  ForceOocAlgorithmGuard(const ForceOocAlgorithmGuard&) = delete;
+  ForceOocAlgorithmGuard(ForceOocAlgorithmGuard&&) = delete;
+  ForceOocAlgorithmGuard& operator=(const ForceOocAlgorithmGuard&) = delete;
+  ForceOocAlgorithmGuard& operator=(ForceOocAlgorithmGuard&&) = delete;
+
+private:
+  bool m_Original;
+};
+
 /**
  * @brief Dispatches between two algorithm classes based on whether any of the
- *        given data arrays use out-of-core (chunked) storage.
+ *        given data arrays use out-of-core (chunked) storage, or if the global
+ *        ForceOocAlgorithm() flag is set.
  *
  * Some algorithms that perform well on in-memory data (e.g. BFS flood fill with
  * random access) become extremely slow when data is stored in disk-backed chunks,
  * because each random access may trigger a chunk load/evict cycle. In these cases,
  * a different algorithm (e.g. scanline CCL with sequential chunk access) can be
  * orders of magnitude faster for OOC data.
  *
- * This function checks the storage type of the given arrays and instantiates the
- * appropriate algorithm class. If *any* array is out-of-core, the OOC algorithm
- * is selected. Callers should pass all input and output arrays the filter operates
- * on. Both algorithm classes must:
+ * This function checks the storage type of the given arrays and the global force
+ * flag. If *any* array is out-of-core or ForceOocAlgorithm() is true, the OOC
+ * algorithm is selected. Callers should pass all input and output arrays the
+ * filter operates on. Both algorithm classes must:
  *   - Be constructible from the same ArgsT... parameter pack
  *   - Provide operator()() returning Result<>
  *
@@ -71,7 +122,7 @@ inline bool AnyOutOfCore(std::initializer_list<const IDataArray*> arrays)
 template <typename InCoreAlgo, typename OocAlgo, typename... ArgsT>
 Result<> DispatchAlgorithm(std::initializer_list<const IDataArray*> arrays, ArgsT&&... args)
 {
-  if(AnyOutOfCore(arrays))
+  if(AnyOutOfCore(arrays) || ForceOocAlgorithm())
   {
     return OocAlgo(std::forward<ArgsT>(args)...)();
   }