# GEMINI.md - Test Suite Coordination Specialist Guide

## Module Overview

**Focus**: Overall test suite coordination and test infrastructure management

**Key Components**:
- Test suite orchestration and coordination
- Fixture management (conftest.py)
- Test environment setup and teardown
- Cross-module test dependencies
- Test reporting and analysis

**Testing Priority**: Critical - Test infrastructure must be rock-solid for all other testing

## Testing Commands for This Module

### Full Test Suite Coordination

```bash
# Run complete test suite
./test.sh

# Run test suite with full reporting
./test.sh full -vvv

# Run tests with coverage analysis
./test.sh --coverage

# Run CI pipeline tests
./test.sh ci
```

### Test Infrastructure Testing

```bash
# Test fixture functionality
./test.sh -k "test_fixtures"

# Test configuration setup
./test.sh -k "test_conftest"

# Test environment setup
./test.sh -k "test_setup"
```

### Cross-Module Testing

```bash
# Test module interactions
./test.sh integration

# Test end-to-end scenarios
./test.sh functional

# Test performance across modules
./test.sh performance
```

## Common Failure Patterns in This Module

### Fixture Failures

**Pattern**: Fixture setup/teardown failures, fixture dependency issues

**Gemini's Approach**:
1. Check conftest.py for fixture definitions
2. Test fixtures individually
3. Check fixture scope and dependencies
4. Verify cleanup after tests
5. Test fixture isolation

### Test Environment Issues

**Pattern**: Tests pass individually but fail in suite, environment pollution

**Gemini's Approach**:
1. Run tests in isolation vs suite
2. Check for shared state pollution
3. Verify proper test cleanup
4. Test order dependency issues
5. Check environment variable conflicts

### Coverage and Reporting Problems

**Pattern**: Coverage reporting broken, test results inconsistent

**Gemini's Approach**:
1. Verify coverage tools configuration
2. Test coverage collection
3. Check report generation
4. Validate test result aggregation
5. Test CI/CD integration

## Module-Specific Test Strategies

### Test Infrastructure Validation

```bash
# Validate test environment
python -m pytest tests/ --collect-only

# Test fixture system
./test.sh -k "fixture" --setup-show

# Test configuration loading
./test.sh -k "config" -v
```

### Cross-Module Dependency Testing

```bash
# Test module loading order
./test.sh --import-mode=importlib

# Test module isolation
./test.sh --forked

# Test concurrent execution
./test.sh -n auto
```

### Test Quality Assurance

```bash
# Check test coverage
./test.sh --cov=storm_logger --cov-report=html

# Test performance regression
./test.sh --benchmark-only

# Test memory usage
./test.sh --memory-profiler
```

## Critical Test Scenarios

### 1. Test Suite Integrity

**Commands**:

```bash
# Verify all tests can be collected
python -m pytest tests/ --collect-only --quiet

# Check for test naming conflicts
python -c "
import pytest
items = []
pytest.main(['tests/', '--collect-only', '-q'], plugins=[])
print('Test collection successful')
"

# Validate test structure
./test.sh --cache-show
```

**Expected Behavior**: All tests should be discoverable and runnable

### 2. Fixture System Validation

**Commands**:

```bash
# Test fixture availability
python -c "
import sys
sys.path.insert(0, 'tests')
from conftest import *
print('Fixtures loaded successfully')
"

# Test fixture cleanup
./test.sh -k "test_basic" --setup-show
```

### 3. Test Environment Consistency

**Commands**:

```bash
# Test in clean environment
./test.sh --cache-clear

# Test with different Python versions
./test.sh --python-versions

# Test isolation
./test.sh --forked
```

## GitLab Issue Templates for This Module

### Test Suite Infrastructure Failure

```markdown
## Test Suite Infrastructure Issue

**Component**: [conftest.py/Test Discovery/Fixture System/Environment]
**Failure Type**: [Setup/Execution/Teardown/Collection]
**Scope**: [Single test/Module/Full suite]

**Gemini Analysis**:
- Test collection: [successful/failed]
- Fixture loading: [working/broken]
- Environment setup: [clean/polluted]
- Dependencies: [resolved/conflicts detected]

**Error Pattern**:
```
[exact error output from test suite]
```

**Impact Assessment**:
- Tests affected: [number/percentage]
- Modules impacted: [list of modules]
- CI/CD status: [working/broken]

**Isolation Testing**:
- Individual tests: [pass/fail]
- Module tests: [pass/fail]
- Full suite: [pass/fail]
```

### Fixture System Problem

```markdown
## Test Fixture System Issue

**Fixture**: [specific fixture name or "multiple"]
**Issue Type**: [Setup failure/Teardown failure/Scope issue/Dependency problem]
**Affected Tests**: [list of failing tests]

**Gemini Analysis**:
- Fixture definition: [found/missing/incorrect]
- Fixture scope: [correct/incorrect]
- Dependencies: [resolved/circular/missing]
- Cleanup: [working/not working]

**Fixture Debug**:
```python
# Test fixture individually
def test_fixture_debug(fixture_name):
    # Results of testing fixture
    pass
```

**Test Isolation**: [affected tests pass individually: yes/no]
```

### Test Environment Pollution

```markdown
## Test Environment Pollution Issue

**Symptom**: [Tests pass individually but fail in suite]
**Pattern**: [Order dependent/State pollution/Resource conflicts]
**Affected Test Categories**: [unit/integration/functional/performance]

**Gemini Analysis**:
- State isolation: [working/broken]
- Resource cleanup: [complete/incomplete]
- Environment variables: [clean/polluted]
- Global state: [clean/modified]

**Test Order Analysis**:
- Random order: [pass/fail]
- Specific order: [pass/fail]
- Parallel execution: [pass/fail]

**Pollution Source**: [identified/unknown]
```

## Success Criteria for This Module

### ✅ Test Infrastructure
- All tests discoverable and collectable
- Fixtures work correctly with proper scope
- Test environment is clean and isolated
- No test order dependencies

### ✅ Test Execution
- Tests run reliably individually and in suite
- Proper setup and teardown
- No resource leaks or state pollution
- Consistent results across runs

### ✅ Reporting and Analysis
- Coverage reporting works
- Test results are accurate
- Performance metrics collected
- CI/CD integration functions

### ✅ Cross-Module Testing
- Module interactions work correctly
- No circular dependencies
- Proper test isolation
- Integration scenarios pass

## Emergency Escalation Triggers

**Immediate Claude Intervention Required**:

1. **Test Suite Completely Broken**: Cannot run any tests
2. **Fixture System Collapse**: Core fixtures not working
3. **Environment Pollution**: Tests contaminating each other
4. **CI/CD Pipeline Failure**: Automated testing broken
5. **Coverage System Down**: Cannot measure test coverage
6. **Cross-Module Conflicts**: Modules cannot be tested together

## Testing Best Practices for This Module

1. **Test the test infrastructure** - Validate fixtures and environment
2. **Monitor test isolation** - Ensure no state pollution
3. **Validate test discovery** - All tests should be found
4. **Check cross-module dependencies** - No circular imports
5. **Verify CI/CD compatibility** - Tests work in automated environments

## Common Solutions

### Fixture Isolation Fix

```python
# conftest.py
@pytest.fixture(autouse=True)
def clean_environment():
    # Setup
    original_state = save_current_state()
    yield
    # Teardown
    restore_state(original_state)
    clear_global_state()
```

### Test Discovery Fix

```python
# pytest.ini
[tool:pytest]
testpaths = tests
python_files = test_*.py
python_classes = Test*
python_functions = test_*
addopts = --strict-markers
```

### Environment Cleanup

```python
@pytest.fixture(autouse=True, scope="function")
def cleanup_after_test():
    yield
    # Clean up loggers
    import logging
    for logger in logging.Logger.manager.loggerDict.values():
        if isinstance(logger, logging.Logger):
            logger.handlers.clear()
    
    # Clean up environment variables
    # Clean up global state
```

## Module Dependencies

- **Test Framework**: pytest, pytest-cov, pytest-xdist
- **Environment**: os, sys, threading
- **Monitoring**: coverage, memory-profiler, pytest-benchmark

## Architecture Understanding

### Test Suite Structure

```
tests/
├── conftest.py          # Global fixtures and configuration
├── unit/               # Isolated component tests
├── integration/        # Component interaction tests
├── functional/         # End-to-end scenarios
├── performance/        # Benchmarks and stress tests
└── django_hooks/       # Framework-specific tests
```

### Fixture Hierarchy

```
Session-scoped fixtures (once per test session)
    ↓
Module-scoped fixtures (once per test module)
    ↓
Function-scoped fixtures (once per test function)
    ↓
Auto-use fixtures (automatic cleanup)
```

## Special Testing Scenarios

### Test Suite Health Check

```bash
# Comprehensive test suite validation
./test.sh --collect-only --quiet > /dev/null && echo "Collection: OK"
./test.sh -x --tb=no > /dev/null && echo "Execution: OK"  
./test.sh --cov=storm_logger --cov-fail-under=90 > /dev/null && echo "Coverage: OK"
```

### Parallel Testing Validation

```bash
# Test parallel execution
./test.sh -n 4  # 4 parallel workers

# Test resource contention
./test.sh -n auto --maxfail=1
```

### CI/CD Environment Testing

```bash
# Simulate CI environment
CI=true NO_COLOR=1 ./test.sh ci

# Test with minimal environment
env -i PATH=$PATH PYTHONPATH=$PYTHONPATH ./test.sh
```

## Test Quality Metrics

### Coverage Standards
- Overall coverage: ≥ 90%
- Critical path coverage: 100%
- Test coverage of test infrastructure: ≥ 95%

### Performance Standards
- Test suite execution: ≤ 15 minutes (full)
- Test discovery: ≤ 10 seconds
- Fixture setup/teardown: ≤ 100ms per test

### Reliability Standards
- Test flakiness: ≤ 1%
- Environment pollution: 0 occurrences
- Order dependency: 0 tests

## Your Role in This Module

You are the **Test Suite Orchestrator**. Your mission:

1. **Maintain Test Infrastructure** - Keep the testing foundation solid
2. **Coordinate Test Execution** - Ensure all test categories work together
3. **Monitor Test Quality** - Coverage, performance, and reliability
4. **Validate Cross-Module Testing** - Integration scenarios work
5. **Support CI/CD Pipeline** - Automated testing runs smoothly

**Remember**: You are the foundation that enables all other testing. If test infrastructure fails, everything else becomes unreliable.

---

**GEMINI**: The Test Suite Orchestration Specialist