Skip to content

TESTING.md

Latest commit

 

History

History
273 lines (215 loc) · 9.43 KB

TESTING.md

File metadata and controls

273 lines (215 loc) · 9.43 KB
Raw

Testing Documentation

Overview

This project uses a comprehensive testing strategy with 118 unit tests across 11 test suites, achieving 92.31% line coverage and 95.96% region coverage.

Test Coverage Summary

File Lines Line Coverage Regions Region Coverage Branches Branch Coverage
vec2.hpp 30 100.00% 33 100.00% 10 100.00%
kdtree_boid.hpp 86 100.00% 66 100.00% 40 100.00%
flock_metrics.hpp 71 100.00% 42 100.00% 32 96.88%
prey.cpp 103 100.00% 64 100.00% 54 83.33%
predator.cpp 30 100.00% 19 100.00% 14 85.71%
simulation.hpp 81 100.00% 40 100.00% 20 90.00%
config.hpp 130 100.00% 65 92.31% 58 74.14%
boid.cpp 26 92.31% 26 96.15% 10 90.00%
experiment.hpp 57 85.96% 14 92.86% 6 100.00%
formation_tracker.hpp 24 70.83% 16 87.50% 6 100.00%
profiler.hpp 50 28.00% 10 30.00% 0 -
TOTAL 689 92.31% 396 95.96% 250 88.00%

Test Suites

Test Suite Tests Description
Vec2Test 23 2D vector math, toroidal distance/delta
BoidParamsTest 4 Parameter defaults and customization
BoidTest 18 Base boid behavior, update, wrapping
PreyTest 19 Separation, alignment, cohesion, flee behaviors
PredatorTest 9 Chase behavior, target selection
SimulationTest 15 World setup, stepping, force application
KDTreeBoidTest 14 Spatial indexing, toroidal neighbor queries
FlockMetricsTest 11 Polarization, cluster counting, formations
ConfigTest 3 YAML configuration loading
SweepConfigTest 2 Parameter sweep generation
ExperimentTest 2 Experiment runner and CSV output

Testing Tools & Techniques

Framework

  • Google Test (gtest) - C++ unit testing framework
    • EXPECT_DOUBLE_EQ for floating-point comparisons
    • EXPECT_GT, EXPECT_LT for relational assertions
    • EXPECT_TRUE/FALSE for boolean checks
    • Test fixtures for shared setup

Coverage Instrumentation

  • LLVM Coverage (llvm-cov, llvm-profdata)
    • Profile-guided instrumentation (-fprofile-instr-generate -fcoverage-mapping)
    • HTML report generation
    • Line, region, and branch coverage metrics

Build System

  • GNU Make with multiple targets: 
    make test       # Build and run all tests
make coverage   # Build with instrumentation, run tests, generate HTML report
make clean      # Remove all build artifacts

Automation

Makefile Targets

Target Command Description
test make test Compile and execute all 118 unit tests
coverage make coverage Run tests with LLVM coverage, generate HTML report
all make Build main simulation binary
run make run Build and run simulation
experiment make experiment Build experiment runner for batch simulations
clean make clean Remove build artifacts

Parallelization

make PARALLEL=1   # Enable OpenMP parallelization

Coverage Report Location

build/coverage/html/index.html

Test Categories

Unit Tests

  • Vector Math (test_vec2.cpp) - Arithmetic, normalization, distance calculations
  • Boid Behavior (test_boid.cpp, test_prey.cpp, test_predator.cpp) - Movement, steering forces
  • Spatial Queries (test_kdtree_boid.cpp) - KD-tree neighbor lookup with toroidal wrapping
  • Metrics (test_flock_metrics.cpp) - Polarization, cluster detection, formation tracking

Integration Tests

  • Simulation (test_simulation.cpp) - Full simulation stepping with predator-prey dynamics
  • Configuration (test_config.cpp) - YAML loading and parameter sweep generation
  • Experiment (test_experiment.cpp) - CSV output and metric recording

Running Tests

# Run all tests
make test

# Run specific test suite
./test_runner --gtest_filter="PreyTest.*"

# Run specific test
./test_runner --gtest_filter="PreyTest.FleeScalesWithProximity"

# List all available tests
./test_runner --gtest_list_tests

# Generate coverage report
make coverage
open build/coverage/html/index.html

Project Structure

assignment1/
├── src/                    # Source files (689 lines tested)
│   ├── vec2.hpp            # 2D vector math
│   ├── boid.cpp/hpp        # Base boid class
│   ├── prey.cpp/hpp        # Prey behavior (flocking + flee)
│   ├── predator.cpp/hpp    # Predator behavior (chase)
│   ├── simulation.hpp      # Main simulation loop
│   ├── kdtree_boid.hpp     # Spatial indexing
│   ├── flock_metrics.hpp   # Analysis metrics
│   └── config.hpp          # YAML configuration
├── tests/                  # Test files (9 test files)
│   ├── test_vec2.cpp
│   ├── test_boid.cpp
│   ├── test_prey.cpp
│   ├── test_predator.cpp
│   ├── test_simulation.cpp
│   ├── test_kdtree_boid.cpp
│   ├── test_flock_metrics.cpp
│   ├── test_config.cpp
│   └── test_experiment.cpp
├── config/                 # YAML configuration files
├── scripts/                # Python analysis scripts
│   └── plot_results.py     # Visualization of experiment results
├── makefile                # Build automation
└── docs/                   # Documentation

Dependencies

Dependency Purpose
Google Test Unit testing framework
LLVM Coverage instrumentation
yaml-cpp Configuration file parsing
GLEW/GLFW OpenGL rendering
libomp OpenMP parallelization (optional)

Installation by Platform

macOS (Homebrew)

brew install googletest yaml-cpp glew glfw libomp
# LLVM is included with Xcode Command Line Tools
xcode-select --install

Ubuntu/Debian

sudo apt-get update
sudo apt-get install -y \
    build-essential clang libc++-dev libc++abi-dev \
    libglew-dev libglfw3-dev libgtest-dev libyaml-cpp-dev \
    libomp-dev llvm cmake make

# Build Google Test from sources (Ubuntu provides sources only)
cd /usr/src/googletest
sudo cmake -DCMAKE_CXX_COMPILER=clang++ .
sudo make && sudo make install
sudo ldconfig

Fedora/RHEL

sudo dnf install -y \
    clang libcxx-devel libcxxabi-devel \
    glew-devel glfw-devel gtest-devel yaml-cpp-devel \
    libomp-devel llvm cmake make

Windows (vcpkg)

# Install vcpkg first: https://vcpkg.io/
vcpkg install gtest yaml-cpp glew glfw3
# Use Visual Studio or WSL2 with Ubuntu instructions above

Docker (Recommended for Cross-Platform)

The easiest way to build and test on any platform is using Docker.

Quick Start

# Run all tests
docker compose run --rm test

# Run tests with coverage (outputs to ./coverage-report/)
docker compose run --rm coverage

# Run experiments (outputs to ./output/)
docker compose run --rm experiment

Manual Docker Commands

# Build the test image
docker build --target test -t boid-sim:test .

# Run tests
docker run --rm boid-sim:test

# Build and run with custom config
docker build --target experiment -t boid-sim:experiment .
docker run --rm -v $(pwd)/output:/app/output -v $(pwd)/config:/app/config:ro \
    boid-sim:experiment config/sweep.yaml output/sweep_results.csv

Building Natively in Docker

# Start interactive container
docker run --rm -it -v $(pwd):/app -w /app ubuntu:24.04 bash

# Inside container: install deps and build
apt-get update && apt-get install -y build-essential clang libc++-dev ...
cp makefile.docker makefile
make test

Platform-Specific Notes

macOS

  • Uses the default makefile with Homebrew paths
  • OpenGL via -framework OpenGL

Linux

  • Use makefile.docker or modify paths in main makefile
  • OpenGL via -lGL
  • May need to build Google Test from sources

Windows

  • Recommended: Use WSL2 with Ubuntu and follow Linux instructions
  • Alternative: Use Docker Desktop
  • Native MSVC build requires significant makefile modifications