# wallet_utils Test Suite

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

## Test Organization

Tests are located in the `tests/` directory at the project root and are **automatically excluded** from package distribution via `pyproject.toml` configuration. This means:

- ✅ Tests are included in the source repository for development
- ✅ Tests are **NOT** included when someone installs the package via `pip install`
- ✅ Tests can be run directly from the project root

## Running Tests

### Prerequisites

1. Install the package in editable mode with test dependencies:
   ```bash
   pip install -e ".[test]"
   ```

2. Run migrations:
   ```bash
   python manage.py migrate
   ```

### Running Tests

From the project root directory:

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

# Run specific test file
python manage.py test tests.test_wallet_service
python manage.py test tests.test_wallet_repository
python manage.py test tests.test_wallet_models
python manage.py test tests.test_exceptions
python manage.py test tests.test_transaction_types

# Run specific test class
python manage.py test tests.test_wallet_service.WalletServiceAddPointTests

# Run specific test method
python manage.py test tests.test_wallet_service.WalletServiceAddPointTests.test_add_point_standard

# Run with verbose output
python manage.py test --verbosity=2
```

### Database Setup

Tests use SQLite (configured in `tests/settings.py`). The database file is created automatically when tests run.

## Test Structure

- `test_wallet_service.py` - Comprehensive tests for WalletService (add_point, deduct_point, transaction history)
- `test_wallet_repository.py` - Tests for WalletRepository implementation
- `test_wallet_models.py` - Tests for Django models (WalletTransaction, AbstractWalletTransaction)
- `test_exceptions.py` - Tests for custom exceptions
- `test_transaction_types.py` - Tests for transaction type constants and helpers
- `models.py` - Test models (TestUser, TestWallet, TestWalletCustomField)
- `settings.py` - Django test settings

## Test Coverage

Tests cover:
- ✅ Standard cases (normal operations)
- ✅ Edge cases (zero amounts, very small/large amounts, exact balance)
- ✅ Error cases (invalid inputs, insufficient balance, reserved fields)
- ✅ Outlier cases (very long remarks, concurrent operations, race conditions)
- ✅ Custom configurations (separate wallet models, custom field names, custom user_id fields)

## Development Workflow

1. **Make code changes** in `src/wallet_utils/`
2. **Run tests** to verify changes:
   ```bash
   python manage.py test
   ```
3. **Tests automatically pick up changes** (no reinstall needed for Python code changes)

## Documentation

For comprehensive testing documentation, including detailed test coverage, CI/CD setup, and best practices, see [docs/testing-wallet-utils.md](../docs/testing-wallet-utils.md).

## Notes

- Tests are excluded from pip install via `pyproject.toml` configuration
- The `tests/` directory is at the project root level
- This ensures tests are accessible during development but excluded from distribution