# Test Plan
## Taiwan NPO Membership Management System

**Last Updated:** 2025-11-20
**Laravel Version:** 11
**Testing Framework:** PHPUnit 10.x

---

## Table of Contents

1. [Testing Strategy](#1-testing-strategy)
2. [Test Environment Setup](#2-test-environment-setup)
3. [Test Coverage Matrix](#3-test-coverage-matrix)
4. [Unit Tests](#4-unit-tests)
5. [Feature Tests](#5-feature-tests)
6. [Running Tests](#6-running-tests)
7. [Test Data](#7-test-data)
8. [Expected Results](#8-expected-results)

---

## 1. Testing Strategy

### 1.1 Testing Pyramid

```
         /\
        /  \
       / E2E\ (Future)
      /______\
     /        \
    / Feature  \
   /____________\
  /              \
 /  Unit Tests    \
/__________________\
```

**Current Focus:**
- ✅ **Unit Tests** - Test individual model methods and business logic
- ✅ **Feature Tests** - Test complete HTTP request/response cycles
- 🟡 **E2E Tests** - Browser tests with Dusk (future enhancement)

### 1.2 Test Types

| Test Type | Purpose | Tools | Coverage Target |
|-----------|---------|-------|-----------------|
| Unit | Test model methods, calculations, business logic | PHPUnit | 80%+ |
| Feature | Test controllers, workflows, integrations | PHPUnit, RefreshDatabase | 70%+ |
| Email | Test email content and delivery | PHPUnit, Mail::fake() | 100% |
| Authorization | Test permissions and middleware | PHPUnit | 100% |
| Database | Test relationships and migrations | PHPUnit, DatabaseMigrations | 100% |

### 1.3 Testing Principles

1. **Isolation:** Each test is independent
2. **Repeatability:** Tests produce same results every time
3. **Speed:** Unit tests < 100ms, Feature tests < 500ms
4. **Clarity:** Clear test names describing what is tested
5. **Coverage:** All critical paths tested

---

## 2. Test Environment Setup

### 2.1 Test Database Configuration

**File:** `phpunit.xml`

```xml
<env name="APP_ENV" value="testing"/>
<env name="DB_CONNECTION" value="sqlite"/>
<env name="DB_DATABASE" value=":memory:"/>
<env name="QUEUE_CONNECTION" value="sync"/>
<env name="MAIL_MAILER" value="array"/>
<env name="CACHE_DRIVER" value="array"/>
<env name="SESSION_DRIVER" value="array"/>
```

### 2.2 Test Traits Used

- `RefreshDatabase` - Migrates and seeds database for each test
- `WithFaker` - Provides Faker instance for generating test data
- `WithoutMiddleware` - Disables middleware (use sparingly)

### 2.3 Setup Commands

```bash
# Install dependencies
composer install

# Copy environment file
cp .env.example .env.testing

# Generate application key
php artisan key:generate --env=testing

# Run migrations
php artisan migrate --env=testing

# Run seeders
php artisan db:seed --env=testing

# Run tests
php artisan test
```

---

## 3. Test Coverage Matrix

### 3.1 Model Coverage

| Model | Unit Test File | Tests | Priority |
|-------|----------------|-------|----------|
| Member | tests/Unit/MemberTest.php | 15 | High |
| MembershipPayment | tests/Unit/MembershipPaymentTest.php | 12 | High |
| Issue | tests/Unit/IssueTest.php | 18 | High |
| Budget | tests/Unit/BudgetTest.php | 10 | Medium |
| BudgetItem | tests/Unit/BudgetTest.php | 8 | Medium |
| FinanceDocument | tests/Unit/FinanceDocumentTest.php | 8 | Medium |
| Transaction | tests/Unit/TransactionTest.php | 6 | Low |

### 3.2 Feature Coverage

| Feature | Feature Test File | Tests | Priority |
|---------|-------------------|-------|----------|
| Member Registration | tests/Feature/MemberRegistrationTest.php | 8 | High |
| Payment Verification | tests/Feature/PaymentVerificationTest.php | 15 | High |
| Finance Documents | tests/Feature/FinanceDocumentTest.php | 10 | High |
| Issue Tracking | tests/Feature/IssueTrackingTest.php | 20 | High |
| Budget Management | tests/Feature/BudgetManagementTest.php | 12 | Medium |
| Authorization | tests/Feature/AuthorizationTest.php | 15 | High |
| Emails | tests/Feature/EmailTest.php | 19 | High |

### 3.3 Coverage Goals

| Category | Target | Current |
|----------|--------|---------|
| Overall Code Coverage | 75% | TBD |
| Model Coverage | 85% | TBD |
| Controller Coverage | 70% | TBD |
| Critical Paths | 100% | TBD |

---

## 4. Unit Tests

### 4.1 MemberTest.php

**File:** `tests/Unit/MemberTest.php`

**Tests:**
1. ✅ Member has required fillable fields
2. ✅ Member belongs to user
3. ✅ Member has many payments
4. ✅ hasPaidMembership() returns true when active with future expiry
5. ✅ hasPaidMembership() returns false when pending
6. ✅ hasPaidMembership() returns false when expired
7. ✅ canSubmitPayment() returns true when pending and no pending payment
8. ✅ canSubmitPayment() returns false when already has pending payment
9. ✅ getPendingPayment() returns pending payment
10. ✅ National ID encryption works
11. ✅ National ID hashing works for search
12. ✅ Status check methods work (isPending, isActive, isExpired, isSuspended)
13. ✅ Status label returns correct Chinese text
14. ✅ Type label returns correct Chinese text
15. ✅ Status badge returns correct CSS class

---

### 4.2 MembershipPaymentTest.php

**File:** `tests/Unit/MembershipPaymentTest.php`

**Tests:**
1. ✅ Payment belongs to member
2. ✅ Payment belongs to submittedBy user
3. ✅ Payment has verifier relationships (cashier, accountant, chair)
4. ✅ Status check methods work (isPending, isApprovedByCashier, etc.)
5. ✅ canBeApprovedByCashier() validates correctly
6. ✅ canBeApprovedByAccountant() validates correctly
7. ✅ canBeApprovedByChair() validates correctly
8. ✅ Status label returns Chinese text
9. ✅ Payment method label returns Chinese text
10. ✅ Receipt file cleanup on deletion
11. ✅ Workflow validation prevents skipping tiers
12. ✅ Rejection tracking works

---

### 4.3 IssueTest.php

**File:** `tests/Unit/IssueTest.php`

**Tests:**
1. ✅ Issue number auto-generation (ISS-YYYY-NNN)
2. ✅ Issue belongs to creator, assignee, reviewer
3. ✅ Issue has many comments, attachments, time logs
4. ✅ Issue has many labels (many-to-many)
5. ✅ Issue has many watchers (many-to-many)
6. ✅ Status check methods work
7. ✅ Workflow validation methods work
8. ✅ Progress percentage calculation
9. ✅ Overdue detection works
10. ✅ Days until due calculation
11. ✅ Total time logged calculation
12. ✅ Status label returns correct text
13. ✅ Priority label returns correct text
14. ✅ Badge color methods work
15. ✅ Scopes work (open, closed, overdue, byStatus, byPriority)
16. ✅ Parent-child relationships work
17. ✅ Can't skip workflow statuses
18. ✅ Can reopen closed issues

---

### 4.4 BudgetTest.php

**File:** `tests/Unit/BudgetTest.php`

**Tests:**
1. ✅ Budget belongs to createdBy and approvedBy
2. ✅ Budget has many budget items
3. ✅ Status check methods work
4. ✅ Workflow validation methods work
5. ✅ Total budgeted income calculation
6. ✅ Total budgeted expense calculation
7. ✅ Total actual income calculation
8. ✅ Total actual expense calculation
9. ✅ Budget item variance calculation
10. ✅ Budget item over-budget detection

---

## 5. Feature Tests

### 5.1 MemberRegistrationTest.php

**File:** `tests/Feature/MemberRegistrationTest.php`

**Tests:**
1. ✅ Public registration form is accessible
2. ✅ Can register with valid data
3. ✅ User and Member records created
4. ✅ User is auto-logged in
5. ✅ Welcome email is sent
6. ✅ Validation fails with invalid email
7. ✅ Validation fails with duplicate email
8. ✅ Password confirmation required

---

### 5.2 PaymentVerificationTest.php

**File:** `tests/Feature/PaymentVerificationTest.php`

**Tests:**
1. ✅ Member can submit payment with receipt
2. ✅ Receipt is stored in private storage
3. ✅ Payment starts with pending status
4. ✅ Submission emails sent to member and cashiers
5. ✅ Cashier can approve (Tier 1)
6. ✅ Cashier approval sends email to accountants
7. ✅ Accountant can approve (Tier 2)
8. ✅ Accountant approval sends email to chairs
9. ✅ Chair can approve (Tier 3)
10. ✅ Chair approval activates membership automatically
11. ✅ Activation email sent to member
12. ✅ Cannot skip tiers (accountant can't approve pending)
13. ✅ Can reject at any tier with reason
14. ✅ Rejection email sent with reason
15. ✅ Dashboard shows correct queues based on permissions

---

### 5.3 FinanceDocumentTest.php

**File:** `tests/Feature/FinanceDocumentTest.php`

**Tests:**
1. ✅ Can create finance document
2. ✅ Can attach file to document
3. ✅ 3-tier approval workflow works
4. ✅ Rejection workflow works
5. ✅ Emails sent at each stage
6. ✅ Cannot skip approval tiers
7. ✅ Can download attachment
8. ✅ Audit log created for each action
9. ✅ Permissions enforced
10. ✅ Validation rules work

---

### 5.4 IssueTrackingTest.php

**File:** `tests/Feature/IssueTrackingTest.php`

**Tests:**
1. ✅ Can create issue
2. ✅ Issue number auto-generated
3. ✅ Can assign issue to user
4. ✅ Assignment email sent
5. ✅ Can update status
6. ✅ Status change email sent
7. ✅ Can add comments
8. ✅ Comment email sent
9. ✅ Can upload attachments
10. ✅ Can download attachments
11. ✅ Can delete attachments
12. ✅ Can log time
13. ✅ Total time calculated correctly
14. ✅ Can add watchers
15. ✅ Watchers receive notifications
16. ✅ Can add labels
17. ✅ Can filter by labels
18. ✅ Can create sub-tasks
19. ✅ Workflow validation works
20. ✅ Overdue detection works

---

### 5.5 BudgetManagementTest.php

**File:** `tests/Feature/BudgetManagementTest.php`

**Tests:**
1. ✅ Can create budget
2. ✅ Can add budget items
3. ✅ Can submit for approval
4. ✅ Can approve budget
5. ✅ Can activate budget
6. ✅ Can close budget
7. ✅ Workflow validation works
8. ✅ Transactions update actual amounts
9. ✅ Variance calculations work
10. ✅ Can link transactions to budget items
11. ✅ Over-budget alerts work
12. ✅ Permissions enforced

---

### 5.6 AuthorizationTest.php

**File:** `tests/Feature/AuthorizationTest.php`

**Tests:**
1. ✅ Admin middleware works
2. ✅ Paid membership middleware works
3. ✅ Cashier permission enforced
4. ✅ Accountant permission enforced
5. ✅ Chair permission enforced
6. ✅ Membership manager permission enforced
7. ✅ Unauthorized users get 403
8. ✅ Role assignment works
9. ✅ Permission inheritance works
10. ✅ Admin role has all permissions
11. ✅ Members cannot access admin routes
12. ✅ Unpaid members cannot access paid resources
13. ✅ Suspended members redirected
14. ✅ Expired members redirected
15. ✅ Guest users redirected to login

---

### 5.7 EmailTest.php

**File:** `tests/Feature/EmailTest.php`

**Tests:**
1. ✅ MemberRegistrationWelcomeMail content
2. ✅ PaymentSubmittedMail (member variant)
3. ✅ PaymentSubmittedMail (cashier variant)
4. ✅ PaymentApprovedByCashierMail
5. ✅ PaymentApprovedByAccountantMail
6. ✅ PaymentFullyApprovedMail
7. ✅ PaymentRejectedMail
8. ✅ MembershipActivatedMail
9. ✅ FinanceDocumentSubmitted
10. ✅ FinanceDocumentApproved*
11. ✅ FinanceDocumentRejected
12. ✅ IssueAssignedMail
13. ✅ IssueStatusChangedMail
14. ✅ IssueCommentedMail
15. ✅ IssueDueSoonMail
16. ✅ IssueOverdueMail
17. ✅ IssueClosedMail
18. ✅ All emails queued correctly
19. ✅ Email recipients correct

---

## 6. Running Tests

### 6.1 Run All Tests

```bash
php artisan test
```

### 6.2 Run Specific Test Suite

```bash
# Unit tests only
php artisan test --testsuite=Unit

# Feature tests only
php artisan test --testsuite=Feature

# Specific test file
php artisan test tests/Unit/MemberTest.php

# Specific test method
php artisan test --filter=test_member_can_submit_payment
```

### 6.3 Run with Coverage

```bash
php artisan test --coverage

# Minimum coverage threshold
php artisan test --coverage --min=75
```

### 6.4 Parallel Testing

```bash
php artisan test --parallel
```

---

## 7. Test Data

### 7.1 TestDataSeeder.php

**File:** `database/seeders/TestDataSeeder.php`

Creates comprehensive test data:
- 5 test users with different roles
- 20 members in various states (pending, active, expired, suspended)
- 30 payments at different approval stages
- 15 issues with various statuses
- 5 budgets with items
- 10 finance documents
- Sample transactions

### 7.2 Using Test Data

```bash
# Seed test data
php artisan db:seed --class=TestDataSeeder --env=testing

# Reset and seed
php artisan migrate:fresh --seed --class=TestDataSeeder --env=testing
```

---

## 8. Expected Results

### 8.1 Success Criteria

All tests pass with:
- ✅ No failures
- ✅ No errors
- ✅ No warnings
- ✅ Coverage > 75%

### 8.2 Test Execution Time

| Test Suite | Expected Time | Acceptable Max |
|------------|---------------|----------------|
| Unit Tests | < 5 seconds | 10 seconds |
| Feature Tests | < 30 seconds | 60 seconds |
| All Tests | < 40 seconds | 90 seconds |

### 8.3 CI/CD Integration

Tests should run automatically on:
- Every commit (via GitHub Actions)
- Every pull request
- Before deployment

**Sample GitHub Actions:**
```yaml
name: Tests

on: [push, pull_request]

jobs:
  tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Install Dependencies
        run: composer install
      - name: Run Tests
        run: php artisan test --coverage --min=75
```

---

## 9. Testing Checklist

Before marking feature as complete:

- [ ] Unit tests written for all model methods
- [ ] Feature tests written for all controller actions
- [ ] Email tests verify content and recipients
- [ ] Authorization tests verify permissions
- [ ] All tests pass
- [ ] Coverage meets minimum threshold (75%)
- [ ] No skipped or incomplete tests
- [ ] Test data seeder updated
- [ ] Documentation updated
- [ ] Edge cases tested
- [ ] Error conditions tested

---

## 10. Test Maintenance

### 10.1 When to Update Tests

- Feature changes
- Bug fixes
- New requirements
- Security updates

### 10.2 Refactoring Tests

Keep tests DRY (Don't Repeat Yourself):
- Use setUp() for common initialization
- Create test helper methods
- Use factories for model creation
- Share fixtures across tests

---

**End of Test Plan**