Hardik a7f3b315c1 Updated directory structure

2026-05-19 10:35:26 +05:30

12 KiB

Raw Blame History

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

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.
Catch regressions introduced by new features before they reach production.
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

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

12 KiB Raw Blame History Unescape Escape