Initial commit
This commit is contained in:
543
docs/TEST_PLAN.md
Normal file
543
docs/TEST_PLAN.md
Normal file
@@ -0,0 +1,543 @@
|
||||
# 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**
|
||||
Reference in New Issue
Block a user