Add Testing Framework

CMakeLists.txt

@@ -16,4 +16,12 @@ add_subdirectory(sample)
 
 add_library(rabitq_headers INTERFACE)
 
-target_include_directories(rabitq_headers INTERFACE ${PROJECT_SOURCE_DIR}/include)
+target_include_directories(rabitq_headers INTERFACE ${PROJECT_SOURCE_DIR}/include)
+
+# Testing
+option(RABITQ_BUILD_TESTS "Build tests" OFF)
+
+if(RABITQ_BUILD_TESTS)
+    enable_testing()
+    add_subdirectory(tests)
+endif()

tests/.gitignore

@@ -0,0 +1 @@
+/googletest

tests/CMakeLists.txt

@@ -0,0 +1,51 @@
+cmake_minimum_required(VERSION 3.10)
+
+# Fetch Google Test
+include(FetchContent)
+FetchContent_Declare(
+  googletest
+  GIT_REPOSITORY https://github.com/google/googletest.git
+  GIT_TAG        v1.14.0
+)
+set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
+FetchContent_MakeAvailable(googletest)
+
+enable_testing()
+
+# Include directories
+include_directories(${PROJECT_SOURCE_DIR}/include)
+include_directories(${CMAKE_CURRENT_SOURCE_DIR}/common)
+
+# Compiler flags
+set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wall -Wextra")
+
+# Automatically register all tests under unit and <other folders> folders
+file(GLOB_RECURSE UNIT_TESTS ${CMAKE_CURRENT_SOURCE_DIR}/unit/*_test.cpp)
+file(GLOB_RECURSE INTEG_TESTS ${CMAKE_CURRENT_SOURCE_DIR}/integration/*_test.cpp)
+file(GLOB_RECURSE COMMON_SRCS ${CMAKE_CURRENT_SOURCE_DIR}/common/*.cpp)
+
+# add executables
+add_executable(rabitq_tests
+    ${COMMON_SRCS}
+    ${UNIT_TESTS}
+    ${INTEG_TESTS}
+)
+
+# Link google test and rabitqlib headers
+target_link_libraries(rabitq_tests
+    gtest
+    gtest_main           
+    rabitq_headers
+    pthread
+)
+
+# Discover tests for CTest
+include(GoogleTest)
+gtest_discover_tests(rabitq_tests)
+
+# Message to verify files are found
+message(STATUS "Discovered test files:")
+foreach(TEST_SRC ${ALL_TEST_SRCS})
+    file(RELATIVE_PATH REL_PATH ${CMAKE_CURRENT_SOURCE_DIR} ${TEST_SRC})
+    message(STATUS "  - ${REL_PATH}")
+endforeach()

tests/README.md

@@ -0,0 +1,74 @@
+# RaBitQ Testing Framework
+
+This directory contains the comprehensive testing framework for the RaBitQ library 
+
+## Prerequisites
+
+- CMake 3.10 or higher
+- C++17 compatible compiler (GCC, Clang, or MSVC)
+- Google Test (automatically downloaded via CMake FetchContent)
+
+### Installing CMake 
+
+For macos
+```bash
+brew install cmake
+```
+
+for (Ubuntu/Debian)
+
+```bash
+sudo apt-get update
+sudo apt-get install cmake
+```
+
+## Building and Running Tests
+
+### Quick Start
+
+From the project root directory:
+
+```bash
+# Create build directory
+mkdir build bin
+cd build
+
+# Configure with tests enabled (tests are OFF by default)
+cmake .. -DRABITQ_BUILD_TESTS=ON
+
+# Build the tests
+make -j$(nproc)
+
+# Run all tests
+./tests/rabitq_tests
+
+# Or use CTest for detailed output
+ctest --output-on-failure
+```
+
+### Building without Tests
+
+By default, tests are **not built**. If you want to build only the library:
+
+```bash
+cmake ..
+```
+
+
+## Test Structure
+
+```
+tests/
+├── CMakeLists.txt              # Automatic test discovery & suite configuration
+├── main.cpp                    # Test runner entry point
+├── common/                     # Test utilities and helpers
+│   ├── test_data.hpp           # Test data generation utilities
+│   ├── test_data.cpp
+│   └── test_helpers.hpp       # Custom assertions and helpers
+├── unit/                       # Unit tests (auto-discovered)
+├── integration/                # Integration tests (auto-discovered)
+└── benchmark/                  # Performance benchmarks (to be added)
+```
+
+## Test Coverage
+

tests/common/test_data.cpp

@@ -0,0 +1,103 @@
+#include "test_data.hpp"
+#include <cmath>
+#include <algorithm>
+
+namespace rabitq_test {
+
+std::vector<float> TestDataGenerator::GenerateRandomVector(
+    size_t dim,
+    float min,
+    float max,
+    unsigned int seed
+) {
+    std::mt19937 rng(seed);
+    std::uniform_real_distribution<float> dist(min, max);
+
+    std::vector<float> vec(dim);
+    for (size_t i = 0; i < dim; ++i) {
+        vec[i] = dist(rng);
+    }
+    return vec;
+}
+
+std::vector<float> TestDataGenerator::GenerateNormalizedVector(
+    size_t dim,
+    unsigned int seed
+) {
+    auto vec = GenerateRandomVector(dim, -1.0f, 1.0f, seed);
+
+    // Calculate L2 norm
+    float norm = 0.0f;
+    for (float val : vec) {
+        norm += val * val;
+    }
+    norm = std::sqrt(norm);
+
+    // Normalize
+    if (norm > 1e-10f) {
+        for (float& val : vec) {
+            val /= norm;
+        }
+    }
+
+    return vec;
+}
+
+std::vector<std::vector<float>> TestDataGenerator::GenerateRandomVectors(
+    size_t num_vectors,
+    size_t dim,
+    float min,
+    float max,
+    unsigned int seed
+) {
+    std::vector<std::vector<float>> vectors;
+    vectors.reserve(num_vectors);
+
+    for (size_t i = 0; i < num_vectors; ++i) {
+        vectors.push_back(GenerateRandomVector(dim, min, max, seed + i));
+    }
+
+    return vectors;
+}
+
+std::vector<float> TestDataGenerator::GenerateGaussianVector(
+    size_t dim,
+    float mean,
+    float stddev,
+    unsigned int seed
+) {
+    std::mt19937 rng(seed);
+    std::normal_distribution<float> dist(mean, stddev);
+
+    std::vector<float> vec(dim);
+    for (size_t i = 0; i < dim; ++i) {
+        vec[i] = dist(rng);
+    }
+    return vec;
+}
+
+std::vector<float> TestDataGenerator::GenerateSimpleVector(size_t dim) {
+    std::vector<float> vec(dim);
+    for (size_t i = 0; i < dim; ++i) {
+        vec[i] = static_cast<float>(i % 10) / 10.0f;
+    }
+    return vec;
+}
+
+std::vector<float> TestDataGenerator::GenerateZeroVector(size_t dim) {
+    return std::vector<float>(dim, 0.0f);
+}
+
+std::vector<float> TestDataGenerator::GenerateOnesVector(size_t dim) {
+    return std::vector<float>(dim, 1.0f);
+}
+
+std::vector<float> TestDataGenerator::GenerateIncrementalVector(size_t dim) {
+    std::vector<float> vec(dim);
+    for (size_t i = 0; i < dim; ++i) {
+        vec[i] = static_cast<float>(i);
+    }
+    return vec;
+}
+
+} // namespace rabitq_test

tests/common/test_data.hpp

@@ -0,0 +1,58 @@
+#ifndef RABITQ_TEST_DATA_HPP
+#define RABITQ_TEST_DATA_HPP
+
+#include <vector>
+#include <random>
+#include <cstddef>
+
+namespace rabitq_test {
+
+class TestDataGenerator {
+public:
+    // Generate random float vector with values in [min, max]
+    static std::vector<float> GenerateRandomVector(
+        size_t dim,
+        float min = -1.0f,
+        float max = 1.0f,
+        unsigned int seed = 42
+    );
+
+    // Generate random normalized vector (unit length)
+    static std::vector<float> GenerateNormalizedVector(
+        size_t dim,
+        unsigned int seed = 42
+    );
+
+    // Generate multiple random vectors
+    static std::vector<std::vector<float>> GenerateRandomVectors(
+        size_t num_vectors,
+        size_t dim,
+        float min = -1.0f,
+        float max = 1.0f,
+        unsigned int seed = 42
+    );
+
+    // Generate Gaussian distributed vector
+    static std::vector<float> GenerateGaussianVector(
+        size_t dim,
+        float mean = 0.0f,
+        float stddev = 1.0f,
+        unsigned int seed = 42
+    );
+
+    // Generate a simple test vector with known values
+    static std::vector<float> GenerateSimpleVector(size_t dim);
+
+    // Generate zero vector
+    static std::vector<float> GenerateZeroVector(size_t dim);
+
+    // Generate vector with all ones
+    static std::vector<float> GenerateOnesVector(size_t dim);
+
+    // Generate vector with incremental values [0, 1, 2, 3, ...]
+    static std::vector<float> GenerateIncrementalVector(size_t dim);
+};
+
+} // namespace rabitq_test
+
+#endif // RABITQ_TEST_DATA_HPP

tests/common/test_helpers.hpp

@@ -0,0 +1,84 @@
+#ifndef RABITQ_TEST_HELPERS_HPP
+#define RABITQ_TEST_HELPERS_HPP
+
+#include <cmath>
+#include <vector>
+#include <random>
+#include <gtest/gtest.h>
+
+namespace rabitq_test {
+
+// Floating point comparison with tolerance
+inline bool FloatNearlyEqual(float a, float b, float epsilon = 1e-5f) {
+    return std::abs(a - b) < epsilon;
+}
+
+inline bool DoubleNearlyEqual(double a, double b, double epsilon = 1e-10) {
+    return std::abs(a - b) < epsilon;
+}
+
+// Vector comparison
+inline bool VectorsNearlyEqual(const float* a, const float* b, size_t size, float epsilon = 1e-5f) {
+    for (size_t i = 0; i < size; ++i) {
+        if (!FloatNearlyEqual(a[i], b[i], epsilon)) {
+            return false;
+        }
+    }
+    return true;
+}
+
+// Calculate relative error
+inline float RelativeError(float actual, float expected) {
+    if (std::abs(expected) < 1e-10f) {
+        return std::abs(actual - expected);
+    }
+    return std::abs((actual - expected) / expected);
+}
+
+// Calculate mean squared error
+inline float MeanSquaredError(const float* a, const float* b, size_t size) {
+    float mse = 0.0f;
+    for (size_t i = 0; i < size; ++i) {
+        float diff = a[i] - b[i];
+        mse += diff * diff;
+    }
+    return mse / size;
+}
+
+// Calculate dot product
+inline float DotProduct(const float* a, const float* b, size_t size) {
+    float result = 0.0f;
+    for (size_t i = 0; i < size; ++i) {
+        result += a[i] * b[i];
+    }
+    return result;
+}
+
+// Calculate L2 distance
+inline float L2Distance(const float* a, const float* b, size_t size) {
+    float sum = 0.0f;
+    for (size_t i = 0; i < size; ++i) {
+        float diff = a[i] - b[i];
+        sum += diff * diff;
+    }
+    return std::sqrt(sum);
+}
+
+// Custom assertion macros
+#define ASSERT_FLOAT_NEARLY_EQUAL(a, b, epsilon) \
+    ASSERT_TRUE(rabitq_test::FloatNearlyEqual(a, b, epsilon)) \
+        << "Expected: " << a << " to be nearly equal to " << b \
+        << " (epsilon: " << epsilon << "), but difference was " << std::abs(a - b)
+
+#define EXPECT_FLOAT_NEARLY_EQUAL(a, b, epsilon) \
+    EXPECT_TRUE(rabitq_test::FloatNearlyEqual(a, b, epsilon)) \
+        << "Expected: " << a << " to be nearly equal to " << b \
+        << " (epsilon: " << epsilon << "), but difference was " << std::abs(a - b)
+
+#define ASSERT_VECTORS_NEARLY_EQUAL(a, b, size, epsilon) \
+    ASSERT_TRUE(rabitq_test::VectorsNearlyEqual(a, b, size, epsilon)) \
+        << "Vectors are not nearly equal (epsilon: " << epsilon << ")"
+
+} // namespace rabitq_test
+
+#endif // RABITQ_TEST_HELPERS_HPP