pelagia-portal/Tests/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:

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