@react-native-harness/jest 1.2.0-rc.1 → 1.2.0

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

@@ -0,0 +1,212 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createCrashMonitor, CrashWatchCancelledError, } from '../crash-monitor.js';
+import { NativeCrashError } from '../errors.js';
+const noop = () => undefined;
+const resolveUndefined = async () => undefined;
+// ---------------------------------------------------------------------------
+// Test doubles
+// ---------------------------------------------------------------------------
+const createAppMonitorMock = () => {
+    let registeredListener = null;
+    const monitor = {
+        start: vi.fn(resolveUndefined),
+        stop: vi.fn(resolveUndefined),
+        dispose: vi.fn(resolveUndefined),
+        addListener: vi.fn((l) => {
+            registeredListener = l;
+        }),
+        removeListener: vi.fn((l) => {
+            if (registeredListener === l)
+                registeredListener = null;
+        }),
+    };
+    return {
+        monitor,
+        emit: (event) => registeredListener?.(event),
+    };
+};
+const createPlatformRunnerMock = (isRunning = false, crashDetails = null) => ({
+    isAppRunning: vi.fn(async () => isRunning),
+    getCrashDetails: vi.fn(async () => crashDetails),
+    startApp: vi.fn(resolveUndefined),
+    restartApp: vi.fn(resolveUndefined),
+    stopApp: vi.fn(resolveUndefined),
+    dispose: vi.fn(resolveUndefined),
+    createAppMonitor: vi.fn(),
+});
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+describe('createCrashMonitor', () => {
+    describe('liveness', () => {
+        it('starts not alive', () => {
+            const { monitor } = createAppMonitorMock();
+            const cm = createCrashMonitor({ appMonitor: monitor, platformRunner: createPlatformRunnerMock() });
+            expect(cm.isAlive()).toBe(false);
+        });
+        it('becomes alive when the app starts', () => {
+            const { monitor, emit } = createAppMonitorMock();
+            const cm = createCrashMonitor({ appMonitor: monitor, platformRunner: createPlatformRunnerMock() });
+            emit({ type: 'app_started' });
+            expect(cm.isAlive()).toBe(true);
+        });
+        it('becomes not alive after a confirmed crash', async () => {
+            const { monitor, emit } = createAppMonitorMock();
+            const cm = createCrashMonitor({ appMonitor: monitor, platformRunner: createPlatformRunnerMock() });
+            emit({ type: 'app_started' });
+            const watch = cm.watch('test.ts', 'execution');
+            watch.promise.catch(noop);
+            emit({ type: 'app_exited', isConfirmed: true });
+            await watch.promise.catch(noop);
+            expect(cm.isAlive()).toBe(false);
+        });
+    });
+    describe('watch', () => {
+        it('promise rejects with NativeCrashError on confirmed app_exited', async () => {
+            const { monitor, emit } = createAppMonitorMock();
+            const cm = createCrashMonitor({ appMonitor: monitor, platformRunner: createPlatformRunnerMock() });
+            const watch = cm.watch('/test/example.ts', 'execution');
+            watch.promise.catch(noop);
+            emit({ type: 'app_exited', isConfirmed: true });
+            await expect(watch.promise).rejects.toBeInstanceOf(NativeCrashError);
+        });
+        it('attributes the crash to the file and phase passed to watch()', async () => {
+            const { monitor, emit } = createAppMonitorMock();
+            const cm = createCrashMonitor({ appMonitor: monitor, platformRunner: createPlatformRunnerMock() });
+            const watch = cm.watch('/test/example.ts', 'startup');
+            watch.promise.catch(noop);
+            emit({ type: 'app_exited', isConfirmed: true });
+            const error = await watch.promise.catch((e) => e);
+            expect(error.testFilePath).toBe('/test/example.ts');
+            expect(error.details.phase).toBe('startup');
+        });
+        it('settles the promise with CrashWatchCancelledError on cancel()', async () => {
+            const { monitor } = createAppMonitorMock();
+            const cm = createCrashMonitor({ appMonitor: monitor, platformRunner: createPlatformRunnerMock() });
+            const watch = cm.watch('test.ts', 'execution');
+            watch.cancel();
+            await expect(watch.promise).rejects.toBeInstanceOf(CrashWatchCancelledError);
+        });
+        it('subsequent cancel() after crash is a no-op', async () => {
+            const { monitor, emit } = createAppMonitorMock();
+            const cm = createCrashMonitor({ appMonitor: monitor, platformRunner: createPlatformRunnerMock() });
+            const watch = cm.watch('test.ts', 'execution');
+            watch.promise.catch(noop);
+            emit({ type: 'app_exited', isConfirmed: true });
+            await watch.promise.catch(noop);
+            // Second cancel should not throw or cause issues.
+            expect(() => watch.cancel()).not.toThrow();
+        });
+    });
+    describe('unconfirmed events', () => {
+        it('fires the crash if isAppRunning returns false', async () => {
+            const { monitor, emit } = createAppMonitorMock();
+            const runner = createPlatformRunnerMock(false /* not running */);
+            const cm = createCrashMonitor({ appMonitor: monitor, platformRunner: runner });
+            const watch = cm.watch('test.ts', 'execution');
+            watch.promise.catch(noop);
+            emit({ type: 'app_exited', isConfirmed: false });
+            await expect(watch.promise).rejects.toBeInstanceOf(NativeCrashError);
+        });
+        it('does not fire if isAppRunning returns true', async () => {
+            const { monitor, emit } = createAppMonitorMock();
+            const runner = createPlatformRunnerMock(true /* still running */);
+            const cm = createCrashMonitor({ appMonitor: monitor, platformRunner: runner });
+            const watch = cm.watch('test.ts', 'execution');
+            const settled = vi.fn();
+            watch.promise.then(settled, settled);
+            emit({ type: 'app_exited', isConfirmed: false });
+            await new Promise((r) => setTimeout(r, 20));
+            expect(settled).not.toHaveBeenCalled();
+            watch.cancel();
+        });
+        it('fires on possible_crash when confirmed', async () => {
+            const { monitor, emit } = createAppMonitorMock();
+            const cm = createCrashMonitor({ appMonitor: monitor, platformRunner: createPlatformRunnerMock() });
+            const watch = cm.watch('test.ts', 'execution');
+            watch.promise.catch(noop);
+            emit({ type: 'possible_crash', isConfirmed: true });
+            await expect(watch.promise).rejects.toBeInstanceOf(NativeCrashError);
+        });
+    });
+    describe('crash detail enrichment', () => {
+        it('merges initial and enriched crash details', async () => {
+            const { monitor, emit } = createAppMonitorMock();
+            const runner = createPlatformRunnerMock(false, {
+                processName: 'MyApp',
+                signal: 'SIGSEGV',
+                summary: 'Segmentation fault',
+            });
+            const cm = createCrashMonitor({ appMonitor: monitor, platformRunner: runner });
+            const watch = cm.watch('test.ts', 'execution');
+            watch.promise.catch(noop);
+            emit({ type: 'app_exited', isConfirmed: true, crashDetails: { pid: 1234 } });
+            const error = await watch.promise.catch((e) => e);
+            expect(error.details.processName).toBe('MyApp');
+            expect(error.details.signal).toBe('SIGSEGV');
+            expect(error.details.pid).toBe(1234);
+        });
+    });
+    describe('stop / start', () => {
+        it('ignores events while stopped', async () => {
+            const { monitor, emit } = createAppMonitorMock();
+            const cm = createCrashMonitor({ appMonitor: monitor, platformRunner: createPlatformRunnerMock() });
+            await cm.stop();
+            const watch = cm.watch('test.ts', 'execution');
+            const settled = vi.fn();
+            watch.promise.then(settled, settled);
+            emit({ type: 'app_exited', isConfirmed: true });
+            await new Promise((r) => setTimeout(r, 10));
+            expect(settled).not.toHaveBeenCalled();
+            watch.cancel();
+        });
+        it('resumes monitoring after start()', async () => {
+            const { monitor, emit } = createAppMonitorMock();
+            const cm = createCrashMonitor({ appMonitor: monitor, platformRunner: createPlatformRunnerMock() });
+            await cm.stop();
+            await cm.start();
+            const watch = cm.watch('test.ts', 'execution');
+            watch.promise.catch(noop);
+            emit({ type: 'app_exited', isConfirmed: true });
+            await expect(watch.promise).rejects.toBeInstanceOf(NativeCrashError);
+        });
+    });
+    describe('reset', () => {
+        it('clears alive state and pending watchers', async () => {
+            const { monitor, emit } = createAppMonitorMock();
+            const cm = createCrashMonitor({ appMonitor: monitor, platformRunner: createPlatformRunnerMock() });
+            emit({ type: 'app_started' });
+            const watch = cm.watch('test.ts', 'execution');
+            watch.promise.catch(noop);
+            cm.reset();
+            expect(cm.isAlive()).toBe(false);
+            // The watcher was cleared; a crash fired now should not reach the old watch.
+            emit({ type: 'app_exited', isConfirmed: true });
+            await new Promise((r) => setTimeout(r, 10));
+            // Old promise is still pending (we can verify by cancel resolving it).
+            watch.cancel();
+            await expect(watch.promise).rejects.toBeInstanceOf(CrashWatchCancelledError);
+        });
+    });
+    describe('dispose', () => {
+        it('ignores events after dispose', async () => {
+            const { monitor, emit } = createAppMonitorMock();
+            const cm = createCrashMonitor({ appMonitor: monitor, platformRunner: createPlatformRunnerMock() });
+            const watch = cm.watch('test.ts', 'execution');
+            watch.promise.catch(noop);
+            await cm.dispose();
+            emit({ type: 'app_exited', isConfirmed: true });
+            await new Promise((r) => setTimeout(r, 10));
+            // After dispose watchers are cleared, so crash didn't propagate.
+            // The promise is still pending - cancel to settle it.
+            watch.cancel();
+            await expect(watch.promise).rejects.toBeInstanceOf(CrashWatchCancelledError);
+        });
+        it('calls appMonitor.dispose()', async () => {
+            const { monitor } = createAppMonitorMock();
+            const cm = createCrashMonitor({ appMonitor: monitor, platformRunner: createPlatformRunnerMock() });
+            await cm.dispose();
+            expect(monitor.dispose).toHaveBeenCalledOnce();
+        });
+    });
+});

package/dist/__tests__/execute-run.test.d.ts

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

package/dist/__tests__/execute-run.test.d.ts.map

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

package/dist/__tests__/execute-run.test.js

@@ -0,0 +1,229 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+import { NativeCrashError, StartupStallError } from '../errors.js';
+import { DeviceNotRespondingError } from '@react-native-harness/bridge/server';
+import { executeRun } from '../execute-run.js';
+const resolveUndefined = async () => undefined;
+// Mock the file-runner so we control what jestResult/harnessResult each test returns
+// without needing a real Jest config or Metro bundler.
+const mockRunHarnessTestFile = vi.hoisted(() => vi.fn());
+vi.mock('../run.js', () => ({
+    runHarnessTestFile: mockRunHarnessTestFile,
+}));
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const makeJestResult = (overrides = {}) => ({
+    testFilePath: '/test/example.ts',
+    testResults: [],
+    failureMessage: null,
+    numFailingTests: 0,
+    numPassingTests: 1,
+    numPendingTests: 0,
+    numTodoTests: 0,
+    leaks: false,
+    openHandles: [],
+    skipped: false,
+    snapshot: {
+        added: 0, fileDeleted: false, matched: 0, unchecked: 0,
+        uncheckedKeys: [], unmatched: 0, updated: 0,
+    },
+    perfStats: { start: 0, end: 1, runtime: 1, slow: false,
+        loadTestEnvironmentStart: 0, loadTestEnvironmentEnd: 0,
+        setupAfterEnvStart: 0, setupAfterEnvEnd: 0,
+        setupFilesStart: 0, setupFilesEnd: 0 },
+    coverage: undefined,
+    ...overrides,
+});
+const makeHarnessResult = (status = 'passed') => ({
+    name: 'suite',
+    tests: [],
+    suites: [],
+    status,
+    duration: 50,
+});
+const makeFileRunResult = (overrides = {}) => ({
+    jestResult: makeJestResult(),
+    harnessResult: makeHarnessResult(),
+    relativeTestPath: 'example.ts',
+    duration: 50,
+    ...overrides,
+});
+const makeTest = (filePath = '/test/example.ts') => ({
+    path: filePath,
+    context: { config: {} },
+});
+const makeWatcher = (interrupted = false) => ({ isInterrupted: () => interrupted });
+const makeGlobalConfig = (overrides = {}) => ({
+    rootDir: '/project',
+    watch: false,
+    watchAll: false,
+    collectCoverage: false,
+    ...overrides,
+});
+const makeSession = (overrides = {}) => ({
+    config: {
+        metroPort: 8081,
+        host: undefined,
+        resetEnvironmentBetweenTestFiles: false,
+        detectNativeCrashes: true,
+    },
+    context: {},
+    ensureAppReady: vi.fn(resolveUndefined),
+    runTestFile: vi.fn(async () => makeHarnessResult()),
+    restartApp: vi.fn(resolveUndefined),
+    resetCrashState: vi.fn(),
+    flushClientLogs: vi.fn(() => []),
+    callHook: vi.fn(resolveUndefined),
+    setRunState: vi.fn(),
+    dispose: vi.fn(resolveUndefined),
+    ...overrides,
+});
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+beforeEach(() => {
+    vi.clearAllMocks();
+    mockRunHarnessTestFile.mockResolvedValue(makeFileRunResult());
+});
+describe('executeRun', () => {
+    describe('lifecycle hooks', () => {
+        it('emits run:started then run:finished in order', async () => {
+            const hookNames = [];
+            const session = makeSession({
+                callHook: vi.fn(async (name) => { hookNames.push(name); }),
+            });
+            await executeRun(session, [makeTest()], makeWatcher(), vi.fn(), vi.fn(), vi.fn(), makeGlobalConfig());
+            expect(hookNames[0]).toBe('run:started');
+            expect(hookNames[hookNames.length - 1]).toBe('run:finished');
+        });
+        it('emits test-file:started and test-file:finished around each test', async () => {
+            const hookNames = [];
+            const session = makeSession({
+                callHook: vi.fn(async (name) => { hookNames.push(name); }),
+            });
+            await executeRun(session, [makeTest('/a.ts'), makeTest('/b.ts')], makeWatcher(), vi.fn(), vi.fn(), vi.fn(), makeGlobalConfig());
+            const fileHooks = hookNames.filter((n) => n === 'test-file:started' || n === 'test-file:finished');
+            expect(fileHooks).toEqual([
+                'test-file:started', 'test-file:finished',
+                'test-file:started', 'test-file:finished',
+            ]);
+        });
+        it('always emits run:finished even when a test throws', async () => {
+            const hookNames = [];
+            const session = makeSession({
+                callHook: vi.fn(async (name) => { hookNames.push(name); }),
+                ensureAppReady: vi.fn(async () => { throw new Error('unexpected'); }),
+            });
+            await executeRun(session, [makeTest()], makeWatcher(), vi.fn(), vi.fn(), vi.fn(), makeGlobalConfig());
+            expect(hookNames).toContain('run:finished');
+        });
+    });
+    describe('happy path', () => {
+        it('calls onStart, ensureAppReady, runTestFile, onResult in order', async () => {
+            const order = [];
+            const session = makeSession({
+                ensureAppReady: vi.fn(async () => { order.push('ensureAppReady'); }),
+            });
+            const onStart = vi.fn(async () => { order.push('onStart'); });
+            const onResult = vi.fn(async () => { order.push('onResult'); });
+            mockRunHarnessTestFile.mockImplementation(async () => {
+                order.push('runTestFile');
+                return makeFileRunResult();
+            });
+            await executeRun(session, [makeTest()], makeWatcher(), onStart, onResult, vi.fn(), makeGlobalConfig());
+            expect(order).toEqual(['onStart', 'ensureAppReady', 'runTestFile', 'onResult']);
+        });
+        it('accumulates passing test counts in run:finished summary', async () => {
+            let finishedPayload;
+            const session = makeSession({
+                callHook: vi.fn(async (name, payload) => {
+                    if (name === 'run:finished')
+                        finishedPayload = payload;
+                }),
+            });
+            mockRunHarnessTestFile.mockResolvedValue(makeFileRunResult({ jestResult: makeJestResult({ numPassingTests: 3 }) }));
+            await executeRun(session, [makeTest(), makeTest('/b.ts')], makeWatcher(), vi.fn(), vi.fn(), vi.fn(), makeGlobalConfig());
+            const payload = finishedPayload;
+            expect(payload.summary.passed).toBe(6);
+            expect(payload.status).toBe('passed');
+        });
+        it('attaches buffered client logs to the Jest result', async () => {
+            const clientLogs = [{ message: 'Loaded screen', origin: '', type: 'warn' }];
+            const session = makeSession({
+                flushClientLogs: vi.fn()
+                    .mockReturnValueOnce([])
+                    .mockReturnValueOnce(clientLogs),
+            });
+            const onResult = vi.fn();
+            await executeRun(session, [makeTest()], makeWatcher(), vi.fn(), onResult, vi.fn(), makeGlobalConfig());
+            expect(session.flushClientLogs).toHaveBeenCalledTimes(2);
+            expect(onResult).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({ console: clientLogs }));
+        });
+    });
+    describe('runtime failures', () => {
+        it('passes StartupStallError to onFailure with an empty stack', async () => {
+            const onFailure = vi.fn();
+            const session = makeSession({
+                ensureAppReady: vi.fn().mockRejectedValue(new StartupStallError(1500, 3)),
+            });
+            await executeRun(session, [makeTest()], makeWatcher(), vi.fn(), vi.fn(), onFailure, makeGlobalConfig());
+            expect(onFailure).toHaveBeenCalledWith(expect.objectContaining({ path: '/test/example.ts' }), expect.objectContaining({ message: expect.stringContaining('1500'), stack: '' }));
+        });
+        it('passes DeviceNotRespondingError to onFailure with an empty stack', async () => {
+            const onFailure = vi.fn();
+            const session = makeSession({
+                ensureAppReady: vi.fn().mockRejectedValue(new DeviceNotRespondingError('runTests', [])),
+            });
+            await executeRun(session, [makeTest()], makeWatcher(), vi.fn(), vi.fn(), onFailure, makeGlobalConfig());
+            expect(onFailure).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({ stack: '' }));
+        });
+        it('calls resetCrashState after a NativeCrashError', async () => {
+            const session = makeSession({
+                ensureAppReady: vi.fn().mockRejectedValue(new NativeCrashError('example.ts', { phase: 'execution', source: 'polling' })),
+            });
+            await executeRun(session, [makeTest()], makeWatcher(), vi.fn(), vi.fn(), vi.fn(), makeGlobalConfig());
+            expect(session.resetCrashState).toHaveBeenCalled();
+        });
+        it('counts runtime failures in the summary', async () => {
+            let finishedPayload;
+            const session = makeSession({
+                callHook: vi.fn(async (name, payload) => {
+                    if (name === 'run:finished')
+                        finishedPayload = payload;
+                }),
+                ensureAppReady: vi.fn().mockRejectedValue(new StartupStallError(1000, 2)),
+            });
+            await executeRun(session, [makeTest()], makeWatcher(), vi.fn(), vi.fn(), vi.fn(), makeGlobalConfig());
+            const payload = finishedPayload;
+            expect(payload.summary.failed).toBe(1);
+            expect(payload.status).toBe('failed');
+        });
+    });
+    describe('watcher interrupt', () => {
+        it('stops processing tests and still emits run:finished', async () => {
+            const hookNames = [];
+            const session = makeSession({
+                callHook: vi.fn(async (name) => { hookNames.push(name); }),
+            });
+            const onStart = vi.fn();
+            await executeRun(session, [makeTest('/a.ts'), makeTest('/b.ts')], makeWatcher(true /* interrupted */), onStart, vi.fn(), vi.fn(), makeGlobalConfig());
+            // No test was started; watcher was already interrupted.
+            expect(onStart).not.toHaveBeenCalled();
+            expect(hookNames).toContain('run:finished');
+        });
+    });
+    describe('resetEnvironmentBetweenTestFiles', () => {
+        it('calls restartApp before the second test but not the first', async () => {
+            const session = makeSession({
+                config: {
+                    metroPort: 8081,
+                    resetEnvironmentBetweenTestFiles: true,
+                    detectNativeCrashes: false,
+                },
+            });
+            await executeRun(session, [makeTest('/a.ts'), makeTest('/b.ts'), makeTest('/c.ts')], makeWatcher(), vi.fn(), vi.fn(), vi.fn(), makeGlobalConfig());
+            // restartApp should be called for tests 2 and 3, not test 1.
+            expect(session.restartApp).toHaveBeenCalledTimes(2);
+        });
+    });
+});

package/dist/__tests__/hook-queue.test.d.ts

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

package/dist/__tests__/hook-queue.test.d.ts.map

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

package/dist/__tests__/hook-queue.test.js

@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest';
+import { createHookQueue } from '../hook-queue.js';
+describe('createHookQueue', () => {
+    it('executes scheduled work in FIFO order', async () => {
+        const queue = createHookQueue();
+        const order = [];
+        queue.schedule(async () => { order.push(1); });
+        queue.schedule(async () => { order.push(2); });
+        queue.schedule(async () => { order.push(3); });
+        await queue.drain();
+        expect(order).toEqual([1, 2, 3]);
+    });
+    it('drain awaits async work before resolving', async () => {
+        const queue = createHookQueue();
+        let resolved = false;
+        queue.schedule(async () => {
+            await new Promise((r) => setTimeout(r, 20));
+            resolved = true;
+        });
+        expect(resolved).toBe(false);
+        await queue.drain();
+        expect(resolved).toBe(true);
+    });
+    it('drain resolves immediately when nothing is scheduled', async () => {
+        const queue = createHookQueue();
+        await expect(queue.drain()).resolves.toBeUndefined();
+    });
+    it('captures the first error and re-throws it on drain', async () => {
+        const queue = createHookQueue();
+        const err = new Error('hook failed');
+        queue.schedule(async () => { throw err; });
+        await expect(queue.drain()).rejects.toBe(err);
+    });
+    it('continues executing subsequent hooks after one throws', async () => {
+        const queue = createHookQueue();
+        const ran = [];
+        queue.schedule(async () => { throw new Error('first'); });
+        queue.schedule(async () => { ran.push('second'); });
+        queue.schedule(async () => { ran.push('third'); });
+        await expect(queue.drain()).rejects.toThrow('first');
+        expect(ran).toEqual(['second', 'third']);
+    });
+    it('error is cleared after drain re-throws it', async () => {
+        const queue = createHookQueue();
+        queue.schedule(async () => { throw new Error('once'); });
+        await expect(queue.drain()).rejects.toThrow('once');
+        // Second drain should see no accumulated error.
+        await expect(queue.drain()).resolves.toBeUndefined();
+    });
+    it('surfaces only the first error when multiple hooks throw', async () => {
+        const queue = createHookQueue();
+        queue.schedule(async () => { throw new Error('first'); });
+        queue.schedule(async () => { throw new Error('second'); });
+        await expect(queue.drain()).rejects.toThrow('first');
+    });
+});

package/dist/__tests__/index.test.js

@@ -1,42 +1,99 @@
-import { describe, expect, it, vi } from 'vitest';
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+import { HarnessError } from '@react-native-harness/tools';
 import JestHarness from '../index.js';
-import { StartupStallError } from '../errors.js';
+const resolveUndefined = async () => undefined;
+// ---------------------------------------------------------------------------
+// Module mocks
+// ---------------------------------------------------------------------------
+const mockSession = {
+    config: { metroPort: 8081 },
+    context: {},
+    ensureAppReady: vi.fn(resolveUndefined),
+    runTestFile: vi.fn(async () => ({
+        name: '',
+        tests: [],
+        suites: [],
+        status: 'passed',
+        duration: 0,
+    })),
+    restartApp: vi.fn(resolveUndefined),
+    resetCrashState: vi.fn(),
+    flushClientLogs: vi.fn(() => []),
+    callHook: vi.fn(resolveUndefined),
+    setRunState: vi.fn(),
+    dispose: vi.fn(resolveUndefined),
+};
+const mockCreateHarnessSession = vi.hoisted(() => vi.fn(async () => mockSession));
+const mockExecuteRun = vi.hoisted(() => vi.fn(async () => undefined));
+vi.mock('../harness-session.js', () => ({
+    createHarnessSession: mockCreateHarnessSession,
+}));
+vi.mock('../execute-run.js', () => ({
+    executeRun: mockExecuteRun,
+}));
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const makeOptions = () => ({ serial: true });
+const makeWatcher = () => ({ isInterrupted: () => false });
+const makeTest = () => ({
+    path: '/test/example.ts',
+    context: { config: {} },
+});
+const makeGlobalConfig = (overrides = {}) => ({ rootDir: '/project', watch: false, watchAll: false, collectCoverage: false, ...overrides });
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+beforeEach(() => {
+    vi.clearAllMocks();
+    mockSession.dispose.mockResolvedValue(undefined);
+    mockExecuteRun.mockResolvedValue(undefined);
+    mockCreateHarnessSession.mockResolvedValue(mockSession);
+});
 describe('JestHarness', () => {
-    it('reports StartupStallError without a stack trace', async () => {
-        const runner = new JestHarness({});
-        const onFailure = vi.fn();
-        const harness = {
-            ensureAppReady: vi
-                .fn()
-                .mockRejectedValue(new StartupStallError(1500, 3)),
-            callHook: vi.fn(async () => undefined),
-            setRunState: vi.fn(),
-            getRunState: vi.fn(() => null),
-            crashSupervisor: {
-                beginTestRun: vi.fn(),
-                waitForCrash: vi.fn(),
-                cancelCrashWaiters: vi.fn(),
-                reset: vi.fn(),
-            },
-        };
-        await runner._createInBandTestRun([
-            {
-                path: '/tmp/example.harness.ts',
-                context: {
-                    config: {},
-                },
-            },
-        ], {
-            isInterrupted: () => false,
-        }, harness, {
-            detectNativeCrashes: true,
-            resetEnvironmentBetweenTestFiles: false,
-        }, () => Promise.resolve(), () => Promise.resolve(), onFailure);
-        expect(onFailure).toHaveBeenCalledWith(expect.objectContaining({
-            path: '/tmp/example.harness.ts',
-        }), {
-            message: 'The app did not request its Metro bundle after 3 launch attempts within 1500ms. Last Metro status: unknown.',
-            stack: '',
+    describe('session lifecycle', () => {
+        it('creates a session on the first run', async () => {
+            const runner = new JestHarness(makeGlobalConfig());
+            await runner.runTests([makeTest()], makeWatcher(), vi.fn(), vi.fn(), vi.fn(), makeOptions());
+            expect(mockCreateHarnessSession).toHaveBeenCalledOnce();
+        });
+        it('reuses the session across runs in watch mode', async () => {
+            const runner = new JestHarness(makeGlobalConfig({ watch: true }));
+            await runner.runTests([makeTest()], makeWatcher(), vi.fn(), vi.fn(), vi.fn(), makeOptions());
+            await runner.runTests([makeTest()], makeWatcher(), vi.fn(), vi.fn(), vi.fn(), makeOptions());
+            expect(mockCreateHarnessSession).toHaveBeenCalledOnce();
+            expect(mockSession.dispose).not.toHaveBeenCalled();
+        });
+        it('disposes the session after each run in normal mode', async () => {
+            const runner = new JestHarness(makeGlobalConfig());
+            await runner.runTests([makeTest()], makeWatcher(), vi.fn(), vi.fn(), vi.fn(), makeOptions());
+            expect(mockSession.dispose).toHaveBeenCalledOnce();
+        });
+        it('creates a fresh session for each run in normal mode', async () => {
+            const runner = new JestHarness(makeGlobalConfig());
+            await runner.runTests([makeTest()], makeWatcher(), vi.fn(), vi.fn(), vi.fn(), makeOptions());
+            await runner.runTests([makeTest()], makeWatcher(), vi.fn(), vi.fn(), vi.fn(), makeOptions());
+            expect(mockCreateHarnessSession).toHaveBeenCalledTimes(2);
+        });
+    });
+    describe('error handling', () => {
+        it('converts HarnessError into a formatted string before throwing', async () => {
+            class TestHarnessError extends HarnessError {
+                constructor() { super('something went wrong'); this.name = 'TestHarnessError'; }
+            }
+            mockCreateHarnessSession.mockRejectedValue(new TestHarnessError());
+            const runner = new JestHarness(makeGlobalConfig());
+            await expect(runner.runTests([makeTest()], makeWatcher(), vi.fn(), vi.fn(), vi.fn(), makeOptions())).rejects.toBeTypeOf('string');
+        });
+        it('propagates non-HarnessError exceptions as-is', async () => {
+            const cause = new TypeError('unexpected');
+            mockCreateHarnessSession.mockRejectedValue(cause);
+            const runner = new JestHarness(makeGlobalConfig());
+            await expect(runner.runTests([makeTest()], makeWatcher(), vi.fn(), vi.fn(), vi.fn(), makeOptions())).rejects.toBe(cause);
+        });
+        it('throws when called without serial flag', async () => {
+            const runner = new JestHarness(makeGlobalConfig());
+            await expect(runner.runTests([makeTest()], makeWatcher(), vi.fn(), vi.fn(), vi.fn(), { serial: false })).rejects.toThrow('Parallel test running is not supported');
         });
     });
 });