# Quick Start: Testing django-cronjob-utils

## ⚡ TL;DR - Run Tests Now

```bash
# 1. Check if hooks are installed
python3 -c "import django_package_hooks" 2>/dev/null && echo "✓ Ready" || echo "✗ Need to install"

# 2. If needed, install django-package-hooks
pip3 install --user -e ../django-package-hooks

# 3. Run tests
export DJANGO_SETTINGS_MODULE=tests.settings
python3 manage.py test
```

Expected result: **182 tests pass** (including 25 hook tests)

---

## 📦 Installation Options

### Option 1: User Install (No Sudo)
```bash
pip3 install --user -e ../django-package-hooks
```

### Option 2: Virtual Environment
```bash
source venv/bin/activate
pip install -e ../django-package-hooks
```

### Option 3: System-Wide (Requires Sudo)
```bash
sudo pip3 install -e ../django-package-hooks
```

---

## 🧪 Run Specific Tests

```bash
export DJANGO_SETTINGS_MODULE=tests.settings

# All hook tests only
python3 manage.py test tests.test_hooks

# All base functionality tests
python3 manage.py test tests.test_base

# Single test class
python3 manage.py test tests.test_hooks.PreHookStandardTests

# Single test method
python3 manage.py test tests.test_hooks.PreHookStandardTests.test_pre_hook_allows_execution
```

---

## ✅ Verify Installation

```bash
python3 << 'PYEOF'
import sys
try:
    import django_package_hooks
    print("✓ django-package-hooks installed")
    print(f"  Version: {django_package_hooks.__version__}")
    
    # Test that we can import the hook classes
    from django_package_hooks import HookManager, HookType
    print("✓ Hook classes available")
    
    # Test the cronjob utils integration
    sys.path.insert(0, 'src')
    from django_cronjob_utils.hooks import HOOKS_AVAILABLE
    print(f"✓ Hooks enabled in cronjob-utils: {HOOKS_AVAILABLE}")
    
except Exception as e:
    print(f"✗ Error: {e}")
    sys.exit(1)
PYEOF
```

---

## �� Test Results

### With django-package-hooks installed:
```
Ran 182 tests in 1.392s
OK
```
- 157 core functionality tests ✓
- 25 hook integration tests ✓

### Without django-package-hooks:
```
Ran 157 tests in 1.250s  
OK (skipped=25)
```
- 157 core functionality tests ✓
- 25 hook tests automatically skipped

---

## 🐛 Troubleshooting

### "No module named 'django_package_hooks'"
```bash
# Install it
pip3 install --user -e ../django-package-hooks

# Verify
python3 -c "import django_package_hooks"
```

### "Permission denied"
```bash
# Use --user flag (no sudo needed)
pip3 install --user -e ../django-package-hooks
```

### Tests fail with ImportError
```bash
# Make sure DJANGO_SETTINGS_MODULE is set
export DJANGO_SETTINGS_MODULE=tests.settings

# Check Django is installed
python3 -c "import django; print(django.VERSION)"
```

---

## 📁 Project Structure

```
django-cronjob-utils/
├── src/django_cronjob_utils/
│   ├── base.py              # Core CronTask class
│   ├── hooks.py             # Hook integration
│   └── models.py            # Database models
├── tests/
│   ├── test_base.py         # Core functionality tests (68 tests)
│   ├── test_hooks.py        # Hook integration tests (25 tests)
│   ├── test_management_command.py  # CLI tests (38 tests)
│   └── test_notifications.py      # Notification tests (51 tests)
├── docs/
│   ├── hooks.md             # Hook system documentation
│   ├── testing.md           # This guide (detailed version)
│   └── usage.md             # Usage guide
└── examples/
    └── cronjob_hooks.py     # Example hook implementations
```

---

## 🔗 Quick Links

- **Detailed Testing Guide**: [docs/testing.md](docs/testing.md)
- **Hook Documentation**: [docs/hooks.md](docs/hooks.md)
- **Usage Guide**: [docs/usage.md](docs/usage.md)
- **Hook Examples**: [examples/cronjob_hooks.py](examples/cronjob_hooks.py)

---

## ✨ What's New

The hooks system allows you to:
- ✅ **PRE hooks**: Reject task execution based on conditions (e.g., dependencies)
- ✅ **POST hooks**: React to execution results (logging, metrics, notifications)
- ✅ **Priority system**: Control execution order
- ✅ **Metadata sharing**: Pass data between hooks
- ✅ **Error handling**: Structured error codes

Example:
```python
from django_cronjob_utils import get_global_cronjob_hook_manager
from django_package_hooks import HookType, HookRejectionError

def check_dependency(context):
    if not dependency_completed():
        raise HookRejectionError(
            code="DEPENDENCY_NOT_MET",
            message="Required task not completed"
        )

manager = get_global_cronjob_hook_manager()
manager.registry.register('cronjob.execute', HookType.PRE, check_dependency)
```

---

Made with ❤️ for robust Django cronjob management