refactor(test): consolidate shared test utilities into common/test_helpers.h

Extract all shared test utilities (PRNG, dataset generation, groundtruth
computation, checksum functions, integration and regression test runners)
from test_regression.h and test_builder_integration.h into a single
common/test_helpers.h header. Delete the two old headers and update all
test source files and CMakeLists.txt to use the new shared include path.
- Create cpp/test/src/common/test_helpers.h with all consolidated utilities
- Delete cpp/test/src/regression/test_regression.h
- Delete cpp/test/src/integration/test_builder_integration.h
- Update test_builder_integration.cpp, test_distances_integration.cpp,
  and test_builder_regression.cpp to include common/test_helpers.h
- Update CMakeLists.txt macros to use src/ as include directory
- Build and verify: all 3 CTest targets pass, all 15 regression tests pass

Author: Neiko2002

cpp/test/CMakeLists.txt

@@ -13,7 +13,7 @@ macro(add_deglib_test name source)
     add_executable(${name} ${TEST_MAIN} ${source})
     target_include_directories(${name} PRIVATE ${DEGLIB_INCLUDE})
     target_include_directories(${name} PRIVATE ${GTEST_INCLUDE})
-    target_include_directories(${name} PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src/regression)
+    target_include_directories(${name} PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src)
     target_sources(${name} PRIVATE ${GTEST_SOURCE})
     target_link_libraries(${name} PRIVATE compile-options)
     set_target_properties(${name} PROPERTIES INTERMEDIATE_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/obj/${name}")
@@ -25,7 +25,7 @@ macro(add_deglib_integration_test name source)
     add_executable(${name} ${TEST_MAIN} ${source})
     target_include_directories(${name} PRIVATE ${DEGLIB_INCLUDE})
     target_include_directories(${name} PRIVATE ${GTEST_INCLUDE})
-    target_include_directories(${name} PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src/integration)
+    target_include_directories(${name} PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src)
     target_sources(${name} PRIVATE ${GTEST_SOURCE})
     target_link_libraries(${name} PRIVATE compile-options)
     set_target_properties(${name} PROPERTIES INTERMEDIATE_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/obj/${name}")
@@ -38,7 +38,7 @@ macro(add_deglib_test_no_ctest name source)
     add_executable(${name} ${TEST_MAIN} ${source})
     target_include_directories(${name} PRIVATE ${DEGLIB_INCLUDE})
     target_include_directories(${name} PRIVATE ${GTEST_INCLUDE})
-    target_include_directories(${name} PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src/regression)
+    target_include_directories(${name} PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src)
     target_sources(${name} PRIVATE ${GTEST_SOURCE})
     target_link_libraries(${name} PRIVATE compile-options)
     set_target_properties(${name} PROPERTIES INTERMEDIATE_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/obj/${name}")
@@ -49,14 +49,10 @@ add_deglib_test(test_cpu_features src/test_cpu_features.cpp)
 
 # Integration tests (fast, recall-only, registered with CTest for CI)
 add_deglib_integration_test(test_builder_integration src/integration/test_builder_integration.cpp)
-add_deglib_integration_test(test_distance_integration src/integration/test_distance_integration.cpp)
+add_deglib_integration_test(test_distances_integration src/integration/test_distances_integration.cpp)
 
 # Regression tests (100k vectors, performance benchmarking — built but NOT registered with CTest)
-add_deglib_test_no_ctest(test_dataset_determinism src/regression/test_dataset_determinism.cpp)
-add_deglib_test_no_ctest(test_l2_regression src/regression/metric/test_l2_regression.cpp)
-add_deglib_test_no_ctest(test_innerproduct_regression src/regression/metric/test_innerproduct_regression.cpp)
-add_deglib_test_no_ctest(test_l2_uint8_regression src/regression/metric/test_l2_uint8_regression.cpp)
-add_deglib_test_no_ctest(test_l2_builder_regression src/regression/builder/test_l2_builder_regression.cpp)
+add_deglib_test_no_ctest(test_builder_regression src/regression/test_builder_regression.cpp)
 
 # Meta target to build all regression tests
-add_custom_target(test_regression DEPENDS test_dataset_determinism test_l2_regression test_innerproduct_regression test_l2_uint8_regression test_l2_builder_regression)
+add_custom_target(test_regression DEPENDS test_builder_regression)

…c/integration/test_builder_integration.h cpp/test/src/common/test_helpers.hcpp/test/src/integration/test_builder_integration.h renamed to cpp/test/src/common/test_helpers.h cpp/test/src/integration/test_builder_integration.h renamed to cpp/test/src/common/test_helpers.h

@@ -14,13 +14,11 @@
 #include <vector>
 
 // ============================================================================
-// Integration Test Shared Utilities
+// Shared Test Utilities
 // ============================================================================
-// Centralized helpers for fast integration tests operating on 10,000 base
-// vectors and 100 queries.  These are adapted from test_regression.h but
-// strip out QPS / build-time assertions so that only recall correctness is
-// verified.  All dataset generation uses the same bit-exact 32-bit PRNG so
-// results are reproducible across platforms.
+// Centralized helpers for both integration and regression tests.
+// All dataset generation uses a bit-exact 32-bit PRNG so results are
+// reproducible across MSVC, GCC, and Clang on all CPU architectures.
 // ============================================================================
 
 // ---------------------------------------------------------------------------
@@ -35,10 +33,20 @@ inline static uint32_t deglib_prng_next(uint32_t& state) {
     return state = x;
 }
 
+inline static float deglib_prng_float(uint32_t& state, float min_val, float max_val) {
+    uint32_t val = deglib_prng_next(state) >> 8; // 24-bit integer
+    float u = static_cast<float>(val) / 16777215.0f;
+    float range = max_val - min_val;
+    return min_val + u * range;
+}
+
 // ---------------------------------------------------------------------------
 // Dataset generation (float, for L2 and InnerProduct)
 // ---------------------------------------------------------------------------
 
+// Generate cross-platform deterministic clustered dataset (Gaussian Mixture with fixed seed)
+// Uses pure 32-bit integer arithmetic and exact integer-to-float conversion to guarantee
+// 100% bit-exact float vectors across MSVC, GCC, and Clang on all CPU architectures.
 inline static void generate_synthetic_clustered_dataset(size_t count, size_t dim, std::vector<float>& base,
                                                  std::vector<float>& query, size_t query_count,
                                                  size_t num_clusters = 20)
@@ -85,6 +93,7 @@ inline static void generate_synthetic_clustered_dataset(size_t count, size_t dim
 // Dataset generation (uint8, for L2_Uint8)
 // ---------------------------------------------------------------------------
 
+// Generate cross-platform deterministic uint8 clustered dataset
 inline static void generate_synthetic_clustered_dataset_uint8(size_t count, size_t dim, std::vector<uint8_t>& base,
                                                        std::vector<uint8_t>& query, size_t query_count,
                                                        size_t num_clusters = 20)
@@ -133,6 +142,8 @@ inline static void generate_synthetic_clustered_dataset_uint8(size_t count, size
 // Groundtruth computation
 // ---------------------------------------------------------------------------
 
+// Compute exact brute-force groundtruth for top-K neighbors using a custom distance evaluator.
+// Works for both float and uint8_t element types via the ElemType template parameter.
 template <typename ElemType, typename DistFunc>
 inline static std::vector<std::vector<uint32_t>> compute_groundtruth_custom(const std::vector<ElemType>& base, size_t base_count,
                                                                        const std::vector<ElemType>& query, size_t query_count,
@@ -163,6 +174,9 @@ inline static std::vector<std::vector<uint32_t>> compute_groundtruth_custom(cons
     return gt;
 }
 
+// Compute exact brute-force L2 groundtruth for top-K neighbors.
+// Uses the scalar L2Float::compare() implementation from deglib to ensure
+// the ground-truth distances match the actual distance computation exactly.
 inline static std::vector<std::vector<uint32_t>> compute_groundtruth_l2(const std::vector<float>& base, size_t base_count,
                                                                  const std::vector<float>& query, size_t query_count,
                                                                  size_t dim, uint32_t k)
@@ -174,6 +188,9 @@ inline static std::vector<std::vector<uint32_t>> compute_groundtruth_l2(const st
                                       });
 }
 
+// Compute exact brute-force InnerProduct groundtruth for top-K neighbors (distance = 1 - dot_product).
+// Uses the scalar InnerProductFloat::compare() implementation from deglib to ensure
+// the ground-truth distances match the actual distance computation exactly.
 inline static std::vector<std::vector<uint32_t>> compute_groundtruth_innerproduct(const std::vector<float>& base, size_t base_count,
                                                                              const std::vector<float>& query, size_t query_count,
                                                                              size_t dim, uint32_t k)
@@ -185,6 +202,9 @@ inline static std::vector<std::vector<uint32_t>> compute_groundtruth_innerproduc
                                       });
 }
 
+// Compute exact brute-force L2 groundtruth for uint8 vectors.
+// Uses the scalar L2Uint8::compare() from deglib to ensure the ground-truth
+// distances match the actual distance computation exactly.
 inline static std::vector<std::vector<uint32_t>> compute_groundtruth_l2_uint8(const std::vector<uint8_t>& base, size_t base_count,
                                                                           const std::vector<uint8_t>& query, size_t query_count,
                                                                           size_t dim, uint32_t k)
@@ -240,7 +260,7 @@ inline static void check_distance_recall(const char* name, const std::vector<Ele
 }
 
 // ---------------------------------------------------------------------------
-// Graph builder + search recall runner (no QPS / build-time checks)
+// Graph builder + search recall runner (integration: no QPS / build-time checks)
 // ---------------------------------------------------------------------------
 
 inline static void run_integration_test(const char* name, deglib::Metric metric, double min_recall,
@@ -426,10 +446,137 @@ inline static void run_builder_integration_test(const char* name, deglib::Metric
     }
 }
 
+// ---------------------------------------------------------------------------
+// Universal regression benchmark runner function for any metric
+// num_runs: number of measured search runs (averaged for QPS/recall).
+//           Higher values extend the total search measurement window, reducing QPS noise.
+// optimization_target: controls the graph build strategy (LowLID, HighLID, StreamingData).
+// ---------------------------------------------------------------------------
+
+inline static void run_regression_test(const char* name, deglib::Metric metric, double min_qps, double max_build_secs,
+                                double min_recall, const void* base_data,
+                                const void* query_data, size_t base_count, size_t query_count,
+                                size_t dim, const std::vector<std::vector<uint32_t>>& gt_data,
+                                std::optional<deglib::DistanceVariant> dist_variant = std::nullopt,
+                                size_t num_runs = 5,
+                                deglib::builder::OptimizationTarget optimization_target = deglib::builder::OptimizationTarget::LowLID)
+{
+    const uint32_t search_k = 10;
+    const float search_eps = 0.05f;
+
+    const uint32_t edges_per_vertex = 32;
+    const uint8_t extend_k = static_cast<uint8_t>(edges_per_vertex);
+    const float extend_eps = 0.1f;
+    const uint8_t improve_k = 0;
+    const float improve_eps = 0.0f;
+    const uint8_t max_path_length = 5;
+    const uint32_t swap_tries = 0;
+    const uint32_t additional_swap_tries = 0;
+    const uint32_t thread_count = 1;
+
+    // Compute byte size per vector based on metric type (0x10 flag indicates 8-bit integer)
+    const size_t feature_bytes = (static_cast<int>(metric) & 0x10) ? dim * sizeof(uint8_t) : dim * sizeof(float);
+
+    // Build DEG Graph using the specified metric feature space
+    const deglib::FloatSpace feature_space = dist_variant.has_value()
+        ? deglib::FloatSpace(dim, metric, dist_variant.value())
+        : deglib::FloatSpace(dim, metric);
+
+    deglib::graph::SizeBoundedGraph graph(static_cast<uint32_t>(base_count), edges_per_vertex,
+                                          std::move(feature_space));
+
+    std::mt19937 rng(1337);
+    deglib::builder::EvenRegularGraphBuilder builder(graph, rng, optimization_target, extend_k, extend_eps, improve_k,
+                                                     improve_eps, max_path_length, swap_tries, additional_swap_tries);
+    builder.setThreadCount(thread_count);
+    auto t_build_start = std::chrono::high_resolution_clock::now();
+
+    const std::byte* base_bytes = reinterpret_cast<const std::byte*>(base_data);
+    for (size_t i = 0; i < base_count; ++i)
+    {
+        const std::byte* ptr = base_bytes + i * feature_bytes;
+        std::vector<std::byte> feat_vec(ptr, ptr + feature_bytes);
+        builder.addEntry(static_cast<uint32_t>(i), std::move(feat_vec));
+    }
+
+    auto build_callback = [](deglib::builder::BuilderStatus& status) {};
+    builder.build(build_callback);
+
+    auto t_build_end = std::chrono::high_resolution_clock::now();
+    double build_secs = std::chrono::duration<double>(t_build_end - t_build_start).count();
+
+    auto entry_vertex_indices = graph.getEntryVertexIndices();
+    const std::byte* query_bytes = reinterpret_cast<const std::byte*>(query_data);
+
+    auto run_search = [&]() -> std::pair<double, double>
+    {
+        size_t total_correct = 0;
+        auto t_search_start = std::chrono::high_resolution_clock::now();
+
+        for (size_t q = 0; q < query_count; ++q)
+        {
+            const std::byte* q_ptr = query_bytes + q * feature_bytes;
+            auto result = graph.search(entry_vertex_indices, q_ptr, search_eps, search_k, nullptr, 0);
+
+            std::unordered_set<uint32_t> gt_set;
+            if (!gt_data.empty() && q < gt_data.size())
+            {
+                size_t eval_k = std::min(static_cast<size_t>(search_k), gt_data[q].size());
+                for (size_t i = 0; i < eval_k; ++i)
+                {
+                    gt_set.insert(gt_data[q][i]);
+                }
+            }
+
+            while (!result.empty())
+            {
+                auto top_item = result.top();
+                result.pop();
+                uint32_t ext_label = graph.getExternalLabel(top_item.getInternalIndex());
+                if (gt_set.count(ext_label))
+                {
+                    total_correct++;
+                }
+            }
+        }
+
+        auto t_search_end = std::chrono::high_resolution_clock::now();
+        double search_secs = std::chrono::duration<double>(t_search_end - t_search_start).count();
+        double qps = static_cast<double>(query_count) / search_secs;
+        double recall = static_cast<double>(total_correct) / static_cast<double>(query_count * search_k);
+        return {qps, recall};
+    };
+
+    // Warm-up run
+    run_search();
+
+    // Measured average runs — higher num_runs extends the measurement window,
+    // reducing QPS noise from OS jitter and CPU power-state transitions.
+    double total_qps = 0.0;
+    double total_recall = 0.0;
+    for (size_t r = 0; r < num_runs; ++r)
+    {
+        auto [qps, recall] = run_search();
+        total_qps += qps;
+        total_recall += recall;
+    }
+    double qps = total_qps / num_runs;
+    double recall = total_recall / num_runs;
+
+    std::cout << "[" << name << "] build_secs=" << build_secs << "  qps=" << qps << "  recall=" << recall << std::endl;
+
+    EXPECT_GE(recall + 1e-5, min_recall);
+    if (std::getenv("SKIP_PERFORMANCE_TESTS") == nullptr) {
+        EXPECT_GT(qps, min_qps);
+        EXPECT_LE(build_secs, max_build_secs);
+    }
+}
+
 // ---------------------------------------------------------------------------
 // Checksums for dataset determinism verification
 // ---------------------------------------------------------------------------
 
+// FNV-1a 64-bit hash for byte buffers
 inline static uint64_t fnv1a_64(const void* data, size_t bytes) {
     const uint8_t* ptr = static_cast<const uint8_t*>(data);
     uint64_t hash = 14695981039346656037ULL;
@@ -440,10 +587,12 @@ inline static uint64_t fnv1a_64(const void* data, size_t bytes) {
     return hash;
 }
 
+// Compute checksum of a float vector
 inline static uint64_t float_vector_checksum(const std::vector<float>& vec) {
     return fnv1a_64(vec.data(), vec.size() * sizeof(float));
 }
 
+// Compute checksum of groundtruth 2D vector
 inline static uint64_t groundtruth_checksum(const std::vector<std::vector<uint32_t>>& gt) {
     uint64_t hash = 14695981039346656037ULL;
     for (const auto& row : gt) {

cpp/test/src/integration/test_builder_integration.cpp

@@ -1,4 +1,4 @@
-#include "test_builder_integration.h"
+#include "common/test_helpers.h"
 
 // ============================================================================
 // Builder & Search Recall Integration Tests

…ntegration/test_distance_integration.cpp …tegration/test_distances_integration.cppcpp/test/src/integration/test_distance_integration.cpp renamed to cpp/test/src/integration/test_distances_integration.cpp cpp/test/src/integration/test_distance_integration.cpp renamed to cpp/test/src/integration/test_distances_integration.cpp

@@ -1,4 +1,4 @@
-#include "test_builder_integration.h"
+#include "common/test_helpers.h"
 
 // ============================================================================
 // Distance Calculation Recall Integration Tests