# Integration Test Safety

## Overview

The integration tests in `tests/integration/` perform real filesystem operations while protecting the host system from modifications. This document describes the safety mechanisms and guarantees.

## Safety Guarantees

### File System Isolation

All file operations are restricted to temporary directories:

* Default app paths (`/Applications/Brave Browser.app`) redirect to temp directory
* User scan directories (`~/Library/Application Support`) redirect to temp directory
* Specific app paths (Config.SPECIFIC_APPS) are cleared during testing

### Process Protection

* `pkill` commands are mocked and return "no processes found"
* No actual processes on the system are terminated during test execution

### Code Signing Protection

* `codesign` commands are mocked to always succeed
* No actual code signing operations are performed

### Automatic Cleanup

* All test artifacts are created in pytest temporary directories
* Temporary directories are automatically cleaned up after tests complete
* Typical location: `/tmp/pytest-of-<user>/pytest-<n>/`

## Implementation

### protect_host_system Fixture

This fixture automatically applies to all integration tests and overrides configuration:

```python
# Real paths redirect to temp paths
Config.DEFAULT_BRAVE_PATH → /tmp/pytest-x/Applications/Brave Browser.app
Config.DEFAULT_LGHUB_PATH → /tmp/pytest-x/Applications/lghub.app
Config.STANDARD_SCAN_DIRS → /tmp/pytest-x/Library/Application Support
Config.SPECIFIC_APPS → {} (empty)
```

### Subprocess Mocking

The `mock_pkill_safe` and `mock_subprocess_all_safe` fixtures intercept subprocess calls:

```python
# pkill is mocked
kill_app_by_name("Brave Browser")  # Returns False, does not run pkill

# codesign is mocked
resign_application(app_path)  # Returns True, does not run codesign

# xattr is mocked
strip_extended_attributes(app_path)  # Returns True, does not run xattr
```

## Verification

Run the safety verification tests to confirm protections are active:

```bash
pytest tests/integration/test_safety_checks.py -v
```

Expected results:

* Default paths point to temp directory
* Scan directories are within temp directory
* Specific apps list is empty
* Real system paths are not used
* pkill is mocked
* codesign is mocked
* File writes stay within temp directory

## Running Tests

### Basic Execution

```bash
# Run all integration tests
pytest tests/integration/ -v

# Run specific test file
pytest tests/integration/test_settings_patching_integration.py -v

# Run with coverage
pytest tests/integration/ --cov=electron_angle_patcher --cov-report=html
```

### Safety Checklist

Before running integration tests, confirm:

* Tests use `integration_temp_dir` fixture for file operations
* Tests use `mock_pkill_safe` or `mock_subprocess_all_safe` for subprocess operations
* No hardcoded paths to `/Applications/` or `~/Library/` in test code

## What Tests Do Not Do

The integration tests will not:

* Modify `/Applications/`
* Modify `~/Library/`
* Kill real processes
* Perform actual code signing
* Leave artifacts after completion

## Test Isolation

Each test receives an isolated temporary directory:

```python
def test_example(integration_temp_dir: Path):
    # integration_temp_dir is unique per test
    # Typically: /tmp/pytest-123/test_example0/

    # Create test apps here
    app_path = create_brave_app_bundle(integration_temp_dir, "fresh")

    # Test operations only affect integration_temp_dir
    patcher = BraveExecutablePatcher(app_path)
    result = patcher.patch()

    # Temp directory cleaned up automatically
```

## Subprocess Mocking Strategy

Mocking occurs at the usage location to prevent import-time binding issues:

```python
# Patch where subprocess is USED, not where it's defined
import electron_angle_patcher.utils as utils_module
monkeypatch.setattr(utils_module.subprocess, "run", mock_function)
```

This ensures mocks work even if modules were imported before the test.

## Emergency Recovery

If tests unexpectedly create files outside temp directories (should not occur with current safeguards):

```bash
# Check for test artifacts in home directory
ls -la ~/Library/Application\ Support/ | grep -i test

# Remove any test artifacts (if found)
rm -rf ~/Library/Application\ Support/TestApp*
```

With current safeguards, this procedure should not be necessary.

## References

* `tests/integration/conftest.py` - Safety fixtures implementation
* `tests/integration/test_safety_checks.py` - Safety verification tests
* `tests/fixtures/app_builders.py` - Test app creation utilities
