alrahma_sunday_school_api/docs/phpunit_ci_fix_plan_concise (1).md

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.