|
| 1 | +# 🚨 CRITICAL: Testing Safety Documentation |
| 2 | + |
| 3 | +## ⚠️ WARNING: Tests Can Wipe Your Database! |
| 4 | + |
| 5 | +This Laravel application uses the `RefreshDatabase` trait in tests, which **COMPLETELY DROPS AND RECREATES ALL DATABASE TABLES**. Running tests incorrectly **WILL DELETE ALL YOUR DATA**. |
| 6 | + |
| 7 | +## Database Configuration |
| 8 | + |
| 9 | +| Database | Purpose | Data Status | |
| 10 | +|----------|---------|-------------| |
| 11 | +| `learning_app` | Development work | **MUST BE PROTECTED** | |
| 12 | +| `learning_app_test` | Testing only | Wiped on each test run | |
| 13 | + |
| 14 | +## ✅ SAFE Testing Methods |
| 15 | + |
| 16 | +### Method 1: Use the Safe Test Script (RECOMMENDED) |
| 17 | +```bash |
| 18 | +./scripts/safe-test.sh # Run all tests |
| 19 | +./scripts/safe-test.sh --filter TestName # Run specific test |
| 20 | +./scripts/safe-test.sh --coverage # Run with coverage |
| 21 | +``` |
| 22 | + |
| 23 | +### Method 2: Use Makefile Commands |
| 24 | +```bash |
| 25 | +make test-unit # Runs safe-test.sh internally |
| 26 | +make test-unit-coverage # Safe coverage testing |
| 27 | +``` |
| 28 | + |
| 29 | +## ❌ DANGEROUS Commands - NEVER RUN THESE |
| 30 | + |
| 31 | +```bash |
| 32 | +# ALL OF THESE CAN WIPE YOUR DEVELOPMENT DATABASE: |
| 33 | +php artisan test # NO DATABASE PROTECTION |
| 34 | +artisan test # NO DATABASE PROTECTION |
| 35 | +vendor/bin/phpunit # NO DATABASE PROTECTION |
| 36 | +phpunit # NO DATABASE PROTECTION |
| 37 | + |
| 38 | +# Even with APP_ENV - still risky if misconfigured: |
| 39 | +APP_ENV=testing php artisan test # RISKY - might not load .env.testing |
| 40 | +``` |
| 41 | + |
| 42 | +## How Protection Works |
| 43 | + |
| 44 | +### 1. Safe Test Script (`scripts/safe-test.sh`) |
| 45 | +- **Validates** database name isn't `learning_app` |
| 46 | +- **Forces** `DB_DATABASE=learning_app_test` |
| 47 | +- **Sets** all required environment variables |
| 48 | +- **Creates** test database if it doesn't exist |
| 49 | +- **Displays** configuration before running |
| 50 | + |
| 51 | +### 2. TestCase.php Protection |
| 52 | +```php |
| 53 | +// Throws exception if wrong database detected |
| 54 | +if ($database !== 'learning_app_test') { |
| 55 | + throw new \Exception("CRITICAL ERROR: Tests attempting to run on non-test database!"); |
| 56 | +} |
| 57 | +``` |
| 58 | + |
| 59 | +### 3. phpunit.xml Configuration |
| 60 | +```xml |
| 61 | +<!-- Forces test database with force="true" attribute --> |
| 62 | +<env name="DB_DATABASE" value="learning_app_test" force="true"/> |
| 63 | +``` |
| 64 | + |
| 65 | +### 4. Makefile Integration |
| 66 | +All `make test*` commands use `safe-test.sh` automatically. |
| 67 | + |
| 68 | +## If Your Database Gets Wiped (Recovery) |
| 69 | + |
| 70 | +### Step 1: Don't Panic |
| 71 | +The structure can be restored, but data may be lost unless you have backups. |
| 72 | + |
| 73 | +### Step 2: Restore Database Structure |
| 74 | +```bash |
| 75 | +# Recreate all tables |
| 76 | +php artisan migrate |
| 77 | + |
| 78 | +# If you have seeders, run them |
| 79 | +php artisan db:seed |
| 80 | + |
| 81 | +# Or use fresh command |
| 82 | +php artisan migrate:fresh --seed |
| 83 | +``` |
| 84 | + |
| 85 | +### Step 3: Restore Data |
| 86 | +- Check if you have database backups |
| 87 | +- Check if you have SQL dumps |
| 88 | +- Manually recreate critical data |
| 89 | + |
| 90 | +### Step 4: Prevent Future Incidents |
| 91 | +```bash |
| 92 | +# Create a database backup before any risky operations |
| 93 | +pg_dump -U laravel -h localhost learning_app > backup_$(date +%Y%m%d_%H%M%S).sql |
| 94 | + |
| 95 | +# Set up automated backups |
| 96 | +# Add to crontab: 0 */6 * * * pg_dump -U laravel learning_app > ~/backups/learning_app_$(date +\%Y\%m\%d_\%H\%M\%S).sql |
| 97 | +``` |
| 98 | + |
| 99 | +## Best Practices |
| 100 | + |
| 101 | +1. **Always use `./scripts/safe-test.sh`** for running tests |
| 102 | +2. **Never modify phpunit.xml database settings** |
| 103 | +3. **Create regular database backups** |
| 104 | +4. **Use separate PostgreSQL users** for dev and test databases (advanced) |
| 105 | +5. **Review test output** - it shows which database is being used |
| 106 | + |
| 107 | +## For CI/CD Pipelines |
| 108 | + |
| 109 | +```yaml |
| 110 | +# GitHub Actions example |
| 111 | +- name: Run tests safely |
| 112 | + env: |
| 113 | + DB_DATABASE: learning_app_test # Explicitly set test database |
| 114 | + APP_ENV: testing |
| 115 | + run: | |
| 116 | + ./scripts/safe-test.sh |
| 117 | +``` |
| 118 | +
|
| 119 | +## Quick Reference Card |
| 120 | +
|
| 121 | +``` |
| 122 | +✅ SAFE: ./scripts/safe-test.sh |
| 123 | +✅ SAFE: make test-unit |
| 124 | +❌ DANGER: php artisan test |
| 125 | +❌ DANGER: vendor/bin/phpunit |
| 126 | +``` |
| 127 | +
|
| 128 | +## Emergency Contact |
| 129 | +
|
| 130 | +If you accidentally wipe your database: |
| 131 | +1. Stop all running processes |
| 132 | +2. Check `storage/logs/laravel.log` for any errors |
| 133 | +3. Run recovery steps above |
| 134 | +4. Consider implementing database replication for instant recovery |
| 135 | + |
| 136 | +--- |
| 137 | + |
| 138 | +**Remember**: When in doubt, use `./scripts/safe-test.sh`. It's better to be safe than sorry! |
0 commit comments