Skip to content

CLI_SAVE_TESTS.md

Latest commit

 

History

History
195 lines (153 loc) · 6.49 KB

CLI_SAVE_TESTS.md

File metadata and controls

195 lines (153 loc) · 6.49 KB
Raw

CLI Save Parameters Unit Tests

This document describes the comprehensive unit tests created for the --save and --auto-save-every CLI parameters in Conway's Game of Life.

Test Files

1. src/cli.zig - Inline Unit Tests

Contains 14 unit tests integrated directly into the CLI module:

Basic CLI Validation Tests

  • test "CLI validation - basic valid args"
  • test "CLI validation - conflicting save and load"
  • test "CLI validation - empty save file"
  • test "CLI validation - empty load file"
  • test "CLI validation - zero auto-save interval"
  • test "CLI validation - save prefix without auto-save"
  • test "CLI validation - description without save"
  • test "CLI validation - valid save with description"
  • test "CLI validation - valid auto-save with prefix and description"

CLI Parameter Parsing Tests

  • test "CLI parsing - save parameter with equals"
  • test "CLI parsing - save parameter with space"
  • test "CLI parsing - auto-save-every parameter with equals"
  • test "CLI parsing - auto-save-every parameter with space"
  • test "CLI parsing - save with description and auto-save combination"
  • test "CLI parsing - invalid auto-save-every value"
  • test "CLI parsing - save file extension handling"
  • test "CLI parsing - edge cases for save parameters"
  • test "CLI parsing - comprehensive save/auto-save scenario validation"

Total: 18 inline unit tests

2. test_cli_save_params.zig - Integration Tests

Contains 7 comprehensive integration tests:

Integration Test Categories

  1. CLI integration - parseArgs with save parameter

    • Tests complete CliArgs structure with save parameters
    • Validates all field assignments and memory management

  2. CLI integration - parseArgs with auto-save parameters

    • Tests auto-save configuration validation
    • Verifies interval and prefix handling

  3. CLI integration - complex save configuration

    • Tests combinations of manual save, auto-save, and pattern loading
    • Validates complex parameter interactions

  4. CLI integration - save parameter validation edge cases

    • Tests path separators in filenames
    • Validates minimum and maximum auto-save intervals
    • Handles special characters and edge cases

  5. CLI integration - error scenarios for save parameters

    • Tests all validation error conditions
    • Verifies proper error reporting and cleanup

  6. CLI integration - realistic usage scenarios

    • Tests real-world usage patterns
    • Validates development, research, and exploration workflows

  7. CLI integration - memory management for save parameters

    • Tests proper memory allocation and deallocation
    • Verifies no memory leaks in error conditions

Total: 7 integration tests

Test Coverage

CLI Parameters Tested

--save Parameter

  • ✅ Basic save file specification
  • ✅ Save file with description
  • ✅ Path validation (empty paths, long names, special characters)
  • ✅ File extension handling (.cgol auto-detection)
  • ✅ Memory management and cleanup
  • ✅ Conflict detection with --load

--auto-save-every Parameter

  • ✅ Numeric value parsing (equals and space syntax)
  • ✅ Interval validation (minimum 1, maximum values)
  • ✅ Integration with save prefix
  • ✅ Error handling for invalid values (0, non-numeric)
  • ✅ Memory management for prefix strings

--save-prefix Parameter

  • ✅ String allocation and validation
  • ✅ Dependency validation (requires --auto-save-every)
  • ✅ Integration with auto-save functionality
  • ✅ Memory cleanup on error conditions

--description Parameter

  • ✅ String handling and validation
  • ✅ Integration with both manual and auto-save
  • ✅ Memory management and proper cleanup
  • ✅ Validation of orphan descriptions

Error Scenarios Tested

  • ✅ Conflicting --save and --load parameters
  • ✅ Empty save file paths
  • ✅ Zero or invalid auto-save intervals
  • ✅ Save prefix without auto-save configuration
  • ✅ Description without save operation
  • ✅ Invalid numeric values for auto-save-every
  • ✅ Memory allocation failures

Edge Cases Tested

  • ✅ Very long filenames
  • ✅ Filenames with spaces and special characters
  • ✅ Path separators and subdirectories
  • ✅ Maximum reasonable auto-save intervals
  • ✅ Minimum auto-save intervals (1 generation)
  • ✅ Complex parameter combinations

Test Execution

Running the Tests

# Run main test suite (includes CLI validation tests)
zig build test

# Run dedicated CLI save parameter tests
zig test test_cli_save_params.zig

# Run both test suites together
zig build test && zig test test_cli_save_params.zig

Test Results

Main test suite:     18/18 tests PASSED ✅
Integration tests:    7/7 tests PASSED  ✅
Total coverage:      25/25 tests PASSED ✅

Example Usage Patterns Validated

1. Development Workflow

cgol --save dev_checkpoint.cgol --description "Development checkpoint"

2. Long-running Simulation

cgol --auto-save-every 500 --save-prefix "long_sim_" --generations 10000

3. Pattern Exploration

cgol --pattern patterns/glider.rle --auto-save-every 50 --save-prefix "exploration_"

4. Research Session

cgol --save research_session_1.cgol \
     --description "Oscillator behavior study" \
     --auto-save-every 200 \
     --save-prefix "research_backup_" \
     --pattern patterns/beacon.rle \
     --generations 2000

Memory Safety

All tests include proper memory management validation:

  • ✅ String allocation using allocator.dupe()
  • ✅ Proper cleanup with args.deinit(allocator)
  • ✅ No memory leaks in error conditions
  • ✅ Safe handling of optional string parameters

Architecture Integration

These tests validate the CLI parameter parsing layer that integrates with:

  • Save/Load System: Tests validate parameters that will be used by saveload.zig
  • Main Loop: Tests ensure parameters are ready for Phase 2 integration
  • Error Handling: Tests verify user-friendly error messages and graceful failures
  • Memory Management: Tests ensure no leaks in long-running simulations

Future Enhancements

The test framework is designed to easily accommodate:

  • Additional save/load parameters
  • New validation rules
  • Extended error conditions
  • Performance testing for large parameter sets
  • Integration with actual file I/O operations

Status: ✅ Complete - All CLI save parameter tests implemented and passing Coverage: 25 comprehensive unit and integration tests
Quality: Memory-safe, error-handling, and edge-case validated