test(mfa): add reachability and UI-walk tests

First split of the MFA state-machine test foundation (was #344). Carries only
the two guarantees this slice needs and the minimal harness they depend on:

- everyStateReachableTest: every settleable leaf state of mfaMachine is
  reachable. Derived from the chart via getShortestPaths, so new states are
  covered with no edit here.
- realModalTest: walks the machine graph (getSimplePaths plus the lifecycle
  lap) through the real provider stack and modal navigator, drives each event
  as a real gesture, and asserts the modal/outcome DOM markers at every step.

Harness: flowFixtures, flowPaths, reachableStates, and the realUi rig
(renderModal, userGestures, mocks, jestMocks).

The remaining specs (machine unit, lifecycle, snapshot mapper, @xstate/react
binding) and the machineUnderTest helper follow in later splits.

Test-only change, no production code touched.

Author: dariusz-biela

tests/unit/MultifactorAuthentication/modalFlow/everyStateReachableTest.ts

@@ -0,0 +1,14 @@
+import {matchesState} from 'xstate';
+import {getShortestPaths} from 'xstate/graph';
+import mfaMachine from '@components/MultifactorAuthentication/machine/mfaMachine';
+import getSettleableLeafStates from '../../../utils/mfa/reachableStates';
+
+// With no `events` list passed, getShortestPaths synthesizes a bare event for every transition the
+// machine declares, so new events reach new states automatically. Pass `events` only to supply a payload a guard needs.
+describe('every MFA modal state is reachable', () => {
+    const reachableSnapshots = getShortestPaths(mfaMachine).map((path) => path.state);
+
+    it.each(getSettleableLeafStates(mfaMachine))('reaches the $description state', ({value}) => {
+        expect(reachableSnapshots.some((snapshot) => matchesState(value, snapshot.value))).toBe(true);
+    });
+});

tests/unit/MultifactorAuthentication/viewMatchesMachine/realModalTest.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/flowPaths';
+import {resetMfaUiMocks} from '../../../utils/mfa/realUi/mocks';
+import {flushMfaUi, isModalOverlayMounted, isOutcomeScreenVisible, renderMfaUi} from '../../../utils/mfa/realUi/renderModal';
+import mfaEventExecutors from '../../../utils/mfa/realUi/userGestures';
+
+// Forces a wide layout so the navigator renders the backdrop overlay the assertions use as the mounted marker.
+jest.mock('@hooks/useResponsiveLayout');
+// Replaces the dev-only Stately inspector wiring with the plain @xstate/react adapter the provider needs.
+jest.mock('@hooks/useInspectedMachine', () => require('../../../utils/mfa/realUi/jestMocks').inspectedMachineMock());
+// Native / WebAuthn biometrics are out of scope for the modal-lifecycle contract.
+jest.mock('@components/MultifactorAuthentication/biometrics/useBiometrics', () => require('../../../utils/mfa/realUi/jestMocks').biometricsHookMock());
+// Browser/Android back-history wiring is a separate concern from the machine <-> UI contract.
+jest.mock('@components/MultifactorAuthentication/useSyncMfaModalNavigatorWithHistory', () => require('../../../utils/mfa/realUi/jestMocks').syncHistoryMock());
+// Navigation automock leaves methods undefined, so this supplies the methods the flow needs and no-ops the rest.
+jest.mock('@libs/Navigation/Navigation', () => require('../../../utils/mfa/realUi/jestMocks').navigationMock());
+
+const MFA_STATE = CONST.MULTIFACTOR_AUTHENTICATION.MFA_STATE;
+
+const testModel = createMfaTestModel();
+
+// The createTestModel-style config maps each event to a UI gesture and each state to a per-state assertion.
+// State keys are dot-path values matched with `matchesState`, so they can target any depth, such as 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('the real MFA modal follows the machine', () => {
+    beforeEach(() => {
+        resetMfaUiMocks();
+        resetMfaNavigation();
+    });
+
+    afterEach(() => {
+        jest.clearAllMocks();
+    });
+
+    // getSimplePaths reaches every state. The lifecycle paths add the MODAL_CLOSED teardown that simple paths skip.
+    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/flowFixtures.ts

@@ -0,0 +1,17 @@
+import {getScenarioConfig} from '@components/MultifactorAuthentication/config';
+import type {MultifactorAuthenticationInitEvent} from '@components/MultifactorAuthentication/machine/types';
+import CONST from '@src/CONST';
+
+const MFA_TEST_SCENARIO_NAME = CONST.MULTIFACTOR_AUTHENTICATION.SCENARIO.BIOMETRICS_TEST;
+
+function createInitEvent(): MultifactorAuthenticationInitEvent {
+    return {
+        type: 'INIT',
+        scenarioName: MFA_TEST_SCENARIO_NAME,
+        scenario: getScenarioConfig(MFA_TEST_SCENARIO_NAME),
+        payload: undefined,
+    };
+}
+
+export default createInitEvent;
+export {MFA_TEST_SCENARIO_NAME};

tests/utils/mfa/flowPaths.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 createInitEvent from './flowFixtures';
+import {toStateValue} from './reachableStates';
+
+/**
+ * Wraps `xstate/graph`'s plain path generators in a small `createTestModel`-style harness. 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 such as `always` or
+ * `initial` (for example `preparing` and `outcome`) are passed through and never become their own node.
+ */
+
+type MfaSnapshot = SnapshotFrom<typeof mfaMachine>;
+
+/** Performs the UI gesture that produces a machine event. It is an `events` map entry passed to `path.test`. */
+type MfaEventExecutor = () => void | Promise<void>;
+
+/** Asserts the UI when the walk reaches a matching state. It is a `states` map entry passed to `path.test`. */
+type MfaStateAssertion = (state: MfaSnapshot) => void | Promise<void>;
+
+type MfaPathTestConfig = {
+    events: Partial<Record<MfaEvent['type'], MfaEventExecutor>>;
+    /** Maps a dot-path state value (e.g. `open.outcome.success`) to its assertion, matched against each step with `matchesState`. */
+    states: Record<string, MfaStateAssertion>;
+};
+
+type RawPath = {
+    state: MfaSnapshot;
+    steps: ReadonlyArray<{state: MfaSnapshot; event: {type: string}}>;
+};
+
+type MfaTestPath = {
+    /** Holds the final-state snapshot, e.g. for `JSON.stringify(path.state.value)` test names. */
+    state: MfaSnapshot;
+    /** Names 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, while CLOSE_MODAL and MODAL_CLOSED are bare. These drive only
+// the explicit teardown sequence (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, so this drops 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)),
+        // Covers the full teardown sequence (... -> 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/reachableStates.ts

@@ -0,0 +1,31 @@
+import type {AnyStateMachine, AnyStateNode, StateValue} from 'xstate';
+
+type SettleableLeafState = {description: string; value: StateValue};
+
+function toStateValue(path: string[]): StateValue {
+    if (path.length <= 1) {
+        return path.at(0) ?? '';
+    }
+    const [head, ...rest] = path;
+    return {[head]: toStateValue(rest)};
+}
+
+function collectSettleableLeafStates(node: AnyStateNode): SettleableLeafState[] {
+    const children = Object.values(node.states);
+    if (children.length > 0) {
+        return children.flatMap(collectSettleableLeafStates);
+    }
+    // A leaf with an `always` transition is a transient router that leaves on entry and never settles.
+    if ((node.always?.length ?? 0) > 0) {
+        return [];
+    }
+    return [{description: node.path.join('.'), value: toStateValue(node.path)}];
+}
+
+function getSettleableLeafStates(machine: AnyStateMachine): SettleableLeafState[] {
+    return collectSettleableLeafStates(machine.root);
+}
+
+export default getSettleableLeafStates;
+export {toStateValue};
+export type {SettleableLeafState};

tests/utils/mfa/realUi/jestMocks.ts

@@ -0,0 +1,71 @@
+// eslint-disable-next-line no-restricted-imports -- this mock replaces useInspectedMachine with the plain @xstate/react adapter so the modal-lifecycle contract runs without the dev-only inspector wiring.
+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, so this returns the shared biometrics mock. */
+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 this provides the methods the flow needs
+ * and resolves 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 navigationMethodStubs: 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(navigationMethodStubs, {
+            get: (target, property) => {
+                if (typeof property === 'string' && property in target) {
+                    return target[property];
+                }
+                return jest.fn();
+            },
+        }),
+    };
+}
+
+export {inspectedMachineMock, biometricsHookMock, syncHistoryMock, navigationMock};

tests/utils/mfa/realUi/mocks.ts

@@ -0,0 +1,47 @@
+/**
+ * Shared, mutable mock seam for the model-based MFA UI test. The jest.mock factories in `jestMocks`
+ * read from these holders, and the harness / event executors drive them. Keeping the seam in one
+ * module means the future "mock the backend responses" work has a single place to grow.
+ */
+
+type CapturedCallback = () => void;
+
+let pendingCloseCallback: CapturedCallback | undefined;
+
+/**
+ * Holds the callback the modal navigator hands to `Navigation.runAfterUpcomingTransition` when it
+ * starts closing. The real navigator runs it once the close animation ends. The test captures it and
+ * runs it explicitly so the `closing` state stays observable and `MODAL_CLOSED` stays drivable from
+ * the event map instead of resolving on a timer.
+ */
+const pendingModalClose = {
+    capture: (callback: CapturedCallback) => {
+        pendingCloseCallback = callback;
+    },
+    run: () => {
+        const callback = pendingCloseCallback;
+        pendingCloseCallback = undefined;
+        callback?.();
+    },
+    clear: () => {
+        pendingCloseCallback = undefined;
+    },
+};
+
+/**
+ * Stands in for the native / WebAuthn biometrics hook. The flow only reads the credential fields
+ * during `INIT` (captureCredentialsState). `authorize` is here for the scenarios that will later sign
+ * a challenge through this seam.
+ */
+const biometricsMock = {
+    serverKnownCredentialIDs: [] as string[],
+    areLocalCredentialsKnownToServer: () => Promise.resolve(false),
+    authorize: () => Promise.resolve(),
+};
+
+function resetMfaUiMocks() {
+    pendingModalClose.clear();
+    biometricsMock.serverKnownCredentialIDs = [];
+}
+
+export {pendingModalClose, biometricsMock, resetMfaUiMocks};