first

docs/07-testing-plan.md

@@ -0,0 +1,183 @@
+# Testing Plan
+
+## Testing Stack
+
+Initial plan:
+
+- Laravel built-in PHPUnit support as the baseline.
+- Pest may be installed if compatible and preferred after Laravel setup.
+- Factories and seeders for realistic election, hierarchy, user, application, and assignment data.
+- Laravel feature tests for workflows and authorization.
+- Unit tests for business-rule services.
+
+## Test Data Strategy
+
+Factories should cover:
+
+- Election and settings.
+- Bahagian Pilihanraya.
+- Daerah Mengundi.
+- Pusat Mengundi.
+- Saluran Mengundi.
+- Users with roles.
+- Positions.
+- Position quotas.
+- Applications with document states.
+- Staff assignments.
+- Bank verifications.
+- Attendances.
+- Wheelchair allocations and transactions.
+
+Seeders should create:
+
+- Default roles and permissions.
+- Default positions.
+- Sample election.
+- Sample hierarchy.
+- Sample Admin user for local development.
+
+## Feature Tests
+
+Required feature tests:
+
+- Applicant can register during registration period. Implemented in Phase 4.
+- Applicant cannot register after registration period. Implemented in Phase 4.
+- Applicant cannot register without IC and bank statement. Implemented in Phase 4.
+- KP/KPDP can choose KTM only if vacancy exists. KP coverage implemented in Phase 4.
+- KTM cannot register non-KP role. Implemented in Phase 6 by forcing KTM-created applications to KP only.
+- KTM cannot register after registration period. Implemented in Phase 6.
+- PPM can only view own Pusat Mengundi applications. Implemented in Phase 5.
+- PPM cannot approve without required documents. Implemented in Phase 5.
+- Admin can edit after closing only with catatan. Implemented in Phase 7.
+- Admin Kewangan can verify bank account but cannot change assignment. Implemented in Phase 8.
+- PPM can record attendance for own Pusat Mengundi only. Implemented in Phase 10.
+- Excel export creates export log. Implemented in Phase 8 for finance verification export and Phase 10 for attendance detail export.
+
+Additional recommended feature tests:
+
+- Public QR link uses Pusat Mengundi UUID and does not expose internal ID.
+- Duplicate IC is blocked within current election. Implemented in Phase 4.
+- Self-registration is blocked when active KTM-created applicant exists for same IC. Implemented in Phase 4.
+- KTM can delete KTM-created applicant to allow self-registration. Implemented in Phase 6.
+- Admin Kewangan cannot access assignment update routes.
+- Admin Kewangan cannot access Admin management routes. Implemented in Phase 7 for assignment listing.
+- PPM role change before approval is audited. Core assignment/history path implemented in Phase 5.
+- Admin post-closing assignment update creates system note and audit log. Implemented in Phase 7.
+- Sensitive document download requires authorization. PPM-owned document download implemented in Phase 5.
+- Sensitive document download requires authorization. Admin/Admin Kewangan document access implemented in Phase 11.
+- Core domain seeders create sample election hierarchy and dual-role assignment.
+- Admin can create manual application records. Implemented in Phase 7.
+- Admin can create Police/KKM/JKM representative records. JKM create covered in Phase 7 tests.
+- Finance filters for missing bank statement and missing account number. Implemented in Phase 8.
+- Finance export downloads XLSX and creates `export_logs`. Implemented in Phase 8.
+- Admin can create/update wheelchair allocation. Implemented in Phase 9.
+- Wheelchair taken quantity cannot exceed available allocation. Implemented in Phase 9.
+- Wheelchair return quantity cannot exceed outstanding quantity. Implemented in Phase 9.
+- Wheelchair allocation cannot be reduced below outstanding quantity. Implemented in Phase 9.
+- Admin Kewangan cannot access wheelchair management. Implemented in Phase 9.
+- Attendance recording requires active attendance module flag. Implemented in Phase 10.
+- Admin can view attendance dashboard and detail. Implemented in Phase 10.
+- Admin Kewangan cannot access Admin attendance dashboard. Implemented in Phase 10.
+
+## Unit Tests
+
+Required unit tests:
+
+- Vacancy calculation. Implemented in Phase 4 for KTM vacancy service.
+- Registration period checker. Implemented in Phase 4.
+- Role assignment rules.
+- Sensitive data masking. Implemented in Phase 11.
+- Attendance summary calculation. Implemented in Phase 10.
+
+Additional recommended unit tests:
+
+- Public registration blocked/open state with override.
+- KP/KPDP KTM selection eligibility.
+- PPM plus KTM dual-role validation.
+- Bank verification state transition.
+- Export filter serialization.
+
+## Policy and Authorization Tests
+
+Policies should be tested for:
+
+- Admin access to all records.
+- PPM access only to own Pusat Mengundi.
+- KTM access only to own team.
+- Admin Kewangan bank-only access.
+- Public applicant access only to QR routes and own flow.
+
+## Upload Tests
+
+Tests should verify:
+
+- Required documents are enforced for public submission and PPM approval.
+- Invalid MIME type is rejected.
+- Oversized file is rejected.
+- Uploaded IC and bank statement are stored on private disk.
+- Unauthorized users cannot download sensitive documents.
+- Admin can download private uploaded documents. Implemented in Phase 11.
+- Admin Kewangan can download bank statement only. Implemented in Phase 11.
+
+## Export Tests
+
+Tests should verify:
+
+- Export classes return expected headings.
+- Export services apply filters.
+- Export logs are created with generated_by, generated_at, report_type, filters, and file name.
+- Finance export log creation implemented in Phase 8.
+- Admin Kewangan finance export does not include unauthorized placement edit capability.
+
+## Audit Tests
+
+Tests should verify audit entries for:
+
+- Approval/rejection.
+- Role changes.
+- Assignment changes.
+- Document changes.
+- Bank verification.
+- Post-closing Admin edit.
+- Attendance update.
+- Attendance update implemented in Phase 10 through activity log.
+- Wheelchair transaction.
+- Wheelchair transaction audit path implemented in Phase 9 through activity log.
+- Excel export.
+- Document downloads.
+
+## Manual Testing Checklist
+
+Desktop:
+
+- Login and dashboard navigation.
+- Admin CRUD forms.
+- Application review.
+- Exports.
+
+Tablet:
+
+- Navigation.
+- Filters.
+- Review forms.
+- Attendance list.
+
+Mobile:
+
+- Public QR application form.
+- KTM dashboard and KP registration.
+- PPM attendance screen.
+- Stacked list/card views.
+
+## Continuous Quality Checks
+
+Planned commands after implementation exists:
+
+```bash
+php artisan test
+vendor/bin/pint
+vendor/bin/phpstan analyse
+npm.cmd run build
+```
+
+Actual commands may change based on installed packages and Windows shell behavior.