fenrir/tests/PRE_COMMIT_INTEGRATION.md

# Pre-Commit Test Integration

## Overview

The test suite is now automatically executed as part of the pre-commit hook, ensuring all commits maintain code quality and passing tests.

## What Happens on Commit

When you run `git commit`, the pre-commit hook now performs **5 validation steps**:

```
1. Python syntax validation (all files)
2. Common issue detection (modified files)
3. Core module import testing
4. Test suite execution (37 tests) ← NEW!
5. Secret/credential detection
```

## Test Execution

```bash
4. Running test suite...
============================= test session starts ==============================
platform linux -- Python 3.13.7, pytest-8.4.2, pluggy-1.6.0
rootdir: /home/storm/git/fenrir
configfile: pytest.ini
collected 37 items

tests/integration/test_remote_control.py ....................            [ 54%]
tests/unit/test_settings_validation.py .................                 [100%]

============================== 37 passed in 0.44s ==============================
✓ All tests passed
```

**Performance:** Tests complete in **< 1 second**, adding minimal overhead to the commit process.

## Behavior

### ✅ Tests Pass - Commit Allowed
```bash
$ git commit -m "Add new feature"

Fenrir Pre-commit Validation
==================================
1. Validating Python syntax...
✓ Syntax validation passed

2. Checking modified files...
✓ No common issues found

3. Testing core module imports...
✓ Core module imports successful

4. Running test suite...
✓ All tests passed (37 passed in 0.44s)

5. Checking for potential secrets...
✓ No potential secrets found

==================================================
✓ All pre-commit validations passed
Commit allowed to proceed
```

### ❌ Tests Fail - Commit Blocked
```bash
$ git commit -m "Broken feature"

Fenrir Pre-commit Validation
==================================
[... earlier checks pass ...]

4. Running test suite...
✗ Test suite failed
Run: pytest tests/ -v  (to see details)

==================================================
✗ Pre-commit validation failed
Commit blocked - please fix issues above

Quick fixes:
  • Python syntax: python3 tools/validate_syntax.py --fix
  • Run tests: pytest tests/ -v
  • Review flagged files manually
  • Re-run commit after fixes
```

## Installation

The pre-commit hook is installed via:

```bash
# One-time setup
./tools/install_validation_hook.sh

# Or manually
ln -sf ../../tools/pre-commit-hook .git/hooks/pre-commit
```

## Requirements

### Required
- Python 3.7+
- Git repository

### Optional but Recommended
- `pytest` - For running tests (gracefully skipped if not installed)

If pytest is not installed, you'll see:
```
4. Running test suite...
⚠ pytest not installed - skipping tests
  Install with: pip install pytest
  Or full test suite: pip install -r tests/requirements.txt
```

The commit will still proceed, but tests won't run.

## Benefits

1. **Catch bugs early** - Tests run before code reaches the repository
2. **Maintain quality** - Broken code can't be committed
3. **Fast feedback** - Tests complete in < 1 second
4. **Zero overhead** - Gracefully degrades if pytest isn't installed
5. **Confidence** - Know that all commits pass tests

## Bypassing the Hook

**Not recommended**, but if you need to commit without running tests:

```bash
# Skip all pre-commit checks (use with caution!)
git commit --no-verify -m "Emergency hotfix"
```

**Warning:** Only use `--no-verify` for legitimate emergencies. Bypassing tests defeats their purpose.

## Troubleshooting

### Tests fail on commit but pass manually

```bash
# Check environment matches
cd /home/storm/git/fenrir
pytest tests/ -v

# Verify PYTHONPATH
echo $PYTHONPATH
```

### Hook doesn't run tests

```bash
# Check pytest is installed
pytest --version

# Install if missing
pip install pytest

# Or full test dependencies
pip install -r tests/requirements.txt
```

### Hook takes too long

The test suite is designed to run in < 1 second. If it's slower:

```bash
# Check test timing
pytest tests/ --durations=10

# Look for slow tests (should all be < 100ms)
```

## Statistics

- **Tests Executed:** 37
- **Execution Time:** 0.44 seconds
- **Pass Rate:** 100%
- **Coverage:** Unit tests (17) + Integration tests (20)

## Future Enhancements

Possible additions to pre-commit validation:

- **Coverage threshold** - Require minimum test coverage percentage
- **Performance regression** - Warn if tests get slower
- **Incremental testing** - Only run tests for modified code
- **Parallel execution** - Use `pytest -n auto` (requires pytest-xdist)

## Related Documentation

- `tests/README.md` - Test strategy overview
- `tests/TESTING_GUIDE.md` - Comprehensive testing guide
- `TESTING_SUMMARY.md` - Test implementation summary
- `tools/pre-commit-hook` - Pre-commit hook source code

## Summary

Adding tests to the pre-commit hook ensures:
- ✅ All commits have passing tests
- ✅ Regressions are caught immediately
- ✅ Code quality is maintained
- ✅ Minimal performance impact (< 1 second)
- ✅ Graceful degradation without pytest

**Result:** Higher code quality with virtually zero developer friction.