usher-manage-stack/docs/TEST_PLAN.md

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
2. Test Environment Setup
3. Test Coverage Matrix
4. Unit Tests
5. Feature Tests
6. Running Tests
7. Test Data
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

<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

# 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

php artisan test

6.2 Run Specific Test Suite

# 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

php artisan test --coverage

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

6.4 Parallel Testing

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

# 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:

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