# wallet_utils Test Suite

This directory contains comprehensive unit tests for the `wallet_utils` package.

## Test Organization

Tests are located in `packages/wallet_utils/tests/` 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 package directory

## Running Tests

### Prerequisites

1. Install Django (required for tests):
   ```bash
   pip install django>=3.2
   ```

2. Install the wallet_utils package in editable mode:
   ```bash
   cd packages/wallet_utils
   pip install -e .
   ```

### Running Tests

From the `packages/wallet_utils/tests/` directory:

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

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

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

# Run specific test method
python manage.py test 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 (`test_db.sqlite3`) is created automatically when tests run.

To reset the database:
```bash
rm test_db.sqlite3
python manage.py migrate
```

## 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
- `manage.py` - Django management script for running tests

## 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
   cd packages/wallet_utils/tests
   python manage.py test
   ```
3. **Tests automatically pick up changes** (no reinstall needed for Python code changes)

## Notes

- Tests are excluded from pip install via `pyproject.toml` configuration
- The `tests/` directory is at the same level as `src/`, not inside it
- This ensures tests are accessible during development but excluded from distribution