@react-native-harness/jest 1.0.0 → 1.1.0-rc.2

package/dist/__tests__/crash-supervisor.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=crash-supervisor.test.d.ts.map

package/dist/__tests__/crash-supervisor.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crash-supervisor.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/crash-supervisor.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/crash-supervisor.test.js

@@ -0,0 +1,151 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createCrashSupervisor } from '../crash-supervisor.js';
+const createMockAppMonitor = (options) => {
+    const listeners = new Set();
+    const noop = async () => undefined;
+    const appMonitor = {
+        start: noop,
+        stop: noop,
+        dispose: noop,
+        addListener: (listener) => {
+            listeners.add(listener);
+        },
+        removeListener: (listener) => {
+            listeners.delete(listener);
+        },
+    };
+    if (options?.getCrashDetails) {
+        appMonitor.getCrashDetails = options.getCrashDetails;
+    }
+    const emit = (event) => {
+        for (const listener of listeners) {
+            listener(event);
+        }
+    };
+    return {
+        appMonitor,
+        emit,
+    };
+};
+const createPlatformRunner = ({ isAppRunning, getCrashDetails, }) => ({
+    startApp: async () => undefined,
+    restartApp: async () => undefined,
+    stopApp: async () => undefined,
+    dispose: async () => undefined,
+    isAppRunning,
+    createAppMonitor: () => {
+        throw new Error('Not used in unit tests');
+    },
+    getCrashDetails,
+});
+describe('crash-supervisor', () => {
+    it('rejects the active test when the app exits during launch', async () => {
+        const monitor = createMockAppMonitor();
+        const supervisor = createCrashSupervisor({
+            appMonitor: monitor.appMonitor,
+            platformRunner: createPlatformRunner({
+                isAppRunning: vi.fn().mockResolvedValue(false),
+            }),
+        });
+        supervisor.beginLaunch('/tmp/startup.harness.ts');
+        const crashPromise = supervisor.waitForCrash('/tmp/startup.harness.ts');
+        const expectation = expect(crashPromise).rejects.toMatchObject({
+            name: 'NativeCrashError',
+            phase: 'startup',
+            details: {
+                signal: 'SIGSEGV',
+                processName: 'com.harnessplayground',
+            },
+        });
+        monitor.emit({
+            type: 'app_exited',
+            source: 'logs',
+            crashDetails: {
+                source: 'logs',
+                signal: 'SIGSEGV',
+                processName: 'com.harnessplayground',
+                rawLines: ['Fatal signal 11 (SIGSEGV)'],
+            },
+        });
+        await expectation;
+        await supervisor.dispose();
+    });
+    it('treats polling exit events as immediately confirmed crashes', async () => {
+        const monitor = createMockAppMonitor();
+        const isAppRunning = vi.fn().mockResolvedValue(true);
+        const supervisor = createCrashSupervisor({
+            appMonitor: monitor.appMonitor,
+            platformRunner: createPlatformRunner({
+                isAppRunning,
+            }),
+        });
+        supervisor.beginLaunch('/tmp/polling-exit.harness.ts');
+        const crashPromise = supervisor.waitForCrash('/tmp/polling-exit.harness.ts');
+        monitor.emit({ type: 'app_exited', source: 'polling' });
+        await expect(crashPromise).rejects.toMatchObject({
+            name: 'NativeCrashError',
+            phase: 'startup',
+        });
+        expect(isAppRunning).not.toHaveBeenCalled();
+        await supervisor.dispose();
+    });
+    it('does not reject when monitoring is stopped', async () => {
+        const monitor = createMockAppMonitor();
+        const supervisor = createCrashSupervisor({
+            appMonitor: monitor.appMonitor,
+            platformRunner: createPlatformRunner({
+                isAppRunning: vi.fn().mockResolvedValue(false),
+            }),
+        });
+        supervisor.beginTestRun('/tmp/restart.harness.ts');
+        await supervisor.stop();
+        const reject = vi.fn();
+        void supervisor.waitForCrash('/tmp/restart.harness.ts').catch(reject);
+        monitor.emit({ type: 'app_exited', source: 'polling' });
+        await Promise.resolve();
+        expect(reject).not.toHaveBeenCalled();
+        await supervisor.dispose();
+    });
+    it('prefers crash details from the started app monitor over the runner', async () => {
+        const monitorGetCrashDetails = vi.fn().mockResolvedValue({
+            source: 'logs',
+            summary: 'full crash block',
+            rawLines: ['full crash block'],
+        });
+        const runnerGetCrashDetails = vi.fn().mockResolvedValue({
+            source: 'logs',
+            summary: 'runner details',
+            rawLines: ['runner details'],
+        });
+        const monitor = createMockAppMonitor({
+            getCrashDetails: monitorGetCrashDetails,
+        });
+        const supervisor = createCrashSupervisor({
+            appMonitor: monitor.appMonitor,
+            platformRunner: createPlatformRunner({
+                isAppRunning: vi.fn().mockResolvedValue(false),
+                getCrashDetails: runnerGetCrashDetails,
+            }),
+        });
+        supervisor.beginTestRun('/tmp/monitor-details.harness.ts');
+        const crashPromise = supervisor.waitForCrash('/tmp/monitor-details.harness.ts');
+        monitor.emit({
+            type: 'possible_crash',
+            source: 'logs',
+            crashDetails: {
+                source: 'logs',
+                processName: 'com.harnessplayground',
+                pid: 1234,
+                rawLines: ['partial line'],
+            },
+        });
+        await expect(crashPromise).rejects.toMatchObject({
+            details: {
+                summary: 'full crash block',
+            },
+        });
+        expect(monitorGetCrashDetails).toHaveBeenCalled();
+        expect(runnerGetCrashDetails).not.toHaveBeenCalled();
+        await supervisor.dispose();
+    });
+});

package/dist/__tests__/errors.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=errors.test.d.ts.map

package/dist/__tests__/errors.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/errors.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/errors.test.js

@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest';
+import { NativeCrashError } from '../errors.js';
+describe('NativeCrashError', () => {
+    it('formats the extracted stack trace in the error message', () => {
+        const error = new NativeCrashError('/tmp/crash.harness.ts', {
+            phase: 'execution',
+            processName: 'HarnessPlayground',
+            pid: 1234,
+            signal: 'SIGTRAP',
+            exceptionType: 'EXC_BREAKPOINT',
+            stackTrace: [
+                '0 AppDelegate.crashIfRequested() (AppDelegate.swift:31)',
+                '1 AppDelegate.application(_:didFinishLaunchingWithOptions:) (AppDelegate.swift:56)',
+            ],
+        });
+        expect(error.message).toContain('  0 AppDelegate.crashIfRequested() (AppDelegate.swift:31)');
+        expect(error.message).toContain('  1 AppDelegate.application(_:didFinishLaunchingWithOptions:) (AppDelegate.swift:56)');
+    });
+    it('omits single-line iOS summaries from the rendered error message', () => {
+        const error = new NativeCrashError('/tmp/crash.harness.ts', {
+            phase: 'startup',
+            artifactType: 'ios-crash-report',
+            summary: '2026-03-12 13:46:18.154 Df HarnessPlayground[18007:65e716] [com.apple.dt.xctest:Default] notify_get_state check indicated test daemon not ready.',
+            processName: 'HarnessPlayground',
+            pid: 18007,
+            signal: 'SIGABRT',
+            exceptionType: 'EXC_CRASH',
+        });
+        expect(error.message).not.toContain('notify_get_state check indicated test daemon not ready');
+        expect(error.message).toContain('Signal: SIGABRT');
+        expect(error.message).toContain('Exception: EXC_CRASH');
+        expect(error.message).toContain('Process: HarnessPlayground (pid 18007)');
+    });
+    it('does not duplicate stack frames when the summary already contains a crash block', () => {
+        const frame = '03-13 07:59:44.943 20373 20373 E AndroidRuntime: \tat com.harnessplayground.MainActivity.onCreate(MainActivity.kt:38)';
+        const error = new NativeCrashError('/tmp/crash.harness.ts', {
+            phase: 'startup',
+            summary: [
+                '--------- beginning of crash',
+                '03-13 07:59:44.943 20373 20373 E AndroidRuntime: FATAL EXCEPTION: main',
+                frame,
+            ].join('\n'),
+            stackTrace: [frame],
+        });
+        expect(error.message.match(/MainActivity\.onCreate\(MainActivity\.kt:38\)/g)).toHaveLength(1);
+    });
+    it('collapses the native crash stack header so jest does not reprint multiline messages', () => {
+        const error = new NativeCrashError('/tmp/crash.harness.ts', {
+            phase: 'startup',
+            summary: ['line one', 'line two'].join('\n'),
+        });
+        expect(error.stack).toBe('NativeCrashError: The native app crashed while preparing to run this test file.');
+    });
+});

package/dist/__tests__/harness-cache.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=harness-cache.test.d.ts.map

package/dist/__tests__/harness-cache.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness-cache.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/harness-cache.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/harness-cache.test.js

@@ -0,0 +1,51 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+const mocks = vi.hoisted(() => ({
+    isMetroCacheReusable: vi.fn(),
+    logMetroCacheReused: vi.fn(),
+    logMetroPrewarmCompleted: vi.fn(),
+}));
+vi.mock('@react-native-harness/bundler-metro', () => ({
+    isMetroCacheReusable: mocks.isMetroCacheReusable,
+}));
+vi.mock('../logs.js', () => ({
+    logMetroCacheReused: mocks.logMetroCacheReused,
+    logMetroPrewarmCompleted: mocks.logMetroPrewarmCompleted,
+}));
+import { maybeLogMetroCacheReuse } from '../harness.js';
+const platform = {
+    name: 'ios',
+    platformId: 'ios',
+    runner: '/virtual/platform-runner.js',
+    config: {},
+};
+const createHarnessConfig = (overrides = {}) => ({
+    appRegistryComponentName: 'App',
+    webSocketPort: 8081,
+    disableViewFlattening: false,
+    bridgeTimeout: 5000,
+    entryPoint: 'index.js',
+    unstable__enableMetroCache: true,
+    forwardClientLogs: false,
+    ...overrides,
+});
+describe('maybeLogMetroCacheReuse', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        mocks.isMetroCacheReusable.mockReturnValue(false);
+    });
+    it('logs when an existing metro cache will be reused', () => {
+        mocks.isMetroCacheReusable.mockReturnValue(true);
+        maybeLogMetroCacheReuse(createHarnessConfig(), platform, '/tmp/project');
+        expect(mocks.isMetroCacheReusable).toHaveBeenCalledWith('/tmp/project');
+        expect(mocks.logMetroCacheReused).toHaveBeenCalledWith(platform);
+    });
+    it('does not log when metro cache reuse is disabled', () => {
+        maybeLogMetroCacheReuse(createHarnessConfig({ unstable__enableMetroCache: false }), platform, '/tmp/project');
+        expect(mocks.isMetroCacheReusable).not.toHaveBeenCalled();
+        expect(mocks.logMetroCacheReused).not.toHaveBeenCalled();
+    });
+    it('does not log when the metro cache is absent', () => {
+        maybeLogMetroCacheReuse(createHarnessConfig(), platform, '/tmp/project');
+        expect(mocks.logMetroCacheReused).not.toHaveBeenCalled();
+    });
+});

package/dist/__tests__/harness.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=harness.test.d.ts.map

package/dist/__tests__/harness.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/harness.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/harness.test.js

@@ -0,0 +1,399 @@
+import { EventEmitter } from 'node:events';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { definePlugin } from '@react-native-harness/plugins';
+import { createCrashSupervisor } from '../crash-supervisor.js';
+const mocks = vi.hoisted(() => ({
+    createCrashArtifactWriter: vi.fn(() => ({})),
+    getBridgeServer: vi.fn(),
+    getMetroInstance: vi.fn(),
+    isMetroCacheReusable: vi.fn(() => false),
+    logMetroCacheReused: vi.fn(),
+    waitForMetroBackedAppReady: vi.fn(),
+}));
+vi.mock('@react-native-harness/bundler-metro', async () => {
+    const actual = await vi.importActual('@react-native-harness/bundler-metro');
+    return {
+        ...actual,
+        getMetroInstance: mocks.getMetroInstance,
+        isMetroCacheReusable: mocks.isMetroCacheReusable,
+        waitForMetroBackedAppReady: mocks.waitForMetroBackedAppReady,
+    };
+});
+vi.mock('@react-native-harness/bridge/server', () => ({
+    getBridgeServer: mocks.getBridgeServer,
+}));
+vi.mock('../logs.js', () => ({
+    logMetroCacheReused: mocks.logMetroCacheReused,
+}));
+vi.mock('@react-native-harness/tools', async () => {
+    const actual = await vi.importActual('@react-native-harness/tools');
+    return {
+        ...actual,
+        createCrashArtifactWriter: mocks.createCrashArtifactWriter,
+    };
+});
+import { getHarness, waitForAppReady } from '../harness.js';
+import { StartupStallError } from '../errors.js';
+const createBridgeServer = () => {
+    const emitter = new EventEmitter();
+    return {
+        serverBridge: {
+            rpc: {
+                clients: [],
+            },
+            on: emitter.on.bind(emitter),
+            once: emitter.once.bind(emitter),
+            off: emitter.off.bind(emitter),
+            dispose: vi.fn(),
+        },
+        emitReady: () => {
+            emitter.emit('ready', {
+                platform: 'ios',
+                manufacturer: 'Apple',
+                model: 'Simulator',
+                osVersion: '18.0',
+            });
+        },
+        emitEvent: (event) => {
+            emitter.emit('event', event);
+        },
+        emitDisconnect: () => {
+            emitter.emit('disconnect');
+        },
+    };
+};
+const createReporter = () => {
+    const listeners = new Set();
+    return {
+        addListener: (listener) => {
+            listeners.add(listener);
+        },
+        removeListener: (listener) => {
+            listeners.delete(listener);
+        },
+        emit: (event) => {
+            listeners.forEach((listener) => listener(event));
+        },
+        clearAllListeners: () => {
+            listeners.clear();
+        },
+    };
+};
+const createMetroInstance = (overrides = {}) => ({
+    events: createReporter(),
+    waitUntilHealthy: vi.fn(async () => 'HTTP 200: packager-status:running'),
+    prewarm: vi.fn(async () => false),
+    dispose: vi.fn(async () => undefined),
+    ...overrides,
+});
+const createAppMonitor = () => {
+    const listeners = new Set();
+    return {
+        appMonitor: {
+            start: vi.fn(async () => undefined),
+            stop: vi.fn(async () => undefined),
+            dispose: vi.fn(async () => undefined),
+            addListener: (listener) => {
+                listeners.add(listener);
+            },
+            removeListener: (listener) => {
+                listeners.delete(listener);
+            },
+        },
+        emit: (event) => {
+            for (const listener of listeners) {
+                listener(event);
+            }
+        },
+    };
+};
+const createPlatformRunner = (overrides = {}) => ({
+    startApp: vi.fn(async () => undefined),
+    restartApp: vi.fn(async () => undefined),
+    stopApp: vi.fn(async () => undefined),
+    dispose: vi.fn(async () => undefined),
+    isAppRunning: vi.fn(async () => true),
+    createAppMonitor: () => createAppMonitor().appMonitor,
+    ...overrides,
+});
+const createHarnessConfig = (overrides = {}) => ({
+    appRegistryComponentName: 'App',
+    bridgeTimeout: 60_000,
+    bundleStartTimeout: 60_000,
+    crashDetectionInterval: 500,
+    defaultRunner: 'ios',
+    detectNativeCrashes: true,
+    disableViewFlattening: false,
+    entryPoint: 'index.js',
+    forwardClientLogs: false,
+    maxAppRestarts: 2,
+    metroPort: 8081,
+    resetEnvironmentBetweenTestFiles: true,
+    runners: [],
+    unstable__enableMetroCache: false,
+    unstable__skipAlreadyIncludedModules: false,
+    webSocketPort: 3001,
+    ...overrides,
+});
+beforeEach(() => {
+    vi.clearAllMocks();
+});
+afterEach(() => {
+    delete globalThis.__HARNESS_PLATFORM_RUNNER__;
+});
+describe('waitForAppReady', () => {
+    it('delegates startup orchestration to bundler-metro and resolves readiness from the bridge', async () => {
+        const { serverBridge, emitReady } = createBridgeServer();
+        const metroInstance = createMetroInstance();
+        const platformInstance = createPlatformRunner();
+        const { appMonitor } = createAppMonitor();
+        const crashSupervisor = createCrashSupervisor({
+            appMonitor,
+            platformRunner: platformInstance,
+        });
+        mocks.waitForMetroBackedAppReady.mockImplementationOnce(async (options) => {
+            options.onAttemptStart?.();
+            const readyPromise = options.waitForReady(new AbortController().signal);
+            emitReady();
+            await readyPromise;
+            options.onAttemptReset?.();
+        });
+        await waitForAppReady({
+            metroInstance,
+            serverBridge,
+            platformInstance,
+            platformId: 'ios',
+            bundleStartTimeout: 1_500,
+            readyTimeout: 2_500,
+            maxAppRestarts: 3,
+            testFilePath: '/tmp/test.harness.ts',
+            crashSupervisor,
+        });
+        expect(mocks.waitForMetroBackedAppReady).toHaveBeenCalledWith(expect.objectContaining({
+            metro: metroInstance,
+            platformId: 'ios',
+            bundleStartTimeout: 1_500,
+            readyTimeout: 2_500,
+            maxAppRestarts: 3,
+            startAttempt: expect.any(Function),
+            waitForReady: expect.any(Function),
+            waitForCrash: expect.any(Function),
+        }));
+        expect(crashSupervisor.isReady()).toBe(true);
+        await crashSupervisor.dispose();
+    });
+    it('passes launch options through the shared Metro startup helper', async () => {
+        const { serverBridge } = createBridgeServer();
+        const metroInstance = createMetroInstance();
+        const restartApp = vi.fn(async () => undefined);
+        const platformInstance = createPlatformRunner({ restartApp });
+        const { appMonitor } = createAppMonitor();
+        const crashSupervisor = createCrashSupervisor({
+            appMonitor,
+            platformRunner: platformInstance,
+        });
+        mocks.waitForMetroBackedAppReady.mockImplementationOnce(async (options) => {
+            await options.startAttempt();
+        });
+        await waitForAppReady({
+            metroInstance,
+            serverBridge,
+            platformInstance,
+            platformId: 'ios',
+            bundleStartTimeout: 1_500,
+            readyTimeout: 2_500,
+            maxAppRestarts: 3,
+            testFilePath: '/tmp/test.harness.ts',
+            crashSupervisor,
+            appLaunchOptions: {
+                extras: {
+                    mode: 'startup',
+                },
+            },
+        });
+        expect(restartApp).toHaveBeenCalledWith({
+            extras: {
+                mode: 'startup',
+            },
+        });
+        await crashSupervisor.dispose();
+    });
+});
+describe('getHarness', () => {
+    it('routes ensureAppReady through the shared Metro startup helper', async () => {
+        const { serverBridge, emitReady } = createBridgeServer();
+        const appMonitor = createAppMonitor();
+        const restartApp = vi.fn(async () => undefined);
+        const platformInstance = createPlatformRunner({
+            restartApp,
+            createAppMonitor: () => appMonitor.appMonitor,
+        });
+        const metroInstance = createMetroInstance();
+        mocks.getBridgeServer.mockResolvedValue(serverBridge);
+        mocks.getMetroInstance.mockResolvedValue(metroInstance);
+        mocks.waitForMetroBackedAppReady.mockImplementationOnce(async (options) => {
+            await options.startAttempt();
+            const readyPromise = options.waitForReady(new AbortController().signal);
+            emitReady();
+            await readyPromise;
+        });
+        globalThis.__HARNESS_PLATFORM_RUNNER__ = vi.fn(async () => platformInstance);
+        const platform = {
+            config: {
+                appLaunchOptions: {
+                    extras: {
+                        source: 'ensure-ready',
+                    },
+                },
+            },
+            name: 'ios',
+            platformId: 'ios',
+            runner: `data:text/javascript,${encodeURIComponent('export default (...args) => globalThis.__HARNESS_PLATFORM_RUNNER__(...args);')}`,
+        };
+        const harness = await getHarness(createHarnessConfig(), platform, '/tmp/project');
+        await harness.ensureAppReady('/tmp/example.harness.ts');
+        expect(mocks.waitForMetroBackedAppReady).toHaveBeenCalledTimes(1);
+        expect(restartApp).toHaveBeenCalledWith({
+            extras: {
+                source: 'ensure-ready',
+            },
+        });
+        await harness.dispose();
+    });
+    it('routes restart(testFilePath) through the shared Metro startup helper', async () => {
+        const { serverBridge, emitReady } = createBridgeServer();
+        const appMonitor = createAppMonitor();
+        const restartApp = vi.fn(async () => undefined);
+        const stopApp = vi.fn(async () => undefined);
+        const platformInstance = createPlatformRunner({
+            restartApp,
+            stopApp,
+            isAppRunning: vi.fn(async () => false),
+            createAppMonitor: () => appMonitor.appMonitor,
+        });
+        const metroInstance = createMetroInstance();
+        mocks.getBridgeServer.mockResolvedValue(serverBridge);
+        mocks.getMetroInstance.mockResolvedValue(metroInstance);
+        mocks.waitForMetroBackedAppReady.mockImplementationOnce(async (options) => {
+            await options.startAttempt();
+            const readyPromise = options.waitForReady(new AbortController().signal);
+            emitReady();
+            await readyPromise;
+        });
+        globalThis.__HARNESS_PLATFORM_RUNNER__ = vi.fn(async () => platformInstance);
+        const platform = {
+            config: {
+                appLaunchOptions: {
+                    extras: {
+                        source: 'restart',
+                    },
+                },
+            },
+            name: 'ios',
+            platformId: 'ios',
+            runner: `data:text/javascript,${encodeURIComponent('export default (...args) => globalThis.__HARNESS_PLATFORM_RUNNER__(...args);')}`,
+        };
+        const harness = await getHarness(createHarnessConfig(), platform, '/tmp/project');
+        await harness.restart('/tmp/restart.harness.ts');
+        expect(stopApp).toHaveBeenCalledTimes(1);
+        expect(mocks.waitForMetroBackedAppReady).toHaveBeenCalledTimes(1);
+        expect(restartApp).toHaveBeenCalledWith({
+            extras: {
+                source: 'restart',
+            },
+        });
+        await harness.dispose();
+    });
+});
+describe('plugins', () => {
+    it('invokes lifecycle and runtime plugin handlers for configured plugins', async () => {
+        const { serverBridge, emitReady, emitEvent, emitDisconnect } = createBridgeServer();
+        const appMonitor = createAppMonitor();
+        const platformInstance = createPlatformRunner({
+            createAppMonitor: () => appMonitor.appMonitor,
+        });
+        const observedHooks = [];
+        mocks.getBridgeServer.mockResolvedValue(serverBridge);
+        const metroInstance = createMetroInstance();
+        mocks.getMetroInstance.mockResolvedValue(metroInstance);
+        globalThis.__HARNESS_PLATFORM_RUNNER__ = vi.fn(async () => platformInstance);
+        const plugin = definePlugin({
+            name: 'test-plugin',
+            createState: () => ({
+                creationCount: 0,
+            }),
+            hooks: {
+                harness: {
+                    beforeCreation: (ctx) => {
+                        ctx.state.creationCount += 1;
+                        observedHooks.push(`beforeCreation:${ctx.platform.platformId}:${ctx.appLaunchOptions == null ? 'no-launch-options' : 'launch-options'}`);
+                    },
+                    beforeDispose: (ctx) => {
+                        observedHooks.push(`beforeDispose:${ctx.state.creationCount}:${ctx.reason}`);
+                    },
+                },
+                runtime: {
+                    ready: (ctx) => {
+                        observedHooks.push(`runtime.ready:${ctx.runId}:${ctx.device.platform}`);
+                    },
+                    disconnected: (ctx) => {
+                        observedHooks.push(`runtime.disconnected:${ctx.reason}`);
+                    },
+                },
+                collection: {
+                    started: (ctx) => {
+                        observedHooks.push(`collection.started:${ctx.file}`);
+                    },
+                },
+            },
+        });
+        const platform = {
+            config: {
+                appLaunchOptions: {
+                    environment: {
+                        MODE: 'test',
+                    },
+                },
+            },
+            name: 'ios',
+            platformId: 'ios',
+            runner: `data:text/javascript,${encodeURIComponent('export default (...args) => globalThis.__HARNESS_PLATFORM_RUNNER__(...args);')}`,
+        };
+        const harness = await getHarness(createHarnessConfig({
+            plugins: [plugin],
+        }), platform, '/tmp/project');
+        harness.setRunState({
+            runId: 'run-1',
+            startTime: Date.now(),
+            testFiles: ['example.harness.ts'],
+            watchMode: false,
+            coverageEnabled: false,
+            summary: {
+                passed: 1,
+                failed: 0,
+                skipped: 0,
+                todo: 0,
+            },
+            status: 'passed',
+        });
+        emitReady();
+        emitEvent({
+            type: 'collection-started',
+            file: 'example.harness.ts',
+        });
+        emitDisconnect();
+        await harness.dispose();
+        expect(observedHooks).toEqual([
+            'beforeCreation:ios:launch-options',
+            'runtime.ready:run-1:ios',
+            'collection.started:example.harness.ts',
+            'runtime.disconnected:bridge-disconnected',
+            'beforeDispose:1:normal',
+        ]);
+    });
+});
+describe('StartupStallError', () => {
+    it('includes the configured timeout and attempt count', () => {
+        expect(new StartupStallError(1_500, 4).message).toBe('The app did not request its Metro bundle after 4 launch attempts within 1500ms. Last Metro status: unknown.');
+    });
+});