fix failed tests

docs/phpunit_ci_fix_plan_concise (1).md

@@ -0,0 +1,102 @@
+# PHPUnit CI Fix Plan
+
+## Goal
+
+Fix the current PHPUnit CI failures from the latest test run by addressing the shared causes first, then the page-specific failures.
+
+## Priority Fixes
+
+### 1. Fix Test Database Isolation
+
+The feature suite is hitting SQLite lock errors.
+
+- Stop using `database/database.sqlite` as the shared CI test database.
+- Create a unique SQLite database per CI run or per parallel process.
+- Store it under `$RUNNER_TEMP` or another temporary path.
+- Disable parallel tests until each process has its own database.
+- Add SQLite busy timeout only as a backup, not as the main fix.
+
+### 2. Fix Auth and Permission Test Setup
+
+Many tests expect `200`, `201`, or `422` but receive `403`.
+
+- Add shared test helpers:
+  - `actingAsAdmin()`
+  - `actingAsTeacher()`
+  - `actingAsStaff()`
+  - `actingAsParent()`
+  - `actingAsWithPermission($permission)`
+- Make factories create active, verified, non-suspended users by default.
+- Assign required roles and permissions in every feature test.
+- Do not bypass middleware unless the test is not about authorization.
+
+### 3. Fix Missing or Renamed Routes
+
+Some tests call routes that now return `404`.
+
+- Restore or replace `/api/v1/users`.
+- Confirm canonical routes for staff, teacher pages, school-year pages, messages, and parent profile APIs.
+- Update tests only after confirming the new route contract.
+
+### 4. Fix Model Metadata Drift
+
+Many model metadata tests fail after school-year changes.
+
+- Review every model touched by `school_year`.
+- Update `$fillable`, `$casts`, relationships, hidden fields, and table names.
+- Add `school_year` only where the model should directly store it.
+- Update tests to match the intended model contract.
+
+### 5. Fix Factory and Schema Drift
+
+Factories are missing required fields.
+
+- Update `EmailTemplateFactory` to always provide `code`.
+- Update affected tests to use valid required fields.
+- Confirm unique fields and required defaults are consistent across migrations, factories, and tests.
+
+### 6. Fix Section Placement Finalization
+
+Placement finalization fails when the batch record does not exist.
+
+- Create a valid `SectionPlacementBatch` in tests before finalizing.
+- Resolve placement batches by ID and selected `school_year`.
+- Return controlled `404` when the batch is missing.
+
+### 7. Fix Validation Payloads
+
+Some service tests now fail because validation rules changed.
+
+- Update class progress test payloads to include required Islamic Studies units.
+- Confirm whether the rule applies to all progress reports or only specific report types.
+
+## Execution Order
+
+1. Fix SQLite CI database isolation.
+2. Fix user factories and auth helpers.
+3. Fix missing routes.
+4. Fix model metadata tests.
+5. Fix factories with required fields.
+6. Fix section placement batch setup.
+7. Fix changed validation payloads.
+8. Re-run unit tests.
+9. Re-run feature tests.
+10. Fix remaining isolated workflow failures.
+
+## Do Not Chase Yet
+
+These are noisy but not the main cause of the PHPUnit failure:
+
+- Xdebug connection warnings.
+- `mbstring is already loaded`.
+- Action cache checkout warnings.
+- Artifact upload certificate failure after tests fail.
+
+## Acceptance Criteria
+
+- PHPUnit unit suite passes.
+- PHPUnit feature suite passes.
+- No `database is locked` errors.
+- No unexpected `403` caused by missing test permissions.
+- No `404` from expected public/internal API contracts.
+- All school-year-aware tests use only `school_year`, not `school_year_id`.