sass-mohfarawati/tests/TEST_PLAN.md

Test Plan — mohfarawati.de

Comprehensive automated test coverage for the multilingual Next.js portfolio + admin workspace. Focus: code correctness. Scope excludes Playwright / browser E2E (per request).

1. Goals & principles

• Cover every application module: pure helpers, validation/schemas, data layer (Prisma), server actions, API routes, middleware, forms, components, and architecture rules.
• Do not change production behaviour. Tests observe the code as-is. If a test reveals a real bug or an architecture-rule violation, it is flagged for the owner — production code is not changed without approval.
• Deterministic and self-contained: no external network, no reliance on a running app server.
• Real Postgres for the data layer (not mocks). See §3.

2. Test taxonomy & runner layout

Vitest with three projects (isolated environments), selected by file location:

Project	Env	Location	Parallel	Purpose
unit	node	tests/unit/**	yes	Pure functions, schemas, formatting, mapping logic
integration	node	tests/integration/**	serial	Prisma data layer, server actions, API routes, middleware
component	jsdom	tests/component/**	yes	React components & forms (RTL)

Legacy flat tests/*.test.ts files are folded into the new structure (kept passing).

Tooling added (dev-only)

• @testing-library/react, @testing-library/dom, @testing-library/jest-dom, @testing-library/user-event, jsdom, @vitejs/plugin-react — component tests.
• @electric-sql/pglite, pglite-prisma-adapter — an embedded real Postgres (Postgres compiled to WASM) that runs the project's actual migrations and Prisma queries in-process, via a Prisma driver adapter.

Database strategy (real Postgres)

tests/helpers/integration-setup.ts + tests/helpers/global-db-setup.ts:

• If TEST_DATABASE_URL is set → the real lib/prisma singleton is used unchanged, pointed at that Postgres (e.g. the Docker instance). The global setup resets the schema and applies every prisma/migrations/*/migration.sql once before the run.
• Otherwise → lib/prisma is mocked (test-only) with a Prisma client backed by an in-process PGlite database. Each worker gets its own isolated database with the migrations applied — real Postgres semantics, no external server, no shared-state races. Production code is never modified.
• resetDb() (TRUNCATE all tables, restart identities) runs in beforeEach.
• The integration project runs serially (fileParallelism: false); each file gets a fresh database connection.

Next.js runtime mocks (integration)

Server actions/middleware depend on the Next runtime. tests/helpers/next-mocks.ts provides:

• next/navigation → redirect() throws a catchable NEXT_REDIRECT carrying the URL.
• next/dist/client/components/redirect-error → isRedirectError() recognises the above.
• next/cache → revalidatePath() spy (no-op, asserted).
• next/headers → controllable cookies() / headers() stores.
• @/lib/admin-auth isAdminAuthenticated → toggled per test (auth guard tests).
• nodemailer → captured transport (no real SMTP).

3. Coverage matrix

3.1 Unit — pure lib

Module	Cases
admin-routing	host resolution (forwarded/comma/port), isAdminHost, hasDedicatedAdminHost, legacy/dev/internal path predicates, toInternalAdminPath, fromDevelopmentAdminPath, getAdminAppPath dev vs prod, buildAdminUrl/buildSiteUrl, env overrides, normalization edge cases
admin-feedback	withFlash (success/error/both/none, encoding), readFlash
admin-navigation	tree shape, active/expanded flags for each section, portfolio child mapping, href de-dup filter
form-data	isCheckedFormValue truthy/falsey set
locale	isSupportedLocale, resolveLocale, getDirection (rtl for ar), stripLocalePrefix, getLocalizedPath(WithDefault) incl. prefix stripping/rebuilding
utils	cn merge/dedupe/conditional
site-theme	buildSiteThemeTokens (hex→hsl, derive dark/secondary, clamps), buildSiteThemeStyleText structure, invalid hex fallback
marquee-settings	defaults, parseMarqueeSettingsValue (invalid json, partial, trims), syncMarqueeSettingsToGermanSource, splitMarqueeRowItems (newline/comma/blank)
site-settings	normalizeSiteDefaultLocale, normalizeSitePrimaryColor, buildDefaultSiteSettings, parseSiteSettingsValue (merge, invalid json, legacy title, invalid locale/color)
site-icons	buildSiteIconUrls (version, relative vs absolute favicon url, name fallback), buildSiteIconResponse transparent fallback for non-managed paths
media-storage (pure)	sanitizeBaseName, getExtensionForMimeType (all mimes + unknown), isManagedMediaFilePath, resolveMediaUploadPath (root confinement + traversal guard)
media-validation	mediaFieldInputSchema: library needs assetId, external needs url, url format rule, upload mode, kind enum, trimming
media-service (pure)	inferMediaKindFromMimeType, inferMediaKindFromFileName, getKindFromUploadFile
portfolio (pure)	resolvePortfolioProjectViewMode, getLocalizedValue (direct/fallback/any)
portfolio-form-progress	slug/year/sortOrder validators, section readiness per type, asset readiness, wizard progress, first incomplete step
portfolio-validation	category/section/asset/project schemas: required fields, slug regex, coercions, view modes, section superRefine per type, media refinements, url rules
metadata	applyTitleTemplateFn, buildLocaleAlternates, buildAppMetadataFromConfig, buildLocalizedMetadataFromConfig (title template skip, description fallback, og/twitter, icons)
mail	createSmtpTransport (required host/user/pass errors, port/secure), sendMail (from with/without name), sendContactMessage (recipient + fallback, body fields), sendTestEmail (recipient fallback, transport reject)

3.2 Integration — data layer (real DB)

Module	Cases
app-config	maintenance get/set, site settings get (fallback name from siteName key) / update roundtrip, mail settings get/update, marquee get/update (german sync), getSiteSettingsMediaBindings (mediaUsage → bindings per field)
media	create asset, get by id (+usages), list, getMediaOptions kind filter, replaceEntityMediaUsages (transactional replace, unique constraint), deleteEntityMediaUsages, getPortfolioMediaBindings routing by usageType, countMediaUsageReferences
portfolio (queries)	admin categories (+project counts), active categories/by-slug, admin projects (status/category filters + ordering), published projects/by-slug, by-id with media bindings, localized mapping, onDelete Restrict/Cascade behaviour
media-service.resolveMediaSelection	library (found/missing), external (creates asset, filename from url), missing+required error, not-required empty
admin-auth (lockout)	registerFailedAdminAttempt increments & locks at threshold, getAdminLockState, resetAdminFailedAttempts, IP hashing via mocked headers; token isPasswordValid/verify with env

3.3 Integration — API routes & middleware

Target	Cases
GET /api/health	200 + database: up; 503 + database: down when query throws
GET /api/site/default-locale	returns runtime defaultLocale + maintenanceEnabled, no-store header
proxy (middleware)	runtime default-locale passthrough, safe fallback on fetch failure, maintenance redirect, SITE_RUNTIME_ORIGIN, admin host rewrite → internal, dev /root handling, legacy 404 in prod, internal path 404 for non-admin in prod, basic-auth challenge/valid

3.4 Integration — server actions

Action file	Cases
contact/actions	valid → sends mail + redirect /success; invalid (short name/bad email/short message) → redirect with error; locale resolution
maintenance/actions	unauth → redirect to admin root; enable/disable toggles config + revalidates + success flash
marquee/actions	unauth guard; empty german rows throw per-row error → error flash; valid → saves (german-synced) + success flash
smtp/actions	parseMailSettingsFormData (port parse error, password retention when blank), save → success; sendTestEmailAction success + failure
site-settings/actions	brand save (primary color normalize, media selection + usage wiring, cleanup on error), localization save (siteName required, title template must contain {pageTitle}), parseJsonObject guard
media/actions	create (kind image/document, missing file error), delete (not found, in-use guard, managed-file removal)
portfolio/actions	upsertCategoryAction create/update + P2002 unique message; deleteCategoryAction blocks when projects exist; saveProjectAction create + update, sections/assets replace, publishedAt first-publish logic, media usage wiring, validation + error cleanup of created media; deleteProjectAction not-found + cascade + usage cleanup

3.5 Component (jsdom + RTL)

Global mocks: framer-motion, gsap, next/link, next/image, next-intl, next/navigation.

Component	Cases
ui/badge	variant classes, custom className merge, passthrough props
ui/input	renders, forwardRef, type/placeholder/disabled, className merge
ui/textarea, ui/label, ui/card, ui/app-card, ui/separator, ui/table	render, props, ref, composition
admin/admin-flash	null when empty, success role=status, error role=alert, both, className
admin/marquee-settings-form	renders 4 rows, default values, submit wiring to action
site/portfolio-category-filter	"all" link + per-category links, active state, localized labels, hrefs
dashboard/dashboard-card, dashboard/stats-card	presentational render, props
layout/container, layout/hero-badge, home/section-heading, home/bento-card	presentational render, children, className

(*multi-part primitives tested for sub-component composition.)

3.6 Architecture-rule tests (tests/integration/architecture)

Enforced from CLAUDE.md:

1. No Prisma in client components — no file containing "use client" imports lib/prisma.
2. Business logic out of UI — components don't import server-only data modules directly (allow-list of pure lib/* view/format helpers).
3. Server actions are guarded — every exported action in app/**/actions.ts calls an auth guard (ensureAdmin/requireAdminAuth) except the public contact action.
4. "use server" directive — every actions.ts begins with "use server".
5. lib/* does not import from app/ — dependency direction.
6. Admin mirror parity — every page.tsx under app/_admin/** has matching re-export stubs under app/root/** and app/admin-internal/** pointing back to _admin.
7. No browser storage in components — no localStorage/sessionStorage usage.

4. Deliverables & running

npm test                         # all projects
npx vitest run --project unit
npx vitest run --project integration
npx vitest run --project component
TEST_DATABASE_URL=postgres://…   # optional: run integration against real Postgres

Findings (real bugs / rule violations) are reported to the owner; production code is only changed after approval.