@futdevpro/fdp-e2e-helpers 1.15.16 → 1.15.19

package/README.md

@@ -39,6 +39,55 @@ user-management.md`).
 - **Server env loader**: `global-env-settings.util.ts` THROWS if
   `E2E_HARD_DELETE_KEY` is set on a production environment.
 
+## `FDP_CWV_Collector_Util` — Core Web Vitals diagnostics
+
+Scripted, synthetic Core Web Vitals (LCP / INP / CLS + attribution) measurement on
+top of Playwright. The reusable Dynamo-level primitive behind the E2E "step-0" CWV
+diagnostic. **Canonical guide:** `documentations/guidelines/development/cwv-diagnostics.md`.
+
+```ts
+import { FDP_CWV_Collector_Util } from '@futdevpro/fdp-e2e-helpers';
+
+// In an e2e spec (consumer supplies the web-vitals IIFE source as a string):
+const result = await FDP_CWV_Collector_Util.collect(page, {
+  routes: [{ path: '/main/home', label: 'Home', interact: async p => { /* real click for INP */ } }],
+  webVitalsScript,                                   // see resolve note below
+  componentPrefixes: ['s-', 'ad-', 'm1-', 'app-'],   // attribution target → component-level
+  budgets: { lcpMs: 2500, inpMs: 200, cls: 0.1 },    // report-only (warn, not fail)
+});
+FDP_CWV_Collector_Util.writeResult(result, 'cwv-result.json');
+// pipeline emits the [CDP_STEP_RESULT] marker AFTER playwright:
+//   node -e "require('@futdevpro/fdp-e2e-helpers').FDP_CWV_Collector_Util.emitMarkerFromFile('cwv-result.json')"
+```
+
+**API**: `collect` / `writeResult` / `emitMarkerFromFile` / `printStepResultMarker` /
+`buildSummaryLine` + pure `rate` / `evaluateBudgets` / `summarizeWorst` / `buildRouteResult`.
+
+**Why the consumer supplies `webVitalsScript` as a string** — this package deliberately
+does NOT import `web-vitals` (keeps it dependency-light + no `require()` in shipped code).
+The consuming e2e project reads the IIFE bundle and passes it in.
+
+> ⚠ **web-vitals v4 `exports`-map gotcha (KÖTELEZŐ olvasni)**: the v4 package has a
+> STRICT `exports` map — it does NOT export `./dist/*` subpaths NOR `./package.json`,
+> so `require.resolve('web-vitals/dist/...')` AND `require.resolve('web-vitals/package.json')`
+> both throw `ERR_PACKAGE_PATH_NOT_EXPORTED`. Resolve an ALLOWED entry point instead and
+> walk to its `dist/`:
+> ```ts
+> const distDir = path.dirname(require.resolve('web-vitals/attribution'));
+> const src = fs.readFileSync(path.join(distDir, 'web-vitals.attribution.iife.js'), 'utf-8');
+> ```
+
+> ⚠ **Playwright `addInitScript` + IIFE `var` gotcha**: the web-vitals IIFE does
+> `var webVitals=...`, but `addInitScript` wraps the script in a function scope, so the
+> top-level `var` never reaches `window`. The collector handles this internally by
+> appending `;self.webVitals=self.webVitals||webVitals;` to the injected script.
+
+**INP note**: synthetic/headless INP is best-effort (Event Timing API unreliable without
+real user input) → often `undefined`. Trustworthy INP comes from the RUM phase. LCP/CLS/FCP/TTFB
+are reliable.
+
+`@playwright/test` is a **peer dependency** (the consuming e2e project already has it).
+
 ## Why stateless `*_Util` (not singleton service)
 
 - Multi-worker parallel-test-safe — no shared instance state across Playwright
@@ -52,6 +101,7 @@ user-management.md`).
 | Layer | Status |
 |---|---|
 | `E2E_HardDelete_Util` (account cascade) | ✅ v01.15.0 |
+| `FDP_CWV_Collector_Util` (Core Web Vitals diag) | ✅ v01.15.14 — live-verified (organizer, 2026-06-01) |
 | `E2E_UserManagerService` lift-up | ⏳ next PR |
 | `E2E_ConfigService` lift-up | ⏳ later |
 | `E2E_UiHelperService` lift-up | ⏳ later (Playwright dep boundary TBD) |

package/build/_models/interfaces/e2e-login-config.interface.d.ts

@@ -0,0 +1,59 @@
+/**
+ * E2E_LoginConfig_Interface — a `E2E_LoginHelperService.setConfig()` bemenete.
+ *
+ * Cel: a helper TARGET-AGNOSTIC. Egy konzument (Overseer, organizer, …) sajat
+ * `e2e-global-setup.ts`-jeben egyszer kitolti a configot az adott rendszer
+ * URL-jevel, route-javal, credentials-evel. A helper NEM ismeri a konzument.
+ *
+ * @see _services/e2e-login-helper.service.ts
+ */
+export interface E2E_LoginConfig_Interface {
+    /**
+     * Host-app base URL — `https://test.overseer.futdevpro.hu` szeru.
+     * NEM tartalmaz path-ot, csak host+protocol.
+     */
+    baseUrl: string;
+    /**
+     * Login route a baseUrl-en belul. Default: `'/'` (a guard-redirect a
+     * login-page-re iranyit). Pontos `/login` is megadhato ha a hostnak nincs
+     * guard-mehanikaja.
+     */
+    loginRoute?: string;
+    /**
+     * A login utan elvart URL regex. Pl. `/test\.overseer/` → barmi a test
+     * overseer hoston (root dashboardra erkezve passol).
+     */
+    postLoginUrlPattern: RegExp;
+    /**
+     * Persistent test-user credentials. `username` ES/VAGY `email` — a
+     * FDPNX_Acc_Login `usernameEmail` mezo barmelyiket elfogadja.
+     */
+    persistentUser: {
+        email?: string;
+        username?: string;
+        password: string;
+    };
+    /**
+     * Selector-override-ok. Default a FDPNX_Acc_Login_Component Forms v2-es
+     * `data-testid`-jeit hasznalja.
+     */
+    testIds?: {
+        /** username input `data-testid`. Default: `'login-username-text'` (Forms v2 TextField testId-pattern). */
+        username?: string;
+        /** password input `data-testid`. Default: `'login-password-password'`. */
+        password?: string;
+        /** submit button name (regex VAGY string). Default: `/Bejelentkezés|Login/`. */
+        submit?: string | RegExp;
+    };
+    /**
+     * Login-POST regex amit a helper `waitForResponse`-pel observal.
+     * Default: `/\/api\/auth\/login/`.
+     */
+    loginApiPattern?: RegExp;
+    /**
+     * sessionStorage kulcs a token-snapshot kinyereshez. Default `'token'`.
+     * Wave-2-ben a FDP_Auth_StorageKey enum hozhatja.
+     */
+    tokenStorageKey?: string;
+}
+//# sourceMappingURL=e2e-login-config.interface.d.ts.map

package/build/_models/interfaces/e2e-login-config.interface.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=e2e-login-config.interface.js.map

package/build/_models/interfaces/e2e-login-result.interface.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `E2E_LoginHelperService.loginWithPersistentUser()` visszateres-shape.
+ *
+ * `alreadyAuthenticated: true` eset:
+ *   A login form NEM jelent meg a configurabilis varakozas alatt → a host
+ *   eleve auth-elt sessiont talalt (pl. storageState reuse). A helper
+ *   ezt NEM tekinti hibanak, csak jelzi.
+ *
+ * Sikeres login-flow eset:
+ *   `loginApiStatus === 200`, `postLoginUrl` a postLoginUrlPattern-rel
+ *   match-elt URL, `token` a sessionStorage kulcsanak erteke.
+ *
+ * @see _services/e2e-login-helper.service.ts
+ */
+export interface E2E_LoginResult_Interface {
+    alreadyAuthenticated?: boolean;
+    loginApiStatus?: number;
+    token?: string | null;
+    postLoginUrl?: string;
+}
+//# sourceMappingURL=e2e-login-result.interface.d.ts.map

package/build/_models/interfaces/e2e-login-result.interface.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=e2e-login-result.interface.js.map

package/build/_services/e2e-login-helper.service.d.ts

@@ -0,0 +1,83 @@
+import { Page } from '@playwright/test';
+import { DyNTS_SingletonService } from '@futdevpro/nts-dynamo';
+import { E2E_LoginConfig_Interface } from '../_models/interfaces/e2e-login-config.interface';
+import { E2E_LoginResult_Interface } from '../_models/interfaces/e2e-login-result.interface';
+/**
+ * `E2E_LoginHelperService` — Playwright login flow helper a FDPNX_Acc_Login_Component
+ * (Forms v2) felulet ellen.
+ *
+ * Target-agnostic: NEM tartalmaz beegetett URL-t, route-ot, vagy creds-et —
+ * a konzument `setConfig()`-pel adja meg a host-app-specifikus ertekeket.
+ * Pattern: singleton, `DyNTS_SingletonService`-bol szarmaztatva (peerDep
+ * `@futdevpro/nts-dynamo`). Lasd `E2E_UserManagerService`-t azonos mintaval.
+ *
+ * Hasznalat (konzument oldalon):
+ * ```typescript
+ * // e2e-global-setup.ts
+ * import { E2E_LoginHelperService } from '@futdevpro/fdp-e2e-helpers';
+ *
+ * E2E_LoginHelperService.getInstance().setConfig({
+ *   baseUrl: process.env.E2E_BASE_URL!,
+ *   loginRoute: '/',
+ *   postLoginUrlPattern: /test\.overseer\.futdevpro\.hu/,
+ *   persistentUser: {
+ *     email: process.env.E2E_PERSISTENT_USER_EMAIL,
+ *     password: process.env.E2E_PERSISTENT_USER_PASSWORD!,
+ *   },
+ * });
+ *
+ * // login-flow.spec.ts
+ * const login = E2E_LoginHelperService.getInstance();
+ * const result = await login.loginWithPersistentUser(page);
+ * expect(result.alreadyAuthenticated || result.loginApiStatus === 200).toBe(true);
+ * ```
+ *
+ * @see _specifications/fdp-login-forms-v2-rollout.md (F3)
+ */
+export declare class E2E_LoginHelperService extends DyNTS_SingletonService {
+    /** Singleton instance getter. */
+    static getInstance(): E2E_LoginHelperService;
+    /** Private constructor — singleton-enforcement. */
+    private constructor();
+    private config;
+    /**
+     * Target-config beallitas. A konzument cycle-elejen egyszer hivja
+     * (`e2e-global-setup.ts`). Tobbszori hivas felulirja a corabbi configot.
+     */
+    setConfig(config: E2E_LoginConfig_Interface): void;
+    /** A jelenleg-aktiv config (testing + introspection). `null` ha nem volt setConfig. */
+    getConfig(): E2E_LoginConfig_Interface | null;
+    /**
+     * Persistent-user login a beallitott config alapjan.
+     *
+     * Skip-modok:
+     *  - `config` nincs allitva → `DyFM_Error` dob.
+     *  - A login form NEM lathato `opts.formVisibleTimeoutMs`-en belul →
+     *    `{ alreadyAuthenticated: true }` (NEM hiba — `setupState reuse` scenario).
+     *
+     * Flow:
+     *  1. `page.goto(baseUrl + loginRoute)`
+     *  2. username + password fill
+     *  3. submit click
+     *  4. `waitForResponse(loginApiPattern)` → loginApiStatus
+     *  5. `waitForURL(postLoginUrlPattern)` → postLoginUrl
+     *  6. `extractToken(page)` → token
+     */
+    loginWithPersistentUser(page: Page, opts?: {
+        /** Login form input megjeleneseig var-as. Default 5000ms. */
+        formVisibleTimeoutMs?: number;
+        /** Login POST response varakozas. Default 20000ms. */
+        loginRespTimeoutMs?: number;
+        /** Post-login URL-redirect varakozas. Default 20000ms. */
+        postLoginUrlTimeoutMs?: number;
+    }): Promise<E2E_LoginResult_Interface>;
+    /**
+     * Token snapshot `sessionStorage`-bol. Default kulcs `'token'` vagy a
+     * configban beallitott `tokenStorageKey`. Konfig-mentes is hasznalhato
+     * (storageKey explicit param-mal).
+     */
+    extractToken(page: Page, storageKey?: string): Promise<string | null>;
+    /** Internal: throw if `setConfig()` nem volt meghivva. */
+    private requireConfig;
+}
+//# sourceMappingURL=e2e-login-helper.service.d.ts.map

package/build/_services/e2e-login-helper.service.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.E2E_LoginHelperService = void 0;
+const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
+const nts_dynamo_1 = require("@futdevpro/nts-dynamo");
+/**
+ * `E2E_LoginHelperService` — Playwright login flow helper a FDPNX_Acc_Login_Component
+ * (Forms v2) felulet ellen.
+ *
+ * Target-agnostic: NEM tartalmaz beegetett URL-t, route-ot, vagy creds-et —
+ * a konzument `setConfig()`-pel adja meg a host-app-specifikus ertekeket.
+ * Pattern: singleton, `DyNTS_SingletonService`-bol szarmaztatva (peerDep
+ * `@futdevpro/nts-dynamo`). Lasd `E2E_UserManagerService`-t azonos mintaval.
+ *
+ * Hasznalat (konzument oldalon):
+ * ```typescript
+ * // e2e-global-setup.ts
+ * import { E2E_LoginHelperService } from '@futdevpro/fdp-e2e-helpers';
+ *
+ * E2E_LoginHelperService.getInstance().setConfig({
+ *   baseUrl: process.env.E2E_BASE_URL!,
+ *   loginRoute: '/',
+ *   postLoginUrlPattern: /test\.overseer\.futdevpro\.hu/,
+ *   persistentUser: {
+ *     email: process.env.E2E_PERSISTENT_USER_EMAIL,
+ *     password: process.env.E2E_PERSISTENT_USER_PASSWORD!,
+ *   },
+ * });
+ *
+ * // login-flow.spec.ts
+ * const login = E2E_LoginHelperService.getInstance();
+ * const result = await login.loginWithPersistentUser(page);
+ * expect(result.alreadyAuthenticated || result.loginApiStatus === 200).toBe(true);
+ * ```
+ *
+ * @see _specifications/fdp-login-forms-v2-rollout.md (F3)
+ */
+class E2E_LoginHelperService extends nts_dynamo_1.DyNTS_SingletonService {
+    /** Singleton instance getter. */
+    static getInstance() {
+        return E2E_LoginHelperService.getSingletonInstance();
+    }
+    /** Private constructor — singleton-enforcement. */
+    constructor() {
+        super();
+    }
+    config = null;
+    /**
+     * Target-config beallitas. A konzument cycle-elejen egyszer hivja
+     * (`e2e-global-setup.ts`). Tobbszori hivas felulirja a corabbi configot.
+     */
+    setConfig(config) {
+        if (!config.baseUrl) {
+            throw new fsm_dynamo_1.DyFM_Error({
+                message: 'E2E_LoginHelperService.setConfig: baseUrl is required',
+                errorCode: 'FDP-E2E-LH-SC-001',
+                issuerService: 'E2E_LoginHelperService',
+            });
+        }
+        if (!config.persistentUser?.password) {
+            throw new fsm_dynamo_1.DyFM_Error({
+                message: 'E2E_LoginHelperService.setConfig: persistentUser.password is required',
+                errorCode: 'FDP-E2E-LH-SC-002',
+                issuerService: 'E2E_LoginHelperService',
+            });
+        }
+        if (!config.persistentUser.email && !config.persistentUser.username) {
+            throw new fsm_dynamo_1.DyFM_Error({
+                message: 'E2E_LoginHelperService.setConfig: persistentUser.email or .username is required',
+                errorCode: 'FDP-E2E-LH-SC-003',
+                issuerService: 'E2E_LoginHelperService',
+            });
+        }
+        this.config = config;
+        fsm_dynamo_1.DyFM_Log.info(`[E2E_LoginHelper] config set: baseUrl=${config.baseUrl}`);
+    }
+    /** A jelenleg-aktiv config (testing + introspection). `null` ha nem volt setConfig. */
+    getConfig() {
+        return this.config;
+    }
+    /**
+     * Persistent-user login a beallitott config alapjan.
+     *
+     * Skip-modok:
+     *  - `config` nincs allitva → `DyFM_Error` dob.
+     *  - A login form NEM lathato `opts.formVisibleTimeoutMs`-en belul →
+     *    `{ alreadyAuthenticated: true }` (NEM hiba — `setupState reuse` scenario).
+     *
+     * Flow:
+     *  1. `page.goto(baseUrl + loginRoute)`
+     *  2. username + password fill
+     *  3. submit click
+     *  4. `waitForResponse(loginApiPattern)` → loginApiStatus
+     *  5. `waitForURL(postLoginUrlPattern)` → postLoginUrl
+     *  6. `extractToken(page)` → token
+     */
+    async loginWithPersistentUser(page, opts = {}) {
+        const config = this.requireConfig();
+        const formVisibleTimeoutMs = opts.formVisibleTimeoutMs ?? 5_000;
+        const loginRespTimeoutMs = opts.loginRespTimeoutMs ?? 20_000;
+        const postLoginUrlTimeoutMs = opts.postLoginUrlTimeoutMs ?? 20_000;
+        const loginRoute = config.loginRoute ?? '/';
+        const usernameTestId = config.testIds?.username ?? 'login-username-text';
+        const passwordTestId = config.testIds?.password ?? 'login-password-password';
+        const submitName = config.testIds?.submit ?? /Bejelentkezés|Login/;
+        const loginApiPattern = config.loginApiPattern ?? /\/api\/auth\/login/;
+        const fullUrl = `${config.baseUrl.replace(/\/+$/, '')}${loginRoute}`;
+        await page.goto(fullUrl, { timeout: 20_000 });
+        // Alreadty-authenticated detection
+        const usernameLocator = page.locator(`[data-testid="${usernameTestId}"]`).first();
+        const visible = await usernameLocator
+            .isVisible({ timeout: formVisibleTimeoutMs })
+            .catch(() => false);
+        if (!visible) {
+            fsm_dynamo_1.DyFM_Log.info('[E2E_LoginHelper] login form not visible → already authenticated');
+            return { alreadyAuthenticated: true };
+        }
+        // Fill creds
+        const userValue = (config.persistentUser.email ?? config.persistentUser.username);
+        await usernameLocator.fill(userValue);
+        await page.locator(`[data-testid="${passwordTestId}"]`).first().fill(config.persistentUser.password);
+        // Wait response + click
+        const loginRespPromise = page.waitForResponse((resp) => loginApiPattern.test(resp.url()) && resp.request().method() === 'POST', { timeout: loginRespTimeoutMs });
+        const submitLocator = typeof submitName === 'string'
+            ? page.locator(`button:has-text("${submitName}")`).first()
+            : page.getByRole('button', { name: submitName }).first();
+        await submitLocator.click();
+        const loginResp = await loginRespPromise;
+        const loginApiStatus = loginResp.status();
+        // Wait for post-login URL
+        await page.waitForURL(config.postLoginUrlPattern, { timeout: postLoginUrlTimeoutMs });
+        const postLoginUrl = page.url();
+        // Snapshot token
+        const token = await this.extractToken(page);
+        return {
+            alreadyAuthenticated: false,
+            loginApiStatus: loginApiStatus,
+            postLoginUrl: postLoginUrl,
+            token: token,
+        };
+    }
+    /**
+     * Token snapshot `sessionStorage`-bol. Default kulcs `'token'` vagy a
+     * configban beallitott `tokenStorageKey`. Konfig-mentes is hasznalhato
+     * (storageKey explicit param-mal).
+     */
+    async extractToken(page, storageKey) {
+        const key = storageKey ?? this.config?.tokenStorageKey ?? 'token';
+        return page.evaluate((k) => sessionStorage.getItem(k), key);
+    }
+    /** Internal: throw if `setConfig()` nem volt meghivva. */
+    requireConfig() {
+        if (!this.config) {
+            throw new fsm_dynamo_1.DyFM_Error({
+                message: 'E2E_LoginHelperService: setConfig() must be called before login operations. '
+                    + 'Add it to your e2e-global-setup.ts.',
+                errorCode: 'FDP-E2E-LH-NCFG-001',
+                issuerService: 'E2E_LoginHelperService',
+            });
+        }
+        return this.config;
+    }
+}
+exports.E2E_LoginHelperService = E2E_LoginHelperService;
+//# sourceMappingURL=e2e-login-helper.service.js.map

package/build/index.d.ts

@@ -3,8 +3,11 @@ export * from './_collections/e2e-unique-generator.util';
 export * from './_collections/fdp-cwv-collector.util';
 export * from './_services/e2e-config.service';
 export * from './_services/e2e-logger.service';
+export * from './_services/e2e-login-helper.service';
 export * from './_services/e2e-user-manager.service';
 export * from './_models/interfaces/e2e-hard-delete-options.interface';
+export * from './_models/interfaces/e2e-login-config.interface';
+export * from './_models/interfaces/e2e-login-result.interface';
 export * from './_models/interfaces/e2e-test-config.interface';
 export * from './_models/interfaces/e2e-user.interface';
 export * from './_models/interfaces/fdp-cwv-run-config.interface';

package/build/index.js

@@ -8,9 +8,12 @@ tslib_1.__exportStar(require("./_collections/fdp-cwv-collector.util"), exports);
 // SERVICES
 tslib_1.__exportStar(require("./_services/e2e-config.service"), exports);
 tslib_1.__exportStar(require("./_services/e2e-logger.service"), exports);
+tslib_1.__exportStar(require("./_services/e2e-login-helper.service"), exports);
 tslib_1.__exportStar(require("./_services/e2e-user-manager.service"), exports);
 // INTERFACES
 tslib_1.__exportStar(require("./_models/interfaces/e2e-hard-delete-options.interface"), exports);
+tslib_1.__exportStar(require("./_models/interfaces/e2e-login-config.interface"), exports);
+tslib_1.__exportStar(require("./_models/interfaces/e2e-login-result.interface"), exports);
 tslib_1.__exportStar(require("./_models/interfaces/e2e-test-config.interface"), exports);
 tslib_1.__exportStar(require("./_models/interfaces/e2e-user.interface"), exports);
 tslib_1.__exportStar(require("./_models/interfaces/fdp-cwv-run-config.interface"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@futdevpro/fdp-e2e-helpers",
-  "version": "01.15.16",
+  "version": "01.15.19",
   "description": "Shared E2E test helpers for FDP-stack apps. First util: E2E_HardDelete_Util. Stateless utility-collection — NOT a framework.",
   "DyBu_settings": {
     "packageType": "shared-package",
@@ -70,8 +70,8 @@
     "HOWTO.md"
   ],
   "peerDependencies": {
-    "@futdevpro/fsm-dynamo": "1.15.16",
-    "@futdevpro/nts-dynamo": "1.15.34",
+    "@futdevpro/fsm-dynamo": "1.15.23",
+    "@futdevpro/nts-dynamo": "1.15.46",
     "@playwright/test": ">=1.49.0"
   },
   "dependencies": {
@@ -80,9 +80,9 @@
     "tslib": "^2.6.2"
   },
   "devDependencies": {
-    "@futdevpro/dynamo-eslint": "1.15.10",
-    "@futdevpro/fsm-dynamo": "1.15.16",
-    "@futdevpro/nts-dynamo": "1.15.34",
+    "@futdevpro/dynamo-eslint": "1.15.12",
+    "@futdevpro/fsm-dynamo": "1.15.23",
+    "@futdevpro/nts-dynamo": "1.15.46",
     "@playwright/test": "^1.49.0",
     "@types/jasmine": "^5.1.5",
     "@typescript-eslint/eslint-plugin": "^8.41.0",