🔧 TECHNOLOGY STACK: CORE Testing Infrastructure

Proyecto: 001_CORE_TESTING Creado: 2025-10-17 Categoría: Testing, Benchmarking, CI/CD, Quality Assurance

---

📦 RESUMEN EJECUTIVO

Para un sistema de testing PROFESIONAL y COMPLETO de 04_CORE necesitamos:

┌─────────────────────────────────────────────────────────────┐
│                    STACK TECNOLÓGICO                         │
├─────────────────────────────────────────────────────────────┤
│  1. TESTING FRAMEWORK     → Catch2 v3                       │
│  2. BENCHMARKING          → Google Benchmark                │
│  3. CODE COVERAGE         → OpenCppCoverage (Win)           │
│  4. SANITIZERS            → ASAN, TSAN, UBSAN (MSVC/Clang)  │
│  5. CI/CD                 → GitHub Actions                   │
│  6. DEPENDENCY MANAGEMENT → vcpkg                            │
│  7. STATIC ANALYSIS       → clang-tidy, cppcheck            │
│  8. BUILD SYSTEM          → CMake 3.22+                      │
└─────────────────────────────────────────────────────────────┘

---

🎯 CATEGORÍAS Y HERRAMIENTAS

1. UNIT TESTING ✅ (CRÍTICO)

Catch2 v3

Qué es: Framework moderno de testing para C++

Por qué: - Header-only (fácil integración) - Sintaxis clara y legible - BDD-style tests - Usado en industria (JUCE, etc.)

Instalación:

# Via vcpkg (RECOMENDADO)
vcpkg install catch2:x64-windows

# O via CMake FetchContent
FetchContent_Declare(
  Catch2
  GIT_REPOSITORY https://github.com/catchorg/Catch2.git
  GIT_TAG v3.5.0
)

Uso en CORE:

#include <catch2/catch_test_macros.hpp>

TEST_CASE("RingBuffer stores and retrieves values") {
    RingBuffer<float> buffer(1024);
    buffer.write(1.0f);
    REQUIRE(buffer.read(0) == 1.0f);
}

Documentación: https://github.com/catchorg/Catch2

---

2. BENCHMARKING ⚡ (ALTO)

Google Benchmark

Qué es: Framework de micro-benchmarking para C++

Por qué: - Medición precisa de performance - Estadísticas automáticas (media, mediana, desv. std) - Detecta outliers - Output en múltiples formatos (console, JSON, CSV)

Instalación:

# Via vcpkg
vcpkg install benchmark:x64-windows

# O compilar desde source
git clone https://github.com/google/benchmark.git
cd benchmark
cmake -B build -S . -DBENCHMARK_DOWNLOAD_DEPENDENCIES=ON
cmake --build build --config Release
cmake --install build --prefix C:/tools/benchmark

Uso en CORE:

#include <benchmark/benchmark.h>

static void BM_RingBuffer_Write(benchmark::State& state) {
    RingBuffer<float> buffer(1024);
    for (auto _ : state) {
        buffer.write(1.0f);
        benchmark::DoNotOptimize(buffer);
    }
}
BENCHMARK(BM_RingBuffer_Write);

BENCHMARK_MAIN();

Ejemplo Output:

Run on (8 X 3000 MHz CPU s)
CPU Caches:
  L1 Data 32 KiB (x4)
  L1 Instruction 32 KiB (x4)
  L2 Unified 256 KiB (x4)
  L3 Unified 8192 KiB (x1)
----------------------------------------------------------------
Benchmark                      Time             CPU   Iterations
----------------------------------------------------------------
BM_RingBuffer_Write         3.2 ns          3.1 ns    224000000
BM_LockFreeQueue_Push      45.3 ns         44.8 ns     15680000

Documentación: https://github.com/google/benchmark

---

3. CODE COVERAGE 📊 (ALTO)

OpenCppCoverage (Windows)

Qué es: Herramienta de cobertura de código para Windows

Por qué: - Nativa para Windows/MSVC - Integración con Visual Studio - Output HTML interactivo - Export a Cobertura XML (para CI)

Instalación:

# Via Chocolatey
choco install opencppcoverage

# O download manual
# https://github.com/OpenCppCoverage/OpenCppCoverage/releases

Uso:

# Ejecutar tests con coverage
OpenCppCoverage.exe `
  --sources "C:\AudioDev\audio-lab\04_CORE" `
  --export_type html:coverage_report `
  --export_type cobertura:coverage.xml `
  -- _ARTIFACTS\binaries\Release\test_containers.exe

# Ver reporte
start coverage_report\index.html

Output: - HTML report con líneas cubiertas (verde/rojo) - Métricas por archivo/función - Branch coverage - Export para CI/CD

Documentación: https://github.com/OpenCppCoverage/OpenCppCoverage

---

Alternativas (Linux/macOS)

gcov + lcov

# Linux
sudo apt-get install lcov

# Compilar con coverage flags
g++ -fprofile-arcs -ftest-coverage test.cpp

# Generar reporte
lcov --capture --directory . --output-file coverage.info
genhtml coverage.info --output-directory coverage_html

llvm-cov (Clang)

# Compilar con clang coverage
clang++ -fprofile-instr-generate -fcoverage-mapping test.cpp

# Ejecutar y generar profile
./a.out
llvm-profdata merge default.profraw -o default.profdata
llvm-cov show ./a.out -instr-profile=default.profdata

---

4. SANITIZERS 🛡️ (CRÍTICO para RT-Safety)

Address Sanitizer (ASAN)

Qué es: Detecta memory errors (leaks, use-after-free, etc.)

Instalación: Built-in en MSVC 2019+ y Clang

Uso:

# En CMakeLists.txt
if(MSVC)
    target_compile_options(audiolab_core PRIVATE /fsanitize=address)
else()
    target_compile_options(audiolab_core PRIVATE -fsanitize=address)
    target_link_options(audiolab_core PRIVATE -fsanitize=address)
endif()

Detecta: - Memory leaks - Use-after-free - Buffer overflows - Stack/heap overflow

---

Thread Sanitizer (TSAN)

Qué es: Detecta data races y condiciones de carrera

CRÍTICO para CORE: Lock-free containers DEBEN pasar TSAN

Uso:

target_compile_options(test_lock_free PRIVATE -fsanitize=thread)
target_link_options(test_lock_free PRIVATE -fsanitize=thread)

Detecta: - Data races - Deadlocks - Lock order inversions

Nota: No compatible con ASAN (ejecutar por separado)

---

Undefined Behavior Sanitizer (UBSAN)

Qué es: Detecta undefined behavior

Uso:

target_compile_options(audiolab_core PRIVATE -fsanitize=undefined)

Detecta: - Integer overflow - Division by zero - Null pointer dereference - Misaligned access

---

5. CI/CD 🔄 (ALTO)

GitHub Actions

Qué es: CI/CD nativo de GitHub

Por qué: - Gratis para repos públicos - Integración nativa con GitHub - Matrix builds (Windows/Linux/macOS) - Runners con herramientas pre-instaladas

Archivo: .github/workflows/core-tests.yml

name: CORE Tests

on: [push, pull_request]

jobs:
  test-windows:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup vcpkg
        run: |
          git clone https://github.com/Microsoft/vcpkg.git
          .\vcpkg\bootstrap-vcpkg.bat
          .\vcpkg\vcpkg install catch2:x64-windows

      - name: Configure CMake
        run: |
          cmake -B build -S . -G "Visual Studio 17 2022" -A x64

      - name: Build
        run: cmake --build build --config Release

      - name: Run Tests
        run: |
          cd build
          ctest -C Release --output-on-failure

      - name: Coverage
        run: |
          OpenCppCoverage --sources 04_CORE -- build/Release/test_*.exe

      - name: Upload Coverage
        uses: codecov/codecov-action@v3
        with:
          files: ./coverage.xml

  test-linux:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y catch2 libbenchmark-dev lcov

      - name: Build and Test
        run: |
          cmake -B build -S . -DCMAKE_BUILD_TYPE=Release
          cmake --build build
          cd build && ctest --output-on-failure

Documentación: https://docs.github.com/en/actions

---

Alternativas

GitLab CI

# .gitlab-ci.yml
test:
  image: gcc:latest
  script:
    - cmake -B build
    - cmake --build build
    - cd build && ctest

Jenkins

• Más complejo pero más flexible
• Para empresas con infraestructura propia

---

6. DEPENDENCY MANAGEMENT 📦 (CRÍTICO)

vcpkg

Qué es: Package manager de Microsoft para C++

Por qué: - Cross-platform (Windows/Linux/macOS) - Gran catálogo de libraries - Integración con CMake - Versionado y reproducibilidad

Instalación:

# Clone and bootstrap
git clone https://github.com/Microsoft/vcpkg.git C:/tools/vcpkg
cd C:/tools/vcpkg
.\bootstrap-vcpkg.bat

# Agregar al PATH
$env:PATH += ";C:\tools\vcpkg"

# Integrar con Visual Studio
.\vcpkg integrate install

Manifest Mode (Recomendado):

vcpkg.json:

{
  "name": "audiolab",
  "version": "1.0.0",
  "dependencies": [
    "catch2",
    "benchmark",
    "fmt",
    "spdlog"
  ]
}

CMake Integration:

# En CMakeLists.txt
set(CMAKE_TOOLCHAIN_FILE "C:/tools/vcpkg/scripts/buildsystems/vcpkg.cmake")
find_package(Catch2 3 REQUIRED)
find_package(benchmark REQUIRED)

Packages Necesarios:

vcpkg install catch2:x64-windows
vcpkg install benchmark:x64-windows
vcpkg install fmt:x64-windows
vcpkg install spdlog:x64-windows

Documentación: https://vcpkg.io/

---

Alternativa: Conan

# conanfile.txt
[requires]
catch2/3.5.0
benchmark/1.8.3

[generators]
CMakeDeps
CMakeToolchain

---

7. STATIC ANALYSIS 🔍 (MEDIO)

clang-tidy

Qué es: Linter y static analyzer para C++

Por qué: - Detecta bugs antes de ejecutar - Modernización de código (C++20) - Sugerencias de best practices

Instalación:

# Via LLVM installer
# https://releases.llvm.org/download.html

# O via vcpkg
vcpkg install llvm:x64-windows

Uso:

# Analizar archivo
clang-tidy ring_buffer.hpp -- -std=c++20

# Integración con CMake
set(CMAKE_CXX_CLANG_TIDY "clang-tidy;-checks=*")

Checks Importantes: - bugprone-* - Bugs comunes - performance-* - Optimizaciones - modernize-* - C++ moderno - readability-* - Legibilidad

---

cppcheck

Qué es: Static analyzer open-source

Instalación:

choco install cppcheck

Uso:

cppcheck --enable=all --inconclusive 04_CORE/

---

MSVC Code Analysis

Qué es: Analizador nativo de Visual Studio

Uso:

target_compile_options(audiolab_core PRIVATE /analyze)

---

8. PERFORMANCE PROFILING 🚀 (MEDIO)

Tracy Profiler

Qué es: Profiler en tiempo real para C++

Por qué: - Frame-by-frame profiling - Visualización de threads - Memory tracking - Perfecto para audio RT

Instalación:

git clone https://github.com/wolfpld/tracy.git
cd tracy/profiler/build/win32
msbuild Tracy.sln

Uso:

#include <tracy/Tracy.hpp>

void processAudio() {
    ZoneScoped;  // ← Tracy macro
    // Audio processing
}

Documentación: https://github.com/wolfpld/tracy

---

Intel VTune

Qué es: Profiler profesional de Intel

Gratis: Para desarrollo (no comercial)

Features: - CPU hotspots - Threading analysis - Memory access patterns

Download: https://www.intel.com/content/www/us/en/developer/tools/oneapi/vtune-profiler.html

---

AMD μProf

Qué es: Profiler para CPUs AMD

Gratis: Sí

Download: https://www.amd.com/en/developer/uprof.html

---

9. MEMORY DEBUGGING 🧠 (MEDIO)

Valgrind (Linux/macOS)

Qué es: Suite de debugging/profiling

Tools: - Memcheck: Memory leaks, invalid access - Helgrind: Thread errors - Cachegrind: Cache profiling

Uso:

valgrind --leak-check=full ./test_containers

---

Dr. Memory (Windows)

Qué es: Alternativa a Valgrind para Windows

Instalación:

choco install drmemory

Uso:

drmemory.exe -- test_containers.exe

---

10. CONTINUOUS MONITORING 📈 (BAJO - Futuro)

Codecov

Qué es: Servicio de coverage tracking

Gratis: Para OSS

Integración:

# En GitHub Actions
- uses: codecov/codecov-action@v3

Dashboard: Tracking de coverage over time

Website: https://codecov.io/

---

SonarCloud

Qué es: Code quality monitoring

Features: - Code smells - Security vulnerabilities - Technical debt tracking - Coverage tracking

Gratis: Para OSS

Website: https://sonarcloud.io/

---

📋 PRIORIZACIÓN DE INSTALACIÓN

FASE 1: ESSENTIALS (HACER YA)

1. vcpkg              (Dependency manager)
2. Catch2             (Testing framework)
3. CMake 3.22+        (Build system)
4. Git                (Version control)

FASE 2: QUALITY (Esta semana)

5. Google Benchmark   (Performance testing)
6. OpenCppCoverage    (Code coverage)
7. GitHub Actions     (CI/CD)

FASE 3: ADVANCED (Próximas semanas)

8. ASAN/TSAN/UBSAN    (Sanitizers)
9. clang-tidy         (Static analysis)
10. Tracy Profiler     (Performance profiling)

FASE 4: ENTERPRISE (Futuro)

11. Codecov/SonarCloud (Continuous monitoring)
12. Intel VTune        (Advanced profiling)
13. Valgrind/Dr.Memory (Memory debugging)

---

🛠️ INSTALACIÓN COMPLETA (Script)

Windows PowerShell Script

# install_testing_stack.ps1

# 1. Install Chocolatey (if not installed)
if (!(Get-Command choco -ErrorAction SilentlyContinue)) {
    Write-Host "Installing Chocolatey..."
    Set-ExecutionPolicy Bypass -Scope Process -Force
    [System.Net.ServicePointManager]::SecurityProtocol = `
        [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
    iex ((New-Object System.Net.WebClient).DownloadString(
        'https://community.chocolatey.org/install.ps1'))
}

# 2. Install vcpkg
if (!(Test-Path "C:\tools\vcpkg")) {
    Write-Host "Installing vcpkg..."
    git clone https://github.com/Microsoft/vcpkg.git C:\tools\vcpkg
    C:\tools\vcpkg\bootstrap-vcpkg.bat
    C:\tools\vcpkg\vcpkg integrate install
}

# 3. Install dependencies via vcpkg
Write-Host "Installing C++ dependencies..."
C:\tools\vcpkg\vcpkg install `
    catch2:x64-windows `
    benchmark:x64-windows `
    fmt:x64-windows `
    spdlog:x64-windows

# 4. Install OpenCppCoverage
Write-Host "Installing OpenCppCoverage..."
choco install opencppcoverage -y

# 5. Install LLVM (clang-tidy)
Write-Host "Installing LLVM..."
choco install llvm -y

# 6. Install cppcheck
Write-Host "Installing cppcheck..."
choco install cppcheck -y

# 7. Verify installations
Write-Host "`nVerifying installations..."
vcpkg list
OpenCppCoverage --help
clang-tidy --version
cppcheck --version

Write-Host "`n✅ Testing stack installed successfully!"

Ejecutar:

# Guardar script como install_testing_stack.ps1
# Ejecutar con privilegios de administrador
.\install_testing_stack.ps1

---

📊 COSTOS

Herramienta	Precio	Notas
Catch2	FREE	Open Source (BSL-1.0)
Google Benchmark	FREE	Open Source (Apache 2.0)
OpenCppCoverage	FREE	Open Source (GPL-3.0)
vcpkg	FREE	Microsoft OSS
GitHub Actions	FREE	2000 min/mes para público
clang-tidy	FREE	LLVM OSS
cppcheck	FREE	OSS (GPL-3.0)
Tracy	FREE	OSS (BSD-3)
Codecov	FREE	Para OSS
SonarCloud	FREE	Para OSS
Intel VTune	FREE	Community edition
TOTAL	$0	✅ 100% Gratis

---

🎯 ROADMAP DE IMPLEMENTACIÓN

Semana 1: Foundation

• vcpkg instalado
• Catch2 integrado
• Tests compilando
• Tests ejecutando

Semana 2: Quality

• Google Benchmark integrado
• Benchmarks de componentes críticos
• OpenCppCoverage configurado
• Coverage ≥70%

Semana 3: Automation

• GitHub Actions CI
• Pre-commit hooks
• Sanitizers en CI
• Coverage tracking

Semana 4: Advanced

• Tracy profiler integrado
• Static analysis en CI
• Performance regression tests
• Full documentation

---

📝 NOTAS IMPORTANTES

Dependencias entre Herramientas

• vcpkg → Instalar PRIMERO (gestiona todo lo demás)
• CMake → Necesario para vcpkg
• Git → Necesario para vcpkg

Compatibilidad

• ASAN + TSAN: NO compatible (ejecutar separado)
• Coverage + Optimizations: NO compatible (usar Debug o RelWithDebInfo)
• Sanitizers: Penalización de performance (~2-5x slower)

Espacio en Disco

• vcpkg: ~2GB (con dependencies)
• LLVM: ~1GB
• Benchmarks: ~500MB
• Total: ~4GB aprox

---

🔗 RECURSOS Y DOCUMENTACIÓN

Tutoriales

• Catch2 Tutorial
• Google Benchmark Quick Start
• OpenCppCoverage Tutorial
• vcpkg Getting Started

Cheat Sheets

• CMake Cheat Sheet
• GitHub Actions Cheat Sheet

---

✅ CHECKLIST DE INSTALACIÓN

Pre-requisitos

• Windows 10/11 (o Linux/macOS)
• Visual Studio 2022 (o GCC/Clang)
• CMake 3.22+
• Git
• PowerShell 5.0+

Herramientas Críticas

• vcpkg instalado
• Catch2 disponible
• Google Benchmark disponible
• OpenCppCoverage instalado

Verificación

• vcpkg list muestra catch2 y benchmark
• CMake encuentra Catch2
• Tests de ejemplo compilan
• Coverage genera reportes

---

VERSION: 1.0.0 LAST UPDATED: 2025-10-17 STATUS: READY TO INSTALL 🚀