Add host unit test infrastructure with GoogleTest

.github/workflows/ci.yml

@@ -58,9 +58,31 @@ jobs:
       - name: Build
         run: cmake --build build
 
+  test:
+    name: Unit tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libavahi-compat-libdnssd-dev
+
+      - name: Configure CMake
+        # BUILD_EXAMPLES=OFF so the test job configures only sendspin + tests and skips the
+        # example-only FetchContent deps (e.g. FTXUI).
+        run: cmake -B build-tests -DSENDSPIN_BUILD_TESTS=ON -DENABLE_SANITIZERS=ON -DBUILD_EXAMPLES=OFF .
+
+      - name: Build tests
+        run: cmake --build build-tests --target sendspin_tests
+
+      - name: Run tests
+        run: ctest --test-dir build-tests --output-on-failure
+
   ci:
     name: CI
-    needs: [pre-commit, lint, build]
+    needs: [pre-commit, lint, build, test]
     runs-on: ubuntu-latest
     if: always()
     steps:

CMakeLists.txt

@@ -184,4 +184,11 @@ else()
         message(STATUS "Skipping sendspin-cpp examples (BUILD_EXAMPLES=OFF)")
     endif()
 
+    # Unit tests (host only, opt-in via -DSENDSPIN_BUILD_TESTS=ON)
+    option(SENDSPIN_BUILD_TESTS "Build host unit tests" OFF)
+    if(SENDSPIN_BUILD_TESTS)
+        enable_testing()
+        add_subdirectory(tests)
+    endif()
+
 endif()

tests/CMakeLists.txt

@@ -0,0 +1,47 @@
+# Host unit tests for sendspin-cpp
+#
+# Enabled from the top-level CMakeLists.txt with -DSENDSPIN_BUILD_TESTS=ON.
+# Tests link against the `sendspin` static library and exercise its internal
+# logic directly (white-box: they include private headers from src/).
+
+include(FetchContent)
+
+# GoogleTest — fetched the same way as the library's other dependencies.
+FetchContent_Declare(
+    googletest
+    GIT_REPOSITORY https://github.com/google/googletest.git
+    GIT_TAG        v1.15.2
+    GIT_SHALLOW    TRUE
+)
+set(INSTALL_GTEST OFF CACHE BOOL "" FORCE)
+set(BUILD_GMOCK OFF CACHE BOOL "" FORCE)  # only gtest_main is used; skip building gmock
+FetchContent_MakeAvailable(googletest)
+
+# One executable aggregating every test_*.cpp file. gtest_discover_tests still
+# registers the individual TEST() cases with CTest so failures are reported per case.
+add_executable(sendspin_tests
+    test_audio_stream_info.cpp
+    test_time_filter.cpp
+    test_protocol.cpp
+)
+
+# Reach the library's private headers (protocol_messages.h, time_filter.h, ...).
+# The public include/ dir and ArduinoJson propagate transitively from `sendspin`.
+# Use CMAKE_CURRENT_SOURCE_DIR (not CMAKE_SOURCE_DIR) so the path stays correct even
+# if sendspin is ever added as a subdirectory of a larger superproject.
+target_include_directories(sendspin_tests PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../src)
+
+target_link_libraries(sendspin_tests PRIVATE sendspin GTest::gtest_main)
+
+target_compile_features(sendspin_tests PRIVATE cxx_std_20)
+target_compile_options(sendspin_tests PRIVATE -Wall -Wextra)
+
+# Match the library's sanitizer configuration so the test binary is instrumented too.
+if(ENABLE_SANITIZERS)
+    target_compile_options(sendspin_tests PRIVATE
+        -fsanitize=address,undefined -fno-omit-frame-pointer)
+    target_link_options(sendspin_tests PRIVATE -fsanitize=address,undefined)
+endif()
+
+include(GoogleTest)
+gtest_discover_tests(sendspin_tests)

tests/README.md

@@ -0,0 +1,48 @@
+# Unit tests
+
+Host-only unit tests for the cross-platform logic in `src/`. They link against the `sendspin`
+static library and run on macOS/Linux with [GoogleTest](https://github.com/google/googletest)
+(fetched automatically via CMake `FetchContent`).
+
+## Running
+
+From the repository root:
+
+```bash
+cmake -B build-tests -DSENDSPIN_BUILD_TESTS=ON .
+cmake --build build-tests --target sendspin_tests
+ctest --test-dir build-tests --output-on-failure
+```
+
+Run the test binary directly to use GoogleTest filters:
+
+```bash
+./build-tests/tests/sendspin_tests --gtest_filter='Protocol.*'
+```
+
+## Running under sanitizers
+
+Add `-DENABLE_SANITIZERS=ON` to build with AddressSanitizer and UndefinedBehaviorSanitizer. This
+is what CI runs, and it is the recommended way to exercise the pointer-heavy code (the message
+formatter, JSON parsing):
+
+```bash
+cmake -B build-tests-asan -DSENDSPIN_BUILD_TESTS=ON -DENABLE_SANITIZERS=ON .
+cmake --build build-tests-asan --target sendspin_tests
+ctest --test-dir build-tests-asan --output-on-failure
+```
+
+## Layout
+
+Each `test_*.cpp` file covers one unit of cross-platform logic:
+
+- `test_protocol.cpp` — wire-protocol parsing/formatting: enum round-trips, message dispatch, the
+  tri-state metadata/color deltas, and the hand-rolled `client/time` formatter checked against
+  `snprintf`.
+- `test_time_filter.cpp` — `SendspinTimeFilter` invariants (monotonic-timestamp rejection, reset,
+  offset round-trip, convergence).
+- `test_audio_stream_info.cpp` — byte/frame/sample/duration conversions.
+
+These are white-box tests: they include private headers from `src/`, so the test target adds
+`src/` to its include path. To add a new test file, create `test_<unit>.cpp` here and add it to
+the `add_executable(sendspin_tests ...)` list in `tests/CMakeLists.txt`.

tests/test_audio_stream_info.cpp

@@ -0,0 +1,83 @@
+// Copyright 2026 Sendspin Contributors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Unit tests for AudioStreamInfo's byte/frame/sample/duration conversions. These are exact
+// integer arithmetic, so the assertions are exact: a wrong conversion silently corrupts
+// buffering and A/V sync, which is exactly the kind of bug worth pinning down.
+
+#include "audio_stream_info.h"
+#include <gtest/gtest.h>
+
+using sendspin::AudioStreamInfo;
+
+// 16-bit stereo at 44.1 kHz: 2 bytes/sample, 4 bytes/frame.
+TEST(AudioStreamInfo, CdQualityConversions) {
+    const AudioStreamInfo info(16, 2, 44100);
+
+    EXPECT_EQ(info.get_bits_per_sample(), 16);
+    EXPECT_EQ(info.get_channels(), 2);
+    EXPECT_EQ(info.get_sample_rate(), 44100u);
+
+    EXPECT_EQ(info.frames_to_bytes(100), 400u);
+    EXPECT_EQ(info.bytes_to_frames(400), 100u);
+    EXPECT_EQ(info.samples_to_bytes(8), 16u);
+
+    // 1 second of audio == sample_rate frames == sample_rate * frame_size bytes.
+    EXPECT_EQ(info.ms_to_bytes(1000), 176400u);
+    EXPECT_EQ(info.bytes_to_ms(176400), 1000u);
+
+    EXPECT_EQ(info.frames_to_microseconds(441), 10000);   // 10 ms
+    EXPECT_EQ(info.frames_to_microseconds(2205), 50000);  // 50 ms
+}
+
+// frames_to_microseconds() widens to 64-bit internally, so it stays exact well past the point
+// where a 32-bit (frames * 1e6) product overflows (~4295 frames, ~97 ms at 44.1 kHz). These
+// counts would have silently wrapped under the old implementation.
+TEST(AudioStreamInfo, FramesToMicrosecondsNoOverflowAtLargeCounts) {
+    const AudioStreamInfo info(16, 2, 44100);
+
+    EXPECT_EQ(info.frames_to_microseconds(44100), 1000000);      // exactly 1 s
+    EXPECT_EQ(info.frames_to_microseconds(88200), 2000000);      // exactly 2 s
+    EXPECT_EQ(info.frames_to_microseconds(4410000), 100000000);  // 100 s, far past the old wrap
+}
+
+// 16-bit mono at 8 kHz, the library's default-ish low-rate case.
+TEST(AudioStreamInfo, MonoLowRateConversions) {
+    const AudioStreamInfo info(16, 1, 8000);
+
+    EXPECT_EQ(info.ms_to_bytes(125), 2000u);  // 125 ms * 16000 B/s
+    EXPECT_EQ(info.bytes_to_ms(2000), 125u);
+    EXPECT_EQ(info.frames_to_microseconds(800), 100000);  // 100 ms
+}
+
+// Bit depths that are not multiples of 8 round up to whole bytes per sample.
+TEST(AudioStreamInfo, BytesPerSampleRounding) {
+    EXPECT_EQ(AudioStreamInfo(8, 1, 48000).frames_to_bytes(10), 10u);   // 1 byte/sample
+    EXPECT_EQ(AudioStreamInfo(24, 2, 48000).frames_to_bytes(10), 60u);  // 3 bytes/sample, stereo
+}
+
+TEST(AudioStreamInfo, Equality) {
+    const AudioStreamInfo a(16, 2, 44100);
+    EXPECT_TRUE(a == AudioStreamInfo(16, 2, 44100));
+    EXPECT_TRUE(a != AudioStreamInfo(16, 2, 48000));  // sample rate differs
+    EXPECT_TRUE(a != AudioStreamInfo(24, 2, 44100));  // bit depth differs
+    EXPECT_TRUE(a != AudioStreamInfo(16, 1, 44100));  // channel count differs
+}
+
+TEST(AudioStreamInfo, DefaultConstruction) {
+    const AudioStreamInfo info;
+    EXPECT_EQ(info.get_bits_per_sample(), 16);
+    EXPECT_EQ(info.get_channels(), 1);
+    EXPECT_EQ(info.get_sample_rate(), sendspin::DEFAULT_SAMPLE_RATE_HZ);
+}