|
| 1 | +# Safety Tests Documentation |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +The `tests/test_safety.rs` module contains tests for git-x's safety and backup functionality. Some of these tests perform **DESTRUCTIVE git operations** that can modify your working directory. |
| 6 | + |
| 7 | +## Destructive Operations |
| 8 | + |
| 9 | +The following operations are considered destructive and are conditionally run: |
| 10 | + |
| 11 | +- **Creating backup branches**: Adds new git branches to your repository |
| 12 | +- **Creating checkpoints**: Creates git stashes that modify stash state |
| 13 | +- **Restoring checkpoints**: Pops git stashes, potentially changing working directory |
| 14 | +- **Cleaning up branches**: Can delete backup branches (though limited to very old ones) |
| 15 | + |
| 16 | +## Test Execution Modes |
| 17 | + |
| 18 | +### Local Development (Default - Safe Mode) |
| 19 | +```bash |
| 20 | +cargo test test_safety |
| 21 | +``` |
| 22 | +- Destructive tests are **SKIPPED** automatically |
| 23 | +- Only safe tests run (method signatures, builders, validation) |
| 24 | +- Your git repository remains unchanged |
| 25 | + |
| 26 | +### CI Environment (Automatic) |
| 27 | +```bash |
| 28 | +# In GitHub Actions or other CI |
| 29 | +cargo test test_safety |
| 30 | +``` |
| 31 | +- All tests run automatically (detected via `CI` or `GITHUB_ACTIONS` env vars) |
| 32 | +- Safe for CI because repositories are disposable |
| 33 | + |
| 34 | +### Manual Override (Use with Caution) |
| 35 | +```bash |
| 36 | +ENABLE_DESTRUCTIVE_TESTS=1 cargo test test_safety |
| 37 | +``` |
| 38 | +- Forces ALL tests to run locally |
| 39 | +- **WARNING**: Will modify your git repository |
| 40 | +- Only use in test repositories or when you understand the risks |
| 41 | + |
| 42 | +## Detection Logic |
| 43 | + |
| 44 | +Tests are skipped locally unless one of these conditions is met: |
| 45 | +- `CI` environment variable is set |
| 46 | +- `GITHUB_ACTIONS` environment variable is set |
| 47 | +- `ENABLE_DESTRUCTIVE_TESTS` environment variable is set |
| 48 | + |
| 49 | +## Safety Measures |
| 50 | + |
| 51 | +Even when destructive tests run: |
| 52 | +- Backup creation uses timestamp-based names to avoid conflicts |
| 53 | +- Cleanup operations target only very old backups (365+ days) |
| 54 | +- All operations use non-interactive mode to prevent hanging |
| 55 | +- Tests are designed to be as safe as possible while still testing functionality |
| 56 | + |
| 57 | +## Development Guidelines |
| 58 | + |
| 59 | +When adding new safety tests: |
| 60 | +1. Wrap potentially destructive operations with `if !should_run_destructive_tests() { return; }` |
| 61 | +2. Use descriptive test names that indicate destructive nature |
| 62 | +3. Test the minimal necessary functionality to verify behavior |
| 63 | +4. Prefer testing business logic over actual git operations when possible |
0 commit comments