# 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`.