@m4l/testing 0.0.23 → 1.0.1

package/types/libs/observability/shared/src/telemetry.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Supported product surfaces that can emit shared telemetry.
+ */
+export type TelemetrySurface = 'host' | 'isolation' | 'mobile';
+/**
+ * Supported runtime kinds used by the shared telemetry contract.
+ */
+export type TelemetryRuntimeKind = 'web' | 'react-native';
+/**
+ * Supported web-only product surfaces.
+ */
+export type WebTelemetrySurface = Extract<TelemetrySurface, 'host' | 'isolation'>;
+/**
+ * Supported mobile-only product surfaces.
+ */
+export type MobileTelemetrySurface = Extract<TelemetrySurface, 'mobile'>;
+/**
+ * Supported module load sources across web and mobile runtimes.
+ */
+export type ModuleLoadSource = 'federation' | 'script-injection' | 'embedded-bundle' | 'native-registry';
+/**
+ * Low-cardinality failure reasons emitted by shared telemetry.
+ */
+export type ModuleLoadFailureReason = 'manifest_fetch_timeout' | 'manifest_fetch_error' | 'script_load_error' | 'bundle_resolve_error' | 'render_function_missing' | 'render_exception' | 'navigation_blocked' | 'swap_race' | 'component_unmounted' | 'unknown';
+/**
+ * Known reasons why one runtime disposed the current module tree.
+ */
+export type ModuleUnmountReason = 'navigation' | 'cleanup' | 'screen-exit' | 'host-dispose';
+/**
+ * Shared context carried by telemetry events across web and mobile.
+ */
+export interface TelemetryContext {
+    /**
+     * Runtime surface that emitted the event.
+     */
+    surface: TelemetrySurface;
+    /**
+     * Runtime technology that emitted the event.
+     */
+    runtimeKind: TelemetryRuntimeKind;
+    /**
+     * Product-specific module identifier when the event is module-scoped.
+     */
+    moduleId?: string;
+    /**
+     * Product-specific deployed module version.
+     */
+    moduleVersion?: string;
+    /**
+     * Stable namespace used by the current runtime to separate module globals.
+     */
+    moduleNamespace?: string;
+    /**
+     * Route name when the runtime owns browser-style routing.
+     */
+    routeName?: string;
+    /**
+     * Screen name when the runtime owns mobile-style navigation.
+     */
+    screenName?: string;
+}
+/**
+ * Web runtime context carried by telemetry emitted from host and isolation surfaces.
+ */
+export interface WebTelemetryContext extends TelemetryContext {
+    /**
+     * Browser-owned surface that emitted the event.
+     */
+    surface: WebTelemetrySurface;
+    /**
+     * Browser runtime technology.
+     */
+    runtimeKind: 'web';
+}
+/**
+ * Mobile runtime context carried by telemetry emitted from React Native surfaces.
+ */
+export interface MobileTelemetryContext extends TelemetryContext {
+    /**
+     * Mobile-owned surface that emitted the event.
+     */
+    surface: MobileTelemetrySurface;
+    /**
+     * React Native runtime technology.
+     */
+    runtimeKind: 'react-native';
+}
+/**
+ * Shared semantic attribute keys used by platform adapters.
+ */
+export declare const telemetryAttributeKeys: {
+    readonly surface: "surface";
+    readonly runtimeKind: "runtime.kind";
+    readonly moduleId: "module.id";
+    readonly moduleVersion: "module.version";
+    readonly moduleNamespace: "module.namespace";
+    readonly loadSource: "load.source";
+    readonly loadAttempt: "load.attempt";
+    readonly loadFailureReason: "load.failure.reason";
+    readonly routeName: "route.name";
+    readonly screenName: "screen.name";
+    readonly fromModuleId: "swap.from_module.id";
+    readonly toModuleId: "swap.to_module.id";
+    readonly unmountReason: "module.unmount.reason";
+};
+type ModuleTelemetryContext<TContext extends TelemetryContext> = TContext & {
+    moduleId: string;
+};
+type VersionedModuleTelemetryContext<TContext extends TelemetryContext> = ModuleTelemetryContext<TContext> & {
+    moduleVersion: string;
+};
+/**
+ * Shared telemetry event family emitted across module load and swap lifecycles.
+ */
+export type TelemetryEventFor<TContext extends TelemetryContext> = {
+    type: 'module_load_started';
+    context: ModuleTelemetryContext<TContext>;
+    loadSource: ModuleLoadSource;
+    attempt: number;
+} | {
+    type: 'module_load_succeeded';
+    context: VersionedModuleTelemetryContext<TContext>;
+    loadSource: ModuleLoadSource;
+    attempt: number;
+    totalDurationMs: number;
+    resolveDurationMs: number;
+    loadDurationMs: number;
+    mountDurationMs: number;
+} | {
+    type: 'module_load_failed';
+    context: ModuleTelemetryContext<TContext>;
+    loadSource: ModuleLoadSource;
+    attempt: number;
+    totalDurationMs: number;
+    failureReason: ModuleLoadFailureReason;
+    failureDetail?: string;
+} | {
+    type: 'module_load_fallback_activated';
+    context: ModuleTelemetryContext<TContext>;
+    fromLoadSource: ModuleLoadSource;
+    toLoadSource: ModuleLoadSource;
+    reason: string;
+} | {
+    type: 'module_swap_started';
+    context: TContext;
+    fromModuleId: string;
+    toModuleId: string;
+} | {
+    type: 'module_swap_succeeded';
+    context: TContext;
+    fromModuleId: string;
+    toModuleId: string;
+    totalDurationMs: number;
+} | {
+    type: 'module_swap_failed';
+    context: TContext;
+    fromModuleId: string;
+    toModuleId: string;
+    totalDurationMs: number;
+    failureReason: ModuleLoadFailureReason;
+    failureDetail?: string;
+} | {
+    type: 'module_unmounted';
+    context: ModuleTelemetryContext<TContext>;
+    reason?: ModuleUnmountReason;
+};
+/**
+ * Platform-neutral telemetry events accepted by shared adapters.
+ */
+export type TelemetryEvent = TelemetryEventFor<TelemetryContext>;
+/**
+ * Web-only telemetry events accepted by browser adapters.
+ */
+export type WebTelemetryEvent = TelemetryEventFor<WebTelemetryContext>;
+/**
+ * Mobile-only telemetry events accepted by React Native adapters.
+ */
+export type MobileTelemetryEvent = TelemetryEventFor<MobileTelemetryContext>;
+export {};

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

@@ -0,0 +1,10 @@
+/**
+ * Stable module id used by shared testing fixtures that need a deterministic
+ * module identity without coupling the fixture back to one package.
+ */
+export declare const testModuleId = "testing";
+/**
+ * Shared module-name label used by dictionary fixtures when the test only
+ * needs a predictable `module_name` value.
+ */
+export declare const testModuleName = "label_for_module_name";

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

@@ -0,0 +1,258 @@
+import { format } from 'date-fns';
+/**
+ * Baseline module dictionary fixture for tests that only need one predictable
+ * label plus the standard `module_name` field.
+ *
+ * Extend it locally when the feature under test needs more dictionary keys,
+ * but prefer keeping the repeated baseline here instead of rebuilding the
+ * same minimal dictionary shape in many packages.
+ */
+export declare const moduleDictionaryFixture: {
+    data: {
+        module_name: string;
+        label1: string;
+    };
+    comp1: {
+        key1: string;
+    };
+};
+/**
+ * Default privileges query fixture for tests that only need one privilege id.
+ */
+export declare const privilegesQueryFixture: string[];
+/**
+ * Matching privileges response fixture for `privilegesQueryFixture`.
+ *
+ * Use this pair when the test needs deterministic privilege loading data but
+ * the exact privilege names are not the focus of the scenario.
+ */
+export declare const privilegesResponseFixture: {
+    data: {
+        priv1: true;
+    };
+};
+/**
+ * Minimal domain payload for tests that need deterministic company branding
+ * fields without depending on a real backend response.
+ */
+export declare const domainFixture: {
+    data: {
+        name: string;
+        company_logo_small_url: string;
+        company_logo_normal_url: string;
+    };
+};
+/**
+ * Domain-country fixture for zero-decimal currencies.
+ *
+ * Use it when the formatter or business rule under test only needs to know
+ * that the currency rounds to whole numbers.
+ */
+export declare const domainCountryNoDecimalsFixture: {
+    id: number;
+    currency: string;
+    currency_decimal_digits: number;
+    decimal_symbol: string;
+    thousands_symbol: string;
+};
+/**
+ * Domain-country fixture for currencies that keep two decimal places.
+ */
+export declare const domainCountryTwoDecimalsFixture: {
+    id: number;
+    currency: string;
+    currency_decimal_digits: number;
+    decimal_symbol: string;
+    thousands_symbol: string;
+};
+/**
+ * Effective user-preferences fixture shared by test and Storybook harnesses.
+ */
+export declare const userPreferencesFixture: {
+    decimalSymbol: string;
+    thousandsSymbol: string;
+    dateFormat: string;
+    timeFormat: string;
+    timeZone: {
+        id: number;
+        name: string;
+        title: string;
+        baseOffset: number;
+        dstOffset: number;
+        countryCode: string;
+    };
+    locale: string;
+    magnitudesSystemId: number;
+    properties: {
+        baseMagnitudeId: string;
+        id: string;
+        magnitudeUnitBase: {
+            id: string;
+            symbol: string;
+        };
+        magnitudeUnitUser: {
+            id: string;
+            symbol: string;
+        };
+        factor: {
+            factorX0: number;
+            factorX1: number;
+            factorX2: number;
+        };
+    }[];
+    currency: string;
+    currencyDecimalDigits: number;
+};
+/**
+ * Raw `/users/me/preferences` response `data` fixture that mirrors backend casing.
+ */
+export declare const userPreferencesApiDataFixture: {
+    locale: {
+        id: string;
+        lang: string;
+        region: string;
+        script: string;
+        name: string;
+        url_icon: string;
+    };
+    time_zone: {
+        id: number;
+        name: string;
+        title: string;
+        base_offset: number;
+        dst_offset: number;
+        country_code: string;
+    };
+    magnitudes_system: {
+        id: number;
+        name: string;
+    };
+    properties: {
+        base_magnitude_id: string;
+        id: string;
+        value: {
+            magnitude_unit_base: {
+                id: string;
+                symbol: string;
+            };
+            magnitude_unit_user: {
+                id: string;
+                symbol: string;
+            };
+            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;
+};
+/**
+ * Neutral Axios-like result payload for tests that only need a simple `data`
+ * envelope from a network operation.
+ */
+export declare const axiosOperationResultFixture: {
+    data: {
+        a: number;
+        b: string;
+    };
+};
+/**
+ * Deterministic network-request fixture for tests that verify request shaping
+ * rather than endpoint-specific business semantics.
+ */
+export declare const networkRequestFixture: {
+    method: string;
+    endPoint: string;
+    parms: {};
+};
+/**
+ * Full environment fixture for providers or context consumers that require a
+ * complete `EnvironmentType`-compatible object.
+ *
+ * Prefer `createEnvironmentFixture(...)` when the test needs local overrides,
+ * and keep local inline environment objects for truly feature-specific values
+ * only.
+ */
+export declare const environmentFixture: {
+    isLocalhost: true;
+    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: false;
+    isMicroFrontend: false;
+    getModuleUrlIconAsset: () => string;
+};
+/**
+ * Lightweight `useEnvironment()` value fixture for tests that only consume the
+ * commonly read environment fields instead of the full provider contract.
+ *
+ * Use this when mocking `useEnvironment()` directly. For provider values or
+ * stricter contract checks, prefer `environmentFixture` instead.
+ */
+export declare const 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;
+};
+/**
+ * Neutral base-provider payload used by tests that only need a tiny stable
+ * object shape to satisfy generic provider contracts.
+ */
+export declare const baseProviderValueFixture: {
+    a: string;
+    b: number;
+};
+/**
+ * Deterministic formatter values shared by tests that need date, number, or
+ * currency formatting without mounting the real graphics formatter pipeline.
+ */
+export declare const formattersFixture: {
+    currencyFormatter: {
+        decimalDigits: number;
+        code: string;
+    };
+    numberFormatter: {
+        decimalSymbol: string;
+        thousandsSymbol: string;
+    };
+    dateFormatter: {
+        dateFormat: string;
+        dateMask: string;
+        datetimeFormat: string;
+        datetimeMask: string;
+        timeFormat: string;
+        timeMask: string;
+        formatDate: typeof format;
+    };
+};

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

@@ -0,0 +1,44 @@
+import type { EnvironmentFixture, UseEnvironmentValueFixture } from '../types';
+/**
+ * Builds a full environment fixture on top of the shared baseline.
+ *
+ * Use this when the test needs a provider-compatible environment object and
+ * only a few fields differ from the standard workspace baseline.
+ */
+export declare function createEnvironmentFixture(overrides?: Partial<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;
+};
+/**
+ * Builds a lighter `useEnvironment()` return value on top of the shared
+ * baseline.
+ *
+ * Prefer this over `createEnvironmentFixture(...)` when the test mocks the
+ * hook directly and does not need the full `EnvironmentType` contract.
+ */
+export declare function createUseEnvironmentValueFixture(overrides?: Partial<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;
+};

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

@@ -0,0 +1,10 @@
+import type { HostToolsFixture, HostToolsFixtureOverrides } from '../types';
+/**
+ * Builds a neutral host-tools fixture with no-op callbacks and a shared toast
+ * stub.
+ *
+ * Use this when a test needs `useHostTools()` or host-tools provider data but
+ * only cares about one or two callbacks. Override only the members that are
+ * relevant to the scenario.
+ */
+export declare function createHostToolsFixture(overrides?: HostToolsFixtureOverrides): HostToolsFixture;

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

@@ -0,0 +1,5 @@
+export * from './environment';
+export * from './toaster';
+export * from './hostTools';
+export * from './moduleDictionary';
+export * from './userPreferences';

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

@@ -0,0 +1,9 @@
+import type { CreateUseModuleDictionaryValueFixtureOptions, UseModuleDictionaryValueFixture } from '../types';
+/**
+ * Builds a lightweight `useModuleDictionary()` return value for tests that
+ * only need predictable label resolution and a stable module label.
+ *
+ * Prefer this over rebuilding inline `{ getLabel, getModuleLabel }` objects in
+ * each suite. Override only the label behavior that matters to the scenario.
+ */
+export declare function createUseModuleDictionaryValueFixture({ fallbackToKey, getLabel, labels, moduleLabel, }?: CreateUseModuleDictionaryValueFixtureOptions): UseModuleDictionaryValueFixture;

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

@@ -0,0 +1,9 @@
+import type { ToasterFixture } from '../types';
+/**
+ * Creates a deterministic toaster stub whose methods always return stable
+ * numeric ids.
+ *
+ * Use this when the test only needs toast-call observability or a valid toast
+ * object shape without mounting the real toast runtime.
+ */
+export declare function createToasterFixture(): ToasterFixture;

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

@@ -0,0 +1,17 @@
+import type { UserPreferencesApiDataFixture, UserPreferencesContextValueFixture, UserPreferencesFixture, UserPreferencesMagnitudePropertyFixture } from '../types';
+/**
+ * Build one magnitude-property fixture on top of the shared preferences baseline.
+ */
+export declare function createUserPreferencesMagnitudePropertyFixture(overrides?: Partial<UserPreferencesMagnitudePropertyFixture>): UserPreferencesMagnitudePropertyFixture;
+/**
+ * Build one `useUserPreferences()`-compatible fixture with live conversion helpers.
+ */
+export declare function createUserPreferencesContextValueFixture(overrides?: Partial<UserPreferencesFixture>): UserPreferencesContextValueFixture;
+/**
+ * Build one normalized user-preferences fixture with optional overrides.
+ */
+export declare function createUserPreferencesFixture(overrides?: Partial<UserPreferencesFixture>): UserPreferencesFixture;
+/**
+ * Build one raw `/users/me/preferences` API fixture with optional overrides.
+ */
+export declare function createUserPreferencesApiDataFixture(overrides?: Partial<UserPreferencesApiDataFixture>): UserPreferencesApiDataFixture;

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

@@ -0,0 +1,4 @@
+export * from './types';
+export * from './constants';
+export * from './fixtures';
+export * from './helpers';