yaze/docs/internal/testing/README_TESTING.md

YAZE Testing Infrastructure

This directory contains comprehensive documentation for YAZE's testing infrastructure, designed to prevent build failures and ensure code quality across platforms.

Quick Start

Before pushing code:

# Unix/macOS
./scripts/pre-push-test.sh

# Windows
.\scripts\pre-push-test.ps1

Time: ~2 minutes Prevents: ~90% of CI failures

Documents in This Directory

1. Gap Analysis

Purpose: Documents what testing gaps led to recent CI failures

Key Sections:

• Issues we didn't catch (Windows Abseil, Linux FLAGS conflicts)
• Current testing coverage analysis
• CI/CD coverage gaps
• Root cause analysis by issue type

Read this if: You want to understand why we built this infrastructure

2. Testing Strategy

Purpose: Complete guide to YAZE's 5-level testing pyramid

Key Sections:

• Level 0-6: From static analysis to E2E tests
• When to run each test level
• Test organization and naming conventions
• Platform-specific testing considerations
• Debugging test failures

Read this if: You need to write tests or understand the testing framework

3. Pre-Push Checklist

Purpose: Step-by-step checklist before pushing code

Key Sections:

• Quick start commands
• Detailed checklist for each test level
• Platform-specific checks
• Troubleshooting common issues
• CI-matching presets

Read this if: You're about to push code and want to make sure it'll pass CI

4. CI Improvements Proposal

Purpose: Technical proposal for enhancing CI/CD pipeline

Key Sections:

• Proposed new CI jobs (config validation, compile-check, symbol-check)
• Job dependency graph
• Time and cost analysis
• Implementation plan
• Success metrics

Read this if: You're working on CI/CD infrastructure or want to understand planned improvements

Testing Levels Overview

Level 0: Static Analysis     → < 1 second   → Format, lint
Level 1: Config Validation   → ~10 seconds  → CMake, includes
Level 2: Smoke Compilation   → ~90 seconds  → Headers, preprocessor
Level 3: Symbol Validation   → ~30 seconds  → ODR, conflicts
Level 4: Unit Tests          → ~30 seconds  → Logic, algorithms
Level 5: Integration Tests   → 2-5 minutes  → Multi-component
Level 6: E2E Tests           → 5-10 minutes → Full workflows

Scripts

Pre-Push Test Scripts

• Unix/macOS: scripts/pre-push-test.sh
• Windows: scripts/pre-push-test.ps1

Usage:

# Run all checks
./scripts/pre-push-test.sh

# Only validate configuration
./scripts/pre-push-test.sh --config-only

# Skip symbol checking
./scripts/pre-push-test.sh --skip-symbols

# Skip tests (faster)
./scripts/pre-push-test.sh --skip-tests

# Verbose output
./scripts/pre-push-test.sh --verbose

Symbol Verification Script

• Unix/macOS: scripts/verify-symbols.sh
• Windows: scripts/verify-symbols.ps1 (TODO)

Usage:

# Check for symbol conflicts
./scripts/verify-symbols.sh

# Show detailed output
./scripts/verify-symbols.sh --verbose

# Show all symbols (including safe duplicates)
./scripts/verify-symbols.sh --show-all

# Use custom build directory
./scripts/verify-symbols.sh --build-dir build_test

Success Metrics

Target Goals

• Time to first failure: <5 minutes (down from ~15 min)
• PR iteration time: 30-60 minutes (down from 2-4 hours)
• CI failure rate: <10% (down from ~30%)
• Symbol conflicts caught: 100% (up from manual detection)

Current Status

• ✅ Pre-push infrastructure created
• ✅ Symbol checker implemented
• ✅ Gap analysis documented
• 🔄 CI improvements planned (see proposal)

Related Documentation

Project-Wide

• CLAUDE.md - Project overview and build guidelines
• docs/public/build/quick-reference.md - Build commands
• docs/public/build/troubleshooting.md - Platform-specific fixes

Developer Guides

• docs/public/developer/testing-guide.md - Testing best practices
• docs/public/developer/testing-without-roms.md - ROM-independent testing