@m4l/testing 0.0.23 → 1.0.1

package/types/packages/testing/mocks/src/types.d.ts

@@ -0,0 +1,233 @@
+import type { BrowserHistory } from 'history';
+export type TestCallback<T = unknown> = (...args: unknown[]) => T;
+export type ToasterFixture = TestCallback<number> & {
+    error: TestCallback<number>;
+    info: TestCallback<number>;
+    success: TestCallback<number>;
+    warning: TestCallback<number>;
+};
+export interface HostToolsFixture {
+    events_add_listener: TestCallback;
+    events_emit: TestCallback;
+    events_remove_listener: TestCallback;
+    history: BrowserHistory;
+    startProgress: TestCallback;
+    stopProgress: TestCallback;
+    toast: ToasterFixture;
+}
+export interface HostToolsFixtureOverrides {
+    events_add_listener?: TestCallback;
+    events_emit?: TestCallback;
+    events_remove_listener?: TestCallback;
+    history?: BrowserHistory;
+    startProgress?: TestCallback;
+    stopProgress?: TestCallback;
+    toast?: ToasterFixture;
+}
+export interface EnvironmentFixture {
+    isLocalhost: boolean;
+    host: string;
+    database: string;
+    domain_token: string;
+    domainToken: string;
+    host_api_local: string;
+    hostApiLocal: string;
+    host_api_remote: string;
+    hostApiRemote: string;
+    hostRemote: string;
+    hostApiIcons: string;
+    host_static_assets: string;
+    environment_assets: string;
+    isIsolatation: boolean;
+    isMicroFrontend: boolean;
+    getModuleUrlIconAsset: () => string;
+}
+export interface UseEnvironmentValueFixture {
+    host_static_assets: string;
+    environment_assets: string;
+    host_api_local: string;
+    hostApiLocal: string;
+    host_api_remote: string;
+    hostApiRemote: string;
+    domain_token: string;
+    domainToken: string;
+    hostRemote: string;
+    hostApiIcons: string;
+}
+export interface UseModuleDictionaryValueFixture {
+    getLabel: (key: string, value?: string) => string;
+    getModuleLabel: () => string;
+}
+export interface CreateUseModuleDictionaryValueFixtureOptions {
+    fallbackToKey?: boolean;
+    getLabel?: (key: string, value?: string) => string;
+    labels?: Record<string, string>;
+    moduleLabel?: string;
+}
+export interface ModuleDictionaryFixture {
+    data: Record<string, string>;
+    [section: string]: Record<string, string>;
+}
+export interface PrivilegesResponseFixture {
+    data: Record<string, boolean>;
+}
+export interface DomainFixture {
+    data: {
+        name: string;
+        company_logo_small_url: string;
+        company_logo_normal_url: string;
+    };
+}
+export interface DomainCountryFixture {
+    id: number;
+    currency: string;
+    currency_decimal_digits: number;
+    decimal_symbol: string;
+    thousands_symbol: string;
+}
+export interface UserPreferencesMagnitudeUnitFixture {
+    id: string;
+    symbol: string;
+}
+export interface UserPreferencesMagnitudeFactorFixture {
+    factorX0: number;
+    factorX1: number;
+    factorX2: number;
+}
+export interface UserPreferencesMagnitudePropertyFixture {
+    baseMagnitudeId: string;
+    id: string;
+    magnitudeUnitBase: UserPreferencesMagnitudeUnitFixture;
+    magnitudeUnitUser: UserPreferencesMagnitudeUnitFixture;
+    factor: UserPreferencesMagnitudeFactorFixture;
+}
+export interface UserPreferencesTimeZoneFixture {
+    id: number;
+    name: string;
+    title?: string;
+    baseOffset: number;
+    dstOffset: number;
+    countryCode?: string;
+}
+export interface UserPreferencesFixture {
+    decimalSymbol: string;
+    thousandsSymbol: string;
+    dateFormat: string;
+    timeFormat: string;
+    timeZone: UserPreferencesTimeZoneFixture | null;
+    locale: string | null;
+    magnitudesSystemId: number | null;
+    properties: UserPreferencesMagnitudePropertyFixture[];
+    currency: string;
+    currencyDecimalDigits: number;
+}
+export interface UserPreferencesMagnitudePropertySelectorFixture {
+    propertyId?: string;
+    baseMagnitudeId?: string;
+}
+export interface ResolveNumberPresentationFixtureOptions {
+    value: number | null | undefined;
+    fallbackValue: string;
+    fractionDigits?: number;
+    formatValue?: (value: number) => string;
+}
+export interface ResolveMagnitudePresentationFixtureOptions extends UserPreferencesMagnitudePropertySelectorFixture {
+    baseValue: number | null | undefined;
+    fallbackSymbol?: string;
+    fallbackValue: string;
+    fractionDigits?: number;
+    formatValue?: (value: number) => string;
+}
+export interface UserPreferencesContextValueFixture extends UserPreferencesFixture {
+    changeUserPreferences: (newUserPreferences: UserPreferencesFixture) => void;
+    getMagnitudeProperty: (selector: UserPreferencesMagnitudePropertySelectorFixture) => UserPreferencesMagnitudePropertyFixture | undefined;
+    formatNumber: (options: ResolveNumberPresentationFixtureOptions) => string;
+    convertMagnitude: (options: ResolveMagnitudePresentationFixtureOptions) => {
+        source: 'fallback' | 'user-preference';
+        symbol?: string;
+        value: string;
+    };
+}
+export interface UserPreferencesApiDataFixture {
+    locale: {
+        id: string;
+        lang: string;
+        region: string | null;
+        script: string;
+        name: string;
+        url_icon: string;
+    } | null;
+    time_zone: {
+        id: number;
+        name: string;
+        title?: string;
+        base_offset: number;
+        dst_offset: number;
+        country_code?: string;
+    } | null;
+    magnitudes_system: {
+        id: number;
+        name: string;
+    } | null;
+    properties: Array<{
+        base_magnitude_id: string;
+        id: string;
+        value: {
+            magnitude_unit_base: UserPreferencesMagnitudeUnitFixture;
+            magnitude_unit_user: UserPreferencesMagnitudeUnitFixture;
+            factor: {
+                factor_x0: number;
+                factor_x1: number;
+                factor_x2: number;
+            };
+        };
+    }>;
+    date_format: {
+        id: number;
+        format: string;
+        name: string;
+    };
+    time_format: {
+        id: number;
+        format: string;
+        name: string;
+    };
+    decimal_symbol: string;
+    thousands_symbol: string;
+    currency: string;
+    currency_decimal_digits: number;
+}
+export interface AxiosOperationResultFixture {
+    data: {
+        a: number;
+        b: string;
+    };
+}
+export interface NetworkRequestFixture {
+    method: string;
+    endPoint: string;
+    parms: Record<string, unknown>;
+}
+export interface BaseProviderValueFixture {
+    a: string;
+    b: number;
+}
+export interface FormatterValuesFixture {
+    currencyFormatter: {
+        decimalDigits: number;
+        code: string;
+    };
+    numberFormatter: {
+        decimalSymbol: string;
+        thousandsSymbol: string;
+    };
+    dateFormatter: {
+        dateFormat: string;
+        dateMask: string;
+        datetimeFormat: string;
+        datetimeMask: string;
+        timeFormat: string;
+        timeMask: string;
+        formatDate: (...args: Parameters<typeof import('date-fns').format>) => ReturnType<typeof import('date-fns').format>;
+    };
+}

package/types/packages/testing/playwright/src/fixtures/createHostAreaFixture.d.ts

@@ -0,0 +1,5 @@
+import type { HostAreaFixture } from '../types';
+/**
+ * Build a deterministic area summary for authenticated host-shell tests.
+ */
+export declare function createHostAreaFixture(overrides?: Partial<HostAreaFixture>): HostAreaFixture;

package/types/packages/testing/playwright/src/fixtures/createHostAuthenticatedMfMenuFixture.d.ts

@@ -0,0 +1,5 @@
+import type { CreateHostAuthenticatedMfMenuFixtureOptions, HostMenuItemFixture } from '../types';
+/**
+ * Build the minimal authenticated host menu tree required to launch one MF.
+ */
+export declare function createHostAuthenticatedMfMenuFixture(options: CreateHostAuthenticatedMfMenuFixtureOptions): HostMenuItemFixture[];

package/types/packages/testing/playwright/src/fixtures/createHostAuthenticatedMfModuleDictionaryFixture.d.ts

@@ -0,0 +1,5 @@
+import type { CreateHostAuthenticatedMfModuleDictionaryFixtureOptions, HostModuleDictionaryFixture } from '../types';
+/**
+ * Build the standard module-dictionary payload used by authenticated MF preview flows.
+ */
+export declare function createHostAuthenticatedMfModuleDictionaryFixture(options: CreateHostAuthenticatedMfModuleDictionaryFixtureOptions): HostModuleDictionaryFixture;

package/types/packages/testing/playwright/src/fixtures/createHostAuthenticatedSessionFixture.d.ts

@@ -0,0 +1,6 @@
+import type { HostAuthenticatedSessionFixture, HostAuthenticatedSessionUserFixture } from '../types';
+/**
+ * Build a deterministic authenticated session response for host platform
+ * flows.
+ */
+export declare function createHostAuthenticatedSessionFixture(overrides?: Partial<HostAuthenticatedSessionUserFixture>): HostAuthenticatedSessionFixture;

package/types/packages/testing/playwright/src/fixtures/createHostCookieFixture.d.ts

@@ -0,0 +1,5 @@
+import type { HostCookieFixture } from '../types';
+/**
+ * Build a deterministic cookie record for authenticated host-shell tests.
+ */
+export declare function createHostCookieFixture(overrides?: Partial<HostCookieFixture>): HostCookieFixture;

package/types/packages/testing/playwright/src/fixtures/createHostGuestSessionFixture.d.ts

@@ -0,0 +1,5 @@
+import type { HostGuestSessionFixture } from '../types';
+/**
+ * Build a deterministic unauthenticated session response for host guest flows.
+ */
+export declare function createHostGuestSessionFixture(overrides?: Partial<HostGuestSessionFixture>): HostGuestSessionFixture;

package/types/packages/testing/playwright/src/fixtures/createHostLocaleFixture.d.ts

@@ -0,0 +1,5 @@
+import type { HostLocaleFixture } from '../types';
+/**
+ * Build a deterministic locale payload for host bootstrap tests.
+ */
+export declare function createHostLocaleFixture(overrides?: Partial<HostLocaleFixture>): HostLocaleFixture;

package/types/packages/testing/playwright/src/fixtures/createHostMfPreviewDynamicParamsFixture.d.ts

@@ -0,0 +1,5 @@
+import type { CreateHostMfPreviewDynamicParamsFixtureOptions, HostMfPreviewDynamicParamsFixture } from '../types';
+/**
+ * Build shared dynamic parameters for authenticated MF preview scenarios.
+ */
+export declare function createHostMfPreviewDynamicParamsFixture(options?: CreateHostMfPreviewDynamicParamsFixtureOptions): HostMfPreviewDynamicParamsFixture;

package/types/packages/testing/playwright/src/fixtures/createHostModuleDictionaryFixture.d.ts

@@ -0,0 +1,11 @@
+import type { HostModuleDictionaryFixture } from '../types';
+export interface CreateHostModuleDictionaryFixtureOptions {
+    data?: Record<string, string>;
+    sections?: Record<string, Record<string, string>>;
+}
+/**
+ * Build a deterministic module-dictionary payload for host no-auth/auth shells.
+ * Keep feature-specific dictionary contents local to the consuming app E2E
+ * project when the labels do not model a reusable host-shell contract.
+ */
+export declare function createHostModuleDictionaryFixture(options?: CreateHostModuleDictionaryFixtureOptions): HostModuleDictionaryFixture;

package/types/packages/testing/playwright/src/fixtures/createHostUiConfigFixture.d.ts

@@ -0,0 +1,7 @@
+import type { HostUIConfigFixture } from '../types';
+/**
+ * Build a deterministic UI-config payload for host bootstrap tests.
+ * Keep app-specific labels and selectors local; share only the host-shell
+ * contract that multiple E2E projects can consume.
+ */
+export declare function createHostUiConfigFixture(overrides?: Partial<HostUIConfigFixture>): HostUIConfigFixture;

package/types/packages/testing/playwright/src/fixtures/createHostUserPreferencesFixture.d.ts

@@ -0,0 +1,6 @@
+import type { HostUserPreferencesFixture } from '../types';
+/**
+ * Build a deterministic authenticated user-preferences payload for host-style
+ * preview bootstrap flows.
+ */
+export declare function createHostUserPreferencesFixture(overrides?: Partial<HostUserPreferencesFixture>): HostUserPreferencesFixture;

package/types/packages/testing/playwright/src/fixtures/createListResponseFixture.d.ts

@@ -0,0 +1,6 @@
+import type { CreateListResponseFixtureOptions, ListResponseFixture } from '../types';
+/**
+ * Build the deterministic `{ data, pager }` envelope returned by GClick list
+ * endpoints, filling pager defaults so any list E2E can mock rows with one call.
+ */
+export declare function createListResponseFixture<TRow>(options: CreateListResponseFixtureOptions<TRow>): ListResponseFixture<TRow>;

package/types/packages/testing/playwright/src/fixtures/index.d.ts

@@ -0,0 +1,12 @@
+export * from './createHostAreaFixture';
+export * from './createListResponseFixture';
+export * from './createHostAuthenticatedMfModuleDictionaryFixture';
+export * from './createHostAuthenticatedMfMenuFixture';
+export * from './createHostAuthenticatedSessionFixture';
+export * from './createHostCookieFixture';
+export * from './createHostGuestSessionFixture';
+export * from './createHostLocaleFixture';
+export * from './createHostMfPreviewDynamicParamsFixture';
+export * from './createHostModuleDictionaryFixture';
+export * from './createHostUiConfigFixture';
+export * from './createHostUserPreferencesFixture';

package/types/packages/testing/playwright/src/helpers/attachJson.d.ts

@@ -0,0 +1,9 @@
+import type { TestInfo } from '@playwright/test';
+/**
+ * Attach one JSON payload to the current Playwright report entry.
+ *
+ * @param testInfo Current Playwright metadata used to persist attachments.
+ * @param name Stable attachment name shown in the HTML report.
+ * @param data Serializable payload written as formatted JSON.
+ */
+export declare function attachJson(testInfo: TestInfo, name: string, data: unknown): Promise<void>;

package/types/packages/testing/playwright/src/helpers/formAccess.d.ts

@@ -0,0 +1,53 @@
+import type { Locator, Page } from '@playwright/test';
+/**
+ * A form scope is either the whole page or a managed-window locator. The add/edit
+ * preview renders a single form, so scoping to the page is the safe default.
+ */
+export type FormScope = Page | Locator;
+/**
+ * Locate the add/edit form container — the RHF `formContainer` region every
+ * `RHFormProvider` + `FormContainer` form renders once it finishes loading.
+ *
+ * Generic and reusable across ALL add/edit modules: the region accessible name
+ * is fixed by the shared `FormContainer` component, so no per-module config is
+ * needed. Its presence is the canonical "the form rendered correctly" signal.
+ */
+export declare function getFormContainer(scope: FormScope): Locator;
+/**
+ * Locate a form field by its react-hook-form `name`, scoped to the form container.
+ *
+ * Generic and reusable across ALL add/edit modules: RHF binds every control to a
+ * functional `name` attribute (`firstName`, `email`, `canReceiveAlarms`, …) that the
+ * form needs at runtime, so it **survives the production bundle** (unlike
+ * `data-testid`) and is stable regardless of the field's label or order. Scoping to
+ * the form container avoids matching host-shell inputs that share a `name`.
+ *
+ * Works for text inputs (assert with `toHaveValue`) and checkboxes/switches (assert
+ * with `toBeChecked`).
+ */
+export declare function getFormField(scope: FormScope, name: string): Locator;
+/**
+ * Locate the form actions container — the `actionsContainer` group that holds the
+ * cancel and submit buttons of every add/edit form.
+ */
+export declare function getFormActionsContainer(scope: FormScope): Locator;
+/**
+ * Locate a host toast (the shell's Toastify notification) by a substring of its
+ * text. Submit success/error feedback is shown by the host via `useHostTools().toast`
+ * and rendered as a `role="alert"` outside the MF window — so scope to `page`, not the
+ * form container. The `message` filter disambiguates it from other `alert` nodes.
+ */
+export declare function getToast(scope: FormScope, message: string): Locator;
+/**
+ * Locate the confirm dialog the form raises before abandoning unsaved changes
+ * (cancel / close-with-X on a dirty form) — the shared `WindowConfirm` modal,
+ * rendered as a `role="dialog"`. Scope to `page` (the modal portals to the body).
+ * Click its confirm/cancel button via `.getByRole('button', { name })`.
+ */
+export declare function getFormConfirmDialog(scope: FormScope): Locator;
+/**
+ * Locate a form action button (submit/cancel) by its visible label, scoped to the
+ * form actions container. The label is module/dictionary-driven (e.g. `Create`,
+ * `Save`, `Cancel`), so the caller passes it; the lookup itself is generic.
+ */
+export declare function getFormActionButton(scope: FormScope, label: string): Locator;

package/types/packages/testing/playwright/src/helpers/formSelect.d.ts

@@ -0,0 +1,51 @@
+import type { Locator, Page, Request } from '@playwright/test';
+import { type FormScope } from './formAccess';
+/**
+ * Form select helpers for `RHFAutocomplete` / `RHFAutocompleteAsync` fields.
+ *
+ * Derived from the real components (`packages/components/.../hook-form/RHFAutocompleteAsync`)
+ * and a real consumer (`operative_devices_edit`): the control renders an
+ * `input[role="combobox"]` carrying the react-hook-form `name`; the async variant
+ * loads its options via a GET request on first open (and on a typed, debounced
+ * search); options render as `role="option"` inside a `role="listbox"`; selecting
+ * one sets the input value to the option label.
+ *
+ * NOTE: no add/edit module with a select field has wired these contracts yet, so
+ * the exact endpoint/option shapes must be confirmed against the consuming module
+ * (e.g. `operative_devices_edit`) the first time its E2E adds REQ-FORM-DATA-001/002.
+ */
+/**
+ * Open a form async-select and capture the options request it fires. The async
+ * select fetches options via GET on first open (and again when a search term is
+ * typed). Returns the captured request so the test can assert the options endpoint
+ * was called (REQ-FORM-DATA-001 — "carga de opciones").
+ */
+export declare function openFormSelectAndCaptureRequest(options: {
+    page: Page;
+    /** The react-hook-form `name` of the select field. */
+    name: string;
+    /** Pattern matching the field's options endpoint. */
+    endpointPattern: RegExp;
+    /** Optional search term to type (triggers the search request). */
+    search?: string;
+}): Promise<Request>;
+/**
+ * Locate the options of the currently-open form select dropdown (the `option`s in
+ * the open `listbox`). Scope to `page` (the listbox portals to the body).
+ */
+export declare function getFormSelectOptions(scope: FormScope): Locator;
+/**
+ * Open a form select and choose an option — by its visible label, or the first
+ * option when no label is given. The option is scoped to the open `listbox` and
+ * waited for before clicking (the dropdown can render a frame late). On success the
+ * field shows the chosen label (REQ-FORM-DATA-002 — "selección de valor").
+ */
+export declare function selectFormOption(options: {
+    page: Page;
+    /** The react-hook-form `name` of the select field. */
+    name: string;
+    /** Visible label of the option to choose; defaults to the first option. */
+    optionLabel?: string;
+    /** Type this search term before picking (async selects that filter by input). */
+    search?: string;
+}): Promise<void>;

package/types/packages/testing/playwright/src/helpers/formatFailedChecks.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Minimal failed-check shape accepted by the shared formatter.
+ */
+export interface FailedCheckLike {
+    /** Observed value captured for the failed check. */
+    actual: unknown;
+    /** Stable check key used in diagnostics and attachments. */
+    key: string;
+    /** Human-readable threshold rendered in the failure message. */
+    threshold: unknown;
+}
+/**
+ * Convert failed checks into one readable multiline assertion message.
+ *
+ * @param checks Failed checks that should be rendered for one assertion.
+ * @returns Human-readable text ready to be passed as an `expect(...)` message.
+ */
+export declare function formatFailedChecks<TCheck extends FailedCheckLike>(checks: TCheck[]): string;

package/types/packages/testing/playwright/src/helpers/index.d.ts

@@ -0,0 +1,16 @@
+export * from './attachJson';
+export * from './formAccess';
+export * from './formSelect';
+export * from './formatFailedChecks';
+export * from './listDatagrid';
+export * from './listDetail';
+export * from './listFilter';
+export * from './listStatePersistence';
+export * from './listSort';
+export * from './viewModeDataGrid';
+export * from './openHostAccountMenuModule';
+export * from './openHostMobileSidebarModule';
+export * from './openHostSidebarModule';
+export * from './openHostAuthenticatedMfPreviewModule';
+export * from './realtimePerformanceBrowser';
+export * from './waitForBrowserCondition';