# Test Suite for django-cronjob-utils

This directory contains comprehensive unit tests for the django-cronjob-utils package.

## Test Structure

The test suite is organized into the following test files:

- `test_models.py` - Tests for CronExecution model
- `test_base.py` - Tests for CronTask base class and ExecutionResult
- `test_registry.py` - Tests for TaskRegistry and ExecutionPattern
- `test_locks.py` - Tests for DatabaseLock
- `test_exceptions.py` - Tests for custom exceptions
- `test_notifications.py` - Tests for notification backends (Email, Slack, Telegram)
- `test_decorators.py` - Tests for @register_task decorator
- `test_management_command.py` - Tests for run_cron_task management command

## Setup and Installation

### 1. Create Virtual Environment

```bash
# Navigate to project root
cd /home/cursorai/projects/django-cronjob-utils

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate  # On Linux/Mac
# OR
venv\Scripts\activate  # On Windows
```

### 2. Install Dependencies

```bash
# Install package dependencies
pip install -e .

# Install test dependencies
pip install -r tests/requirements.txt

# Optional: Install pytest if you prefer pytest over Django's test runner
# pip install pytest pytest-django
```

### 3. Run Tests

#### Using Django's Test Runner (Recommended)

```bash
# Run all tests
python manage.py test tests

# Run specific test file
python manage.py test tests.test_models

# Run specific test class
python manage.py test tests.test_models.CronExecutionModelTests

# Run specific test method
python manage.py test tests.test_models.CronExecutionModelTests.test_create_execution

# Run with verbosity
python manage.py test tests --verbosity=2

# Run with coverage (if installed)
coverage run --source='django_cronjob_utils' manage.py test tests
coverage report
coverage html  # Generate HTML report
```

#### Using pytest (Optional)

```bash
# Run all tests
pytest tests/

# Run specific test file
pytest tests/test_models.py

# Run with verbosity
pytest tests/ -v

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

## Test Coverage

The test suite covers:

### Standard Cases
- Model creation and field validation
- Task registration and retrieval
- Successful task execution
- Lock acquisition and release
- Notification sending

### Edge Cases
- Empty/null values
- Very long strings
- Future/past dates
- Multiple concurrent executions
- Missing configuration

### Outlier Cases
- Invalid date formats
- Non-existent tasks
- Network failures in notifications
- Timeout handling
- Exception propagation

## Test Database

Tests use an in-memory SQLite database (`test_db.sqlite3`) that is automatically created and destroyed for each test run. No manual database setup is required.

## Running Tests in CI/CD

For continuous integration, you can use:

```bash
# Install dependencies
pip install -e . -r tests/requirements.txt

# Run tests
python manage.py test tests --verbosity=2

# Or with pytest
pytest tests/ -v --tb=short
```

## Troubleshooting

### Import Errors
If you encounter import errors, make sure:
1. The virtual environment is activated
2. The package is installed in editable mode: `pip install -e .`
3. Django settings module is set: `DJANGO_SETTINGS_MODULE=tests.settings`

### Database Errors
If you see database-related errors:
1. Delete `test_db.sqlite3` if it exists
2. Run migrations: `python manage.py migrate --settings=tests.settings`

### Notification Test Failures
Some notification tests mock external services. If they fail:
1. Check that `requests` library is installed
2. Verify mocks are properly configured
3. Check test isolation (tests should not depend on external services)

## Notes

- Tests are excluded from package distribution via `setup.py` configuration
- All tests use Django's TestCase which provides database transaction rollback
- External services (Slack, Telegram) are mocked to avoid actual API calls
- Email backend uses Django's in-memory backend for testing