pelagia-portal/Docs/e2e-test-plan.md

# PPMS — E2E Test Plan

**Version:** 1.0  
**Date:** 2026-05-17  
**Scope:** PPMS portal (`App/pelagia-portal`)  
**Test type:** Browser-level end-to-end (Playwright / Chromium)

---

## 1 · Objectives

1. Verify that each shipped feature behaves correctly from a user's perspective in
   a real browser session against a live Next.js dev server and PostgreSQL database.
2. Catch regressions introduced by new features before they reach production.
3. Document the expected user experience for each role so that future developers
   have a runnable specification, not just written prose.

---

## 2 · Scope

### In scope

- All authenticated portal routes under `/(portal)/`
- Login / logout flows
- Role-based access control (page redirects, element visibility)
- Mobile-specific layout and navigation (375 × 812 viewport)
- API-level gate checks (HTTP status codes on export endpoint)

### Out of scope

- Unit tests for individual components and utilities → `tests/unit/` (Vitest)
- Integration tests for Server Actions and database mutations → `tests/integration/` (Vitest + real DB)
- Email delivery (Resend is console-logged in dev; not browser-testable)
- File storage (R2 is mocked to `.dev-uploads/` in dev)
- GstService GST-number lookup (separate Node.js service; tested independently)
- Visual pixel-perfect regression (not yet implemented)

---

## 3 · Test Environment

| Item | Value |
|---|---|
| Base URL | `http://localhost:3000` |
| App server | Next.js 15 dev server (`pnpm dev`) — auto-started by Playwright webServer config |
| Database | Local PostgreSQL populated with `pnpm db:seed` |
| Browser | Chromium (headless by default) |
| Auth | Fresh login per test using seeded credentials |

**Prerequisite:** run `pnpm db:seed` before the first test run to ensure all users,
vessels, accounts, vendors, and POs are present.

---

## 4 · User Roles Under Test

| Role | Email | Capabilities tested |
|---|---|---|
| TECHNICAL | tech@pelagia.local | Create/submit POs, view status, receipt confirmation |
| MANNING | manning@pelagia.local | Same as TECHNICAL; separate user for isolation |
| ACCOUNTS | accounts@pelagia.local | Payment queue, mark paid, payment history, partial receipt |
| MANAGER | manager@pelagia.local | Approval queue, approve/reject/request-edits, mobile |
| SUPERUSER | superuser@pelagia.local | All manager capabilities + admin read |
| ADMIN | admin@pelagia.local | Admin CRUD pages (users, vendors, vessels, etc.) |
| AUDITOR | auditor@pelagia.local | Desktop Required overlay (non-mobile role) |

---

## 5 · Feature Coverage Matrix

Each row maps a shipped feature (linked to its git commit) to the spec file
that verifies it, the roles exercised, and the current test status.

| # | Feature | Spec File | Roles | Status |
|---|---|---|---|---|
| 1 | PPMS rebrand — login, sidebar, title | `rebrand.spec.ts` | TECH | ✅ Pass |
| 2 | Color-coded PO status badges on dashboard | `dashboard/po-status-badges.js` | TECH, MANAGER | ✅ Pass |
| 3 | Submit for Approval button on DRAFT PO detail | `po-submit-button.spec.ts` | TECH | ⚠️ Selector fix needed |
| 4 | In-app notification bell with unread badge | `notification-bell.spec.ts` | TECH, MANAGER, ACCOUNTS | ✅ Pass |
| 5 | Export gate — PDF/XLSX only on MGR_APPROVED+ | `export-gate.spec.ts` | TECH, MANAGER | ✅ Pass |
| 6 | Approver name as signatory on exported docs | `export-gate.spec.ts` | ACCOUNTS | ✅ Pass |
| 7 | Payment history page at `/payments/history` | `payment-history.spec.ts` | ACCOUNTS, MANAGER, TECH | ✅ Pass |
| 8 | Partial receipt confirmation (per-item delivery) | `partial-receipt.spec.ts` | ACCOUNTS, TECH | ✅ Pass |
| 9 | Auto-verify vendor on first successful payment | `vendor-auto-verify.spec.ts` | ADMIN, ACCOUNTS | ✅ Pass (UI only; full flow skipped) |
| 10 | Bordered buttons on admin pages | `admin-bordered-buttons.spec.ts` | ADMIN | ✅ Pass |
| 11 | User profile page and manager signature | `profile.spec.ts` | TECH, ACCOUNTS, MANAGER, SUPERUSER | ✅ 6/7 pass |
| 12 | Cheapest / ★ Closest tags on inventory items | `inventory/items-tags.spec.ts` | TECH | ✅ Pass |
| 13 | Auto-sort by distance when site is selected | `inventory/items-tags.spec.ts` | TECH | ✅ Pass |
| 14 | Cart icon in header with item count badge | `inventory/cart-icon.spec.ts` | TECH | ✅ Pass |
| 15 | Item and vendor detail pages at `/inventory/…/[id]` | `inventory/cart-icon.spec.ts` | TECH | ✅ Pass |
| 16 | Desktop Required overlay for non-mobile roles | `mobile/desktop-required.spec.ts` | AUDITOR, TECH | ✅ Pass |
| 17 | Manager approval queue as mobile cards | `mobile/manager-approvals.spec.ts` | MANAGER | ✅ Pass |
| 18 | Accounts payment actions on mobile | `mobile/accounts-payments.spec.ts` | ACCOUNTS | ✅ Pass |
| 19 | Sign-out button on Desktop Required overlay | `mobile/desktop-required.spec.ts` | AUDITOR | ✅ Pass |
| 20 | Home tab in mobile bottom navigation | `mobile/bottom-nav.spec.ts` | MANAGER, ACCOUNTS | ✅ Pass |
| 21 | Edit-highlight diff on resubmitted POs | `approvals-edit-highlight.spec.ts` | TECH, MANAGER | ⚡ Flaky |

---

## 6 · Test Case Descriptions

### Feature 1 — PPMS Rebrand

| ID | Description | Expected |
|---|---|---|
| US-1a | Visit `/login` | Page shows text "PPMS" and "Pelagia Payment Management System" |
| US-1a | Visit `/login` | Page does NOT show "Pelagia Portal" |
| US-1b | Log in as any user | Sidebar displays "PPMS" |
| US-1c | Log in as any user | Browser tab title matches `/PPMS/i` |

### Feature 2 — Dashboard Status Badges

| ID | Description | Expected |
|---|---|---|
| US-2a | TECHNICAL logs in, visits `/dashboard` | Each PO row has a visible badge element with a background-color class |
| US-2b | MANAGER logs in, visits `/dashboard` | Same — badges present on manager view |

### Feature 4 — Notification Bell

| ID | Description | Expected |
|---|---|---|
| US-4a | Any user logs in | A bell icon button is visible in the header |
| US-4b | User has unread notifications | A numeric badge or dot is visible on/near the bell |
| US-4c | User clicks the bell | A dropdown/panel appears containing notification items |

### Feature 5 & 6 — Export Gate

| ID | Description | Expected |
|---|---|---|
| US-5a | Visit a DRAFT PO detail page | No "Export PDF" or "Export XLSX" buttons visible |
| US-5b | Visit a MGR_APPROVED PO detail page | Export buttons are visible |
| US-5c | `GET /api/po/[draftId]/export?format=pdf` | HTTP 403 with error JSON |
| US-6a | `GET /api/po/[approvedId]/export?format=xlsx` | HTTP 200, content-type `application/vnd.openxmlformats…` |
| US-6b | `GET /api/po/[approvedId]/export?format=pdf` | HTTP 200, content-type `application/pdf` |

### Feature 7 — Payment History

| ID | Description | Expected |
|---|---|---|
| US-7a | ACCOUNTS visits `/payments/history` | Page loads; shows table or empty-state |
| US-7a | MANAGER visits `/payments/history` | Page loads (MANAGER has `view_all_pos` permission) |
| US-7b | TECHNICAL visits `/payments/history` | Redirected to `/dashboard` |
| US-7b | MANNING visits `/payments/history` | Redirected to `/dashboard` |

### Feature 10 — Admin Bordered Buttons

| ID | Description | Expected |
|---|---|---|
| US-10a | ADMIN visits `/admin/vendors` | Edit and Delete/Deactivate buttons have a CSS class containing `border` |
| US-10b | ADMIN visits `/admin/users` | Same |
| US-10c | ADMIN visits `/admin/vessels` | Same |
| US-10d | ADMIN visits `/admin/accounts` | Same |

### Feature 16–19 — Mobile Experience

| ID | Description | Viewport | Expected |
|---|---|---|---|
| US-16a | AUDITOR logs in | 375 × 812 | "Desktop Required" overlay covers the page |
| US-16a | TECHNICAL logs in | 375 × 812 | "Desktop Required" overlay visible |
| US-16a | MANAGER logs in | 375 × 812 | No overlay — portal content visible |
| US-16a | ACCOUNTS logs in | 375 × 812 | No overlay — portal content visible |
| US-19a | AUDITOR on Desktop Required screen | 375 × 812 | "Sign out" button present in overlay |
| US-19b | AUDITOR clicks "Sign out" | 375 × 812 | Redirected to `/login` |
| US-17a | MANAGER visits `/approvals` | 375 × 812 | PO cards rendered (not a table) |
| US-17b | MANAGER taps a PO card | 375 × 812 | Navigates to `/approvals/[id]` |
| US-17c | MANAGER on `/approvals/[id]` | 375 × 812 | Edit form hidden; Approve/Reject buttons visible |
| US-18a | ACCOUNTS visits `/payments` | 375 × 812 | Payment queue loads; no Desktop Required overlay |
| US-18b | ACCOUNTS sees MGR_APPROVED PO | 375 × 812 | "Start Payment Processing" button visible |
| US-18c | ACCOUNTS sees SENT_FOR_PAYMENT PO | 375 × 812 | Reference input + "Confirm Payment Sent" button visible |

### Feature 20 — Mobile Bottom Navigation

| ID | Description | Viewport | Expected |
|---|---|---|---|
| US-20a | MANAGER logs in | 375 × 812 | Bottom nav has links to `/dashboard`, `/approvals`, `/profile` |
| US-20b | MANAGER taps Home tab | 375 × 812 | Navigates to `/dashboard` |
| US-20c | ACCOUNTS logs in | 375 × 812 | Bottom nav has links to `/dashboard`, `/payments`, `/profile` |
| US-20c | ACCOUNTS taps Home tab | 375 × 812 | Navigates to `/dashboard` |

---

## 7 · Regression Checklist

Run after any change to the following areas:

| Area changed | Specs to run |
|---|---|
| Auth / login / NextAuth config | `auth.spec.ts`, `rebrand.spec.ts` |
| Portal layout (sidebar, header, mobile nav) | `mobile/bottom-nav.spec.ts`, `mobile/desktop-required.spec.ts`, `rebrand.spec.ts` |
| PO state machine / status transitions | `export-gate.spec.ts`, `po-submit-button.spec.ts`, `approvals-edit-highlight.spec.ts` |
| Payment / Accounts flows | `accounts-payment.spec.ts`, `payment-history.spec.ts`, `mobile/accounts-payments.spec.ts` |
| Approval / Manager flows | `manager-approvals.spec.ts`, `mobile/manager-approvals.spec.ts` |
| Admin pages | `admin-bordered-buttons.spec.ts` |
| Inventory / Items | `inventory/items-tags.spec.ts`, `inventory/cart-icon.spec.ts` |
| Profile page | `profile.spec.ts` |
| Notifications | `notification-bell.spec.ts` |
| Export endpoint | `export-gate.spec.ts`, `po-export.spec.ts` |

---

## 8 · Gaps & Future Test Coverage

The following areas are not yet covered by automated E2E tests:

| Gap | Priority | Notes |
|---|---|---|
| Full vendor auto-verify flow (TECH → submit → MANAGER → approve → ACCOUNTS → pay → verify) | Medium | Requires `beforeAll` multi-role setup; skip currently in place |
| PO edit form (`/po/[id]/edit`) — field pre-population | High | `submitter-journey.spec.ts` covers this but currently fails due to selector issue |
| Edits-requested email trigger | Low | Email is console-logged in dev; not directly testable in browser |
| AUDITOR read-only views | Medium | AUDITOR can view all POs; no spec yet |
| Superuser access requests on profile page | Low | UI exists; no spec |
| PDF/XLSX content verification (signature name, PO fields) | Medium | API returns correct status; content inspection not yet asserted |
| MANNING/TECHNICAL Desktop Required overlay | Done | Covered in `desktop-required.spec.ts` |
| Password change flow | Low | Form exists on profile page; not yet exercised |

---

## 9 · Continuous Integration (Planned)

When wired into CI (GitHub Actions), the following configuration applies:

```yaml
# .github/workflows/e2e.yml
- name: Install Playwright browsers
  run: pnpm exec playwright install --with-deps chromium

- name: Run E2E tests
  run: pnpm test:e2e
  env:
    CI: "true"
    DATABASE_URL: ${{ secrets.TEST_DATABASE_URL }}
    NEXTAUTH_SECRET: ${{ secrets.NEXTAUTH_SECRET }}
    NEXTAUTH_URL: "http://localhost:3000"
```

In CI mode (`process.env.CI = "true"`), the config uses:
- `workers: 1` — no concurrency, avoids auth flooding on constrained runners
- `retries: 2` — two retry attempts before marking a test as failed
- `forbidOnly: true` — fails the run if any `test.only` is left in the code