# CI/CD Testing Configuration for ldastools_cmake

## Overview
The ldastools_cmake package includes comprehensive tests for cx_boost_* macros, but some tests may fail in CI environments due to environment-specific configurations (conda setups, missing boost installations, etc.).

## Test Categories

### Core Tests (Always Required)
These tests validate the essential boost detection functionality:
- `test_cx_boost_macros` - Direct CMake script testing
- `test_cx_boost_validation` - Cross-platform validation  
- Integration test - Actual boost compilation/linking

### Optional Tests (May Fail in CI)
These tests validate environment-specific scenarios:
- `test_cx_boost_environments` - Conda environment switching
- `run_cx_boost_tests` - Comprehensive test suite including environment tests

## CI Configuration Options

### Option 1: Disable Environment Tests (Recommended for CI)
```bash
cmake -DBUILD_TESTING_ENVIRONMENT=OFF ..
make
make test
```

### Option 2: Run Only Core Tests  
```bash
cmake -DBUILD_TESTING=ON ..
make
ctest -L "^((?!optional).)*$"  # Exclude tests labeled "optional"
```

### Option 3: Run All Tests but Ignore Failures
```bash
cmake -DBUILD_TESTING=ON ..
make
ctest --output-on-failure || true  # Continue on test failures
```

### Option 4: Run Only Specific Tests
```bash
cmake -DBUILD_TESTING=ON ..
make
ctest -R "test_cx_boost_macros|test_cx_boost_validation"
```

## GitLab CI Configuration Example

```yaml
build_ldastools_cmake:
  stage: build
  script:
    - mkdir build && cd build
    - cmake -DBUILD_TESTING_ENVIRONMENT=OFF -DCMAKE_BUILD_TYPE=Release ..
    - make -j4
    - make test
  artifacts:
    when: always
    reports:
      junit: build/test_results.xml
  allow_failure: false
```

## Jenkins Pipeline Example

```groovy
stage('Test') {
    steps {
        sh '''
            cd build
            cmake -DBUILD_TESTING_ENVIRONMENT=OFF ..
            make test || echo "Some tests failed but continuing..."
        '''
    }
    post {
        always {
            junit 'build/**/test_results.xml'
        }
    }
}
```

## Test Failure Interpretation

### ✅ Build Should Proceed If:
- Core boost detection tests pass (`test_cx_boost_macros`, `test_cx_boost_validation`)
- Integration test passes (proves boost actually works)
- Only environment-specific tests fail

### ❌ Build Should Fail If:
- Core CMake macro tests fail
- Integration test fails (boost detection/linking broken)
- Build/compilation errors occur

## Environment Variables

Set these in CI to control test behavior:
```bash
export BUILD_TESTING_ENVIRONMENT=OFF
export BUILD_TESTING_STRICT=OFF
export BOOST_ROOT=/usr/local  # If boost is in non-standard location
```

## Troubleshooting

### Common CI Issues:
1. **Conda environment not available** - Use `BUILD_TESTING_ENVIRONMENT=OFF`
2. **Boost not found** - Set `BOOST_ROOT` environment variable
3. **Tests timeout** - Increase timeout or disable comprehensive tests
4. **Permission issues** - Ensure test artifacts directory is writable

### Essential Test Requirements:
- CMake 3.10+
- Boost development libraries
- Python 3 (for validation tests)
- Write access to temporary directories

## Summary for CI Maintainers

**Recommended CI Configuration**:
```bash
cmake -DBUILD_TESTING_ENVIRONMENT=OFF -DCMAKE_BUILD_TYPE=Release ..
make -j4
make test
```

This configuration ensures:
- ✅ Core boost detection functionality is validated
- ✅ Build pipeline continues even if environment-specific tests fail
- ✅ Essential functionality is proven to work
- ✅ Downstream packages can proceed with their builds