test(mfa): add model-based UI contract test

Render the real MFA modal navigator, walk the machine graph
(getSimplePaths plus a fixed lifecycle lap), drive each event through
real gestures, and assert the modal/outcome DOM markers at every step.

Group the UI-only helpers under tests/utils/mfa/ui/ (harness, mocks,
eventExecutors, jestMocks); keep the graph path model in
createMfaTestModel and export toStateValue from machineStates for it.

The createTestModel-style harness mirrors path.test({events, states})
on top of xstate/graph because the real createTestModel rejects the
machine's `after` (closeFallback) transition.

Author: dariusz-biela

tests/unit/MultifactorAuthentication/mfaUiModelTest.tsx

@@ -0,0 +1,65 @@
+/* eslint-disable @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-return -- jest.mock factories delegate to require()'d helpers, which resolve as `any`. */
+import {resetMfaNavigation} from '@components/MultifactorAuthentication/mfaNavigation';
+import CONST from '@src/CONST';
+import createMfaTestModel from '../../utils/mfa/createMfaTestModel';
+import mfaEventExecutors from '../../utils/mfa/ui/eventExecutors';
+import {flushMfaUi, isModalOverlayMounted, isOutcomeScreenVisible, renderMfaUi} from '../../utils/mfa/ui/harness';
+import {resetMfaUiMocks} from '../../utils/mfa/ui/mocks';
+
+// Wide layout so the navigator renders the backdrop overlay the assertions use as the mounted marker.
+jest.mock('@hooks/useResponsiveLayout');
+// Dev-only Stately inspector wiring -> the plain @xstate/react adapter the provider needs.
+jest.mock('@hooks/useInspectedMachine', () => require('../../utils/mfa/ui/jestMocks').inspectedMachineMock());
+// Native / WebAuthn biometrics are out of scope for the modal-lifecycle contract.
+jest.mock('@components/MultifactorAuthentication/biometrics/useBiometrics', () => require('../../utils/mfa/ui/jestMocks').biometricsHookMock());
+// Browser/Android back-history wiring is a separate concern from the machine <-> UI contract.
+jest.mock('@components/MultifactorAuthentication/useSyncMfaModalNavigatorWithHistory', () => require('../../utils/mfa/ui/jestMocks').syncHistoryMock());
+// Navigation automock leaves methods undefined; supply the three the flow needs and no-op the rest.
+jest.mock('@libs/Navigation/Navigation', () => require('../../utils/mfa/ui/jestMocks').navigationMock());
+
+const MFA_STATE = CONST.MULTIFACTOR_AUTHENTICATION.MFA_STATE;
+
+const testModel = createMfaTestModel();
+
+// The createTestModel-style config: events map -> UI gesture, states map -> per-state assertion.
+// State keys are dot-path values matched with `matchesState`, so they can target any depth - here the
+// settled success leaf `open.outcome.success` rather than just the `open` parent.
+const testConfig = {
+    events: mfaEventExecutors,
+    states: {
+        [MFA_STATE.CLOSED]: () => {
+            expect(isModalOverlayMounted()).toBe(false);
+            expect(isOutcomeScreenVisible()).toBe(false);
+        },
+        [`${MFA_STATE.OPEN}.${MFA_STATE.OUTCOME}.${MFA_STATE.SUCCESS}`]: () => {
+            expect(isModalOverlayMounted()).toBe(true);
+            expect(isOutcomeScreenVisible()).toBe(true);
+        },
+        [MFA_STATE.CLOSING]: () => {
+            expect(isModalOverlayMounted()).toBe(true);
+            expect(isOutcomeScreenVisible()).toBe(false);
+        },
+    },
+};
+
+describe('mfaMachine driven through the real MFA UI', () => {
+    beforeEach(() => {
+        resetMfaUiMocks();
+        resetMfaNavigation();
+    });
+
+    afterEach(() => {
+        jest.clearAllMocks();
+    });
+
+    // getSimplePaths reaches every state; the lifecycle lap adds the MODAL_CLOSED teardown it skips.
+    const paths = [...testModel.getSimplePaths(), ...testModel.getLifecyclePaths()];
+
+    for (const path of paths) {
+        it(`reaches ${JSON.stringify(path.state.value)} via [${path.description}]`, async () => {
+            renderMfaUi();
+            await flushMfaUi();
+            await path.test(testConfig);
+        });
+    }
+});

tests/utils/mfa/createMfaTestModel.ts

@@ -0,0 +1,108 @@
+import {matchesState} from 'xstate';
+import type {SnapshotFrom} from 'xstate';
+import {getPathsFromEvents, getSimplePaths} from 'xstate/graph';
+import mfaMachine from '@components/MultifactorAuthentication/machine/mfaMachine';
+import type {MfaEvent} from '@components/MultifactorAuthentication/machine/types';
+import {toStateValue} from './machineStates';
+import createInitEvent from './mfaTestFixtures';
+
+/**
+ * A small `createTestModel`-style harness over `xstate/graph`'s plain path generators: each path
+ * exposes `path.test({events, states})`, which replays the path through the real UI (drive the
+ * matching event executor at each step, then run every matching state assertion).
+ *
+ * Why not the real `createTestModel`? Its constructor calls `validateMachine`, which throws "After
+ * events on test machines are not supported", and `mfaMachine.closing` has an `after` (closeFallback)
+ * transition. The plain generators have no such restriction.
+ *
+ * Paths are generated WITHOUT a pinned event list, so the graph synthesizes an event for every
+ * transition the machine declares and auto-discovers new (sub)states as the chart grows. Each step's
+ * `state` is the deepest settled configuration (e.g. `open.outcome.success`), so the `states` map
+ * routes by `matchesState` and can assert at any depth - transient routers (`always`/`initial` such
+ * as `preparing`/`outcome`) are passed through and never become their own node.
+ */
+
+type MfaSnapshot = SnapshotFrom<typeof mfaMachine>;
+
+/** UI action that produces a machine event - an `events` map entry passed to `path.test`. */
+type MfaEventExecutor = () => void | Promise<void>;
+
+/** Assertion run when the walk reaches a matching state - a `states` map entry passed to `path.test`. */
+type MfaStateAssertion = (state: MfaSnapshot) => void | Promise<void>;
+
+type MfaPathTestConfig = {
+    events: Partial<Record<MfaEvent['type'], MfaEventExecutor>>;
+    /** Keyed by dot-path state value (e.g. `open.outcome.success`), matched against each step with `matchesState`. */
+    states: Record<string, MfaStateAssertion>;
+};
+
+type RawPath = {
+    state: MfaSnapshot;
+    steps: ReadonlyArray<{state: MfaSnapshot; event: {type: string}}>;
+};
+
+type MfaTestPath = {
+    /** Final-state snapshot, e.g. for `JSON.stringify(path.state.value)` test names. */
+    state: MfaSnapshot;
+    /** The driven event sequence, e.g. `INIT -> CLOSE_MODAL`. */
+    description: string;
+    /** Walks the path: for each step, runs the matching event executor then asserts every matching state. */
+    test: (config: MfaPathTestConfig) => Promise<void>;
+};
+
+// INIT carries the real scenario payload; CLOSE_MODAL/MODAL_CLOSED are bare. Used only for the explicit
+// teardown lap (getLifecyclePaths); simple paths auto-discover events from the chart.
+const DRIVING_EVENTS: MfaEvent[] = [createInitEvent(), {type: 'CLOSE_MODAL'}, {type: 'MODAL_CLOSED'}];
+const INIT_STEP_EVENT_TYPE = 'xstate.init';
+const DELAYED_EVENT_PREFIX = 'xstate.after';
+
+// Delayed (`after`) transitions are timers, not gestures - drop any path that would need to fire one.
+// The closing -> closed teardown they cover is driven explicitly via MODAL_CLOSED in getLifecyclePaths.
+function isGestureDrivablePath(path: RawPath): boolean {
+    return path.steps.every((step) => !step.event.type.startsWith(DELAYED_EVENT_PREFIX));
+}
+
+async function assertMatchingStates(snapshot: MfaSnapshot, states: MfaPathTestConfig['states']): Promise<void> {
+    for (const [stateValue, assertState] of Object.entries(states)) {
+        if (matchesState(toStateValue(stateValue.split('.')), snapshot.value)) {
+            await assertState(snapshot);
+        }
+    }
+}
+
+function wrapPath(graphPath: RawPath): MfaTestPath {
+    const drivenEventTypes = graphPath.steps.map((step) => step.event.type).filter((type) => type !== INIT_STEP_EVENT_TYPE);
+
+    return {
+        state: graphPath.state,
+        description: drivenEventTypes.length > 0 ? drivenEventTypes.join(' -> ') : '(initial state)',
+        test: async ({events, states}) => {
+            const executorByEventType: Partial<Record<string, MfaEventExecutor>> = events;
+            for (const step of graphPath.steps) {
+                if (step.event.type !== INIT_STEP_EVENT_TYPE) {
+                    const executeEvent = executorByEventType[step.event.type];
+                    if (!executeEvent) {
+                        throw new Error(`No event executor provided for "${step.event.type}"`);
+                    }
+                    await executeEvent();
+                }
+                await assertMatchingStates(step.state, states);
+            }
+        },
+    };
+}
+
+function toTestPaths(rawPaths: RawPath[]): MfaTestPath[] {
+    return rawPaths.filter(isGestureDrivablePath).map(wrapPath);
+}
+
+function createMfaTestModel() {
+    return {
+        getSimplePaths: (): MfaTestPath[] => toTestPaths(getSimplePaths(mfaMachine)),
+        // The full teardown lap (... -> MODAL_CLOSED -> closed) that simple paths skip because it revisits `closed`.
+        getLifecyclePaths: (): MfaTestPath[] => toTestPaths(getPathsFromEvents(mfaMachine, DRIVING_EVENTS)),
+    };
+}
+
+export default createMfaTestModel;
+export type {MfaPathTestConfig, MfaTestPath};

tests/utils/mfa/machineStates.ts

@@ -27,4 +27,5 @@ function getSettleableLeafStates(machine: AnyStateMachine): SettleableLeafState[
 }
 
 export default getSettleableLeafStates;
+export {toStateValue};
 export type {SettleableLeafState};

tests/utils/mfa/ui/eventExecutors.ts

@@ -0,0 +1,46 @@
+import {act, fireEvent, screen} from '@testing-library/react-native';
+import type {MfaEvent} from '@components/MultifactorAuthentication/machine/types';
+import {handleInitialScreenLayout} from '@components/MultifactorAuthentication/mfaNavigation';
+import {MFA_TEST_SCENARIO_NAME} from '../mfaTestFixtures';
+import {flushMfaUi, getMfaControls} from './harness';
+import {pendingModalClose} from './mocks';
+
+type MfaEventType = MfaEvent['type'];
+type MfaEventExecutor = () => Promise<void>;
+
+/** Translated `common.buttonConfirm` shown on the outcome screen's confirm button (and back button). */
+const CONFIRM_BUTTON_TEXT = 'Got it';
+
+/**
+ * The dictionary the model walk drives the real UI with: one entry per machine event, each performing
+ * the gesture (or the system step) that produces that event in production.
+ *
+ * Not every event is a DOM gesture in this slice: `INIT` is fired by an external consumer through the
+ * public API (no button inside the MFA modal starts a flow), and `MODAL_CLOSED` is the navigator's
+ * teardown signal rather than a user action - here we run the exact callback the navigator handed us.
+ * `satisfies Record<MfaEventType, ...>` makes a new machine event a compile error until it gets an executor.
+ */
+/* eslint-disable @typescript-eslint/naming-convention -- keys mirror the machine's event type union. */
+const mfaEventExecutors = {
+    INIT: async () => {
+        await act(async () => {
+            await getMfaControls().executeScenario(MFA_TEST_SCENARIO_NAME);
+        });
+        await flushMfaUi();
+        // The transparent initial screen's onLayout does not fire in jsdom; call the exact handler it
+        // wires so the buffered push to the outcome screen runs, just like a real layout pass.
+        act(() => handleInitialScreenLayout());
+        await flushMfaUi();
+    },
+    CLOSE_MODAL: async () => {
+        fireEvent.press(screen.getByText(CONFIRM_BUTTON_TEXT));
+        await flushMfaUi();
+    },
+    MODAL_CLOSED: async () => {
+        act(() => pendingModalClose.run());
+        await flushMfaUi();
+    },
+} satisfies Record<MfaEventType, MfaEventExecutor>;
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export default mfaEventExecutors;

tests/utils/mfa/ui/harness.tsx

@@ -0,0 +1,76 @@
+import {render, screen} from '@testing-library/react-native';
+import React, {useEffect} from 'react';
+import {SafeAreaProvider} from 'react-native-safe-area-context';
+import ComposeProviders from '@components/ComposeProviders';
+import {LocaleContextProvider} from '@components/LocaleContextProvider';
+import {MultifactorAuthenticationContextProviders, useMultifactorAuthentication} from '@components/MultifactorAuthentication/Context';
+import OnyxListItemProvider from '@components/OnyxListItemProvider';
+import MultifactorAuthenticationModalNavigator from '@navigation/AppNavigator/Navigators/MultifactorAuthenticationModalNavigator';
+import waitForBatchedUpdatesWithAct from '../../waitForBatchedUpdatesWithAct';
+
+/** The two queryable markers the state tests assert against. `OutcomeScreenBase` is the success/failure
+ *  screen's testID; the backdrop's `common.close` label only ever renders inside the mounted navigator. */
+const OUTCOME_SCREEN_TEST_ID = 'OutcomeScreenBase';
+const MODAL_OVERLAY_LABEL = 'Close';
+
+type MfaUiControls = {
+    executeScenario: ReturnType<typeof useMultifactorAuthentication>['executeScenario'];
+};
+
+const controlsHolder: {current: MfaUiControls | undefined} = {current: undefined};
+
+/**
+ * Renders nothing; it sits inside the providers only to capture the live context API so the event
+ * executors can start a flow through the public API.
+ */
+function MfaControlsCapture() {
+    const {executeScenario} = useMultifactorAuthentication();
+    useEffect(() => {
+        controlsHolder.current = {executeScenario};
+    });
+    return null;
+}
+MfaControlsCapture.displayName = 'MfaControlsCapture';
+
+const INITIAL_SAFE_AREA_METRICS = {
+    frame: {x: 0, y: 0, width: 390, height: 844},
+    insets: {top: 0, left: 0, right: 0, bottom: 0},
+};
+
+/** Mounts the real provider stack and the real MFA modal navigator the app renders in production. */
+function renderMfaUi() {
+    controlsHolder.current = undefined;
+    return render(
+        <SafeAreaProvider initialMetrics={INITIAL_SAFE_AREA_METRICS}>
+            <ComposeProviders components={[OnyxListItemProvider, LocaleContextProvider]}>
+                <MultifactorAuthenticationContextProviders>
+                    <MfaControlsCapture />
+                    <MultifactorAuthenticationModalNavigator />
+                </MultifactorAuthenticationContextProviders>
+            </ComposeProviders>
+        </SafeAreaProvider>,
+    );
+}
+
+function getMfaControls(): MfaUiControls {
+    if (!controlsHolder.current) {
+        throw new Error('MFA UI controls were not captured. Call renderMfaUi() and flushMfaUi() first.');
+    }
+    return controlsHolder.current;
+}
+
+async function flushMfaUi(): Promise<void> {
+    await waitForBatchedUpdatesWithAct();
+}
+
+/** True while the outcome screen (success/failure) is the visible route. */
+function isOutcomeScreenVisible(): boolean {
+    return screen.queryAllByTestId(OUTCOME_SCREEN_TEST_ID).length > 0;
+}
+
+/** True while the MFA overlay (navigator root + backdrop) is mounted. */
+function isModalOverlayMounted(): boolean {
+    return screen.queryAllByLabelText(MODAL_OVERLAY_LABEL).length > 0;
+}
+
+export {renderMfaUi, getMfaControls, flushMfaUi, isOutcomeScreenVisible, isModalOverlayMounted};

tests/utils/mfa/ui/jestMocks.ts

@@ -0,0 +1,70 @@
+import {useMachine} from '@xstate/react';
+import type {AnyStateMachine} from 'xstate';
+import {biometricsMock, pendingModalClose} from './mocks';
+
+/**
+ * jest.mock factory bodies for the model-based MFA UI test, kept out of the test file so it reads as
+ * mock registrations plus test logic. Each is called from a `jest.mock(..., () => require(...).xMock())`
+ * factory, so it returns a ready-to-use mock module (`__esModule` + `default`).
+ */
+
+/** Drops the dev-only Stately inspector wiring; the provider just needs the plain @xstate/react adapter. */
+function inspectedMachineMock() {
+    // Named `use*` so rules-of-hooks treats it as a custom hook (it calls useMachine).
+    const useInspectedMachineMock = (machine: AnyStateMachine) => useMachine(machine);
+    return {
+        __esModule: true,
+        default: useInspectedMachineMock,
+    };
+}
+
+/** Native / WebAuthn biometrics are out of scope for the modal-lifecycle contract; serve the shared seam. */
+function biometricsHookMock() {
+    return {
+        __esModule: true,
+        default: () => biometricsMock,
+    };
+}
+
+/** Browser/Android back-history wiring is a separate concern from the machine <-> UI contract. */
+function syncHistoryMock() {
+    return {
+        __esModule: true,
+        default: () => {},
+    };
+}
+
+/**
+ * Automock leaves the default export's methods undefined, so provide the three the flow needs and
+ * resolve any other `Navigation.*` the render path touches to a no-op jest.fn().
+ *
+ * `runAfterTransition` runs its callback immediately (no active navigation transition in jsdom).
+ * `runAfterUpcomingTransition` captures the navigator's teardown callback so MODAL_CLOSED is driven
+ * from the event map, not a timer.
+ */
+function navigationMock() {
+    const handlers: Record<string, unknown> = {
+        runAfterTransition: (callback: () => void) => {
+            callback();
+            return {cancel: () => {}};
+        },
+        runAfterUpcomingTransition: (callback: () => void) => {
+            pendingModalClose.capture(callback);
+            return {cancel: () => pendingModalClose.clear()};
+        },
+        isNavigationReady: () => Promise.resolve(),
+    };
+    return {
+        __esModule: true,
+        default: new Proxy(handlers, {
+            get: (target, property) => {
+                if (typeof property === 'string' && property in target) {
+                    return target[property];
+                }
+                return jest.fn();
+            },
+        }),
+    };
+}
+
+export {inspectedMachineMock, biometricsHookMock, syncHistoryMock, navigationMock};