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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-native-harness/jest",
-  "version": "1.2.0",
+  "version": "1.4.0-rc.1",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -39,12 +39,12 @@
     "jest-util": "^30.2.0",
     "tslib": "^2.3.0",
     "yargs": "^17.7.2",
-    "@react-native-harness/config": "1.2.0",
-    "@react-native-harness/platforms": "1.2.0",
-    "@react-native-harness/tools": "1.2.0",
-    "@react-native-harness/bundler-metro": "1.2.0",
-    "@react-native-harness/bridge": "1.2.0",
-    "@react-native-harness/plugins": "1.2.0"
+    "@react-native-harness/plugins": "1.4.0-rc.1",
+    "@react-native-harness/platforms": "1.4.0-rc.1",
+    "@react-native-harness/bridge": "1.4.0-rc.1",
+    "@react-native-harness/config": "1.4.0-rc.1",
+    "@react-native-harness/tools": "1.4.0-rc.1",
+    "@react-native-harness/bundler-metro": "1.4.0-rc.1"
   },
   "devDependencies": {
     "@types/yargs": "^17.0.32",

package/src/__tests__/bridge.test.ts

@@ -1,13 +1,14 @@
 /**
  * Integration test pairing createHarnessBridge (CLI side) with
  * connectToHarness (app side). Tests the full connection lifecycle and
- * RPC round-trip without knowing birpc internals.
+ * RPC round-trip without coupling tests to the transport internals.
  */
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import type { HarnessBridge } from '@react-native-harness/bridge/server';
 import { createHarnessBridge } from '@react-native-harness/bridge/server';
 import { connectToHarness } from '@react-native-harness/bridge/client';
 import type { HarnessContext } from '@react-native-harness/bridge';
+import type { TestSuiteResult } from '@react-native-harness/bridge';
 
 const makeContext = (): HarnessContext => ({
   platform: {
@@ -151,6 +152,38 @@ describe('bridge: createHarnessBridge + connectToHarness', () => {
       expect(result.tests[0].name).toBe('passes');
       handle.disconnect();
     });
+
+    it('rejects pending app calls when a newer client replaces the session', async () => {
+      const firstHandle = await connect({
+        runTests: async (): Promise<TestSuiteResult> =>
+          await new Promise<TestSuiteResult>(() => undefined),
+      });
+      firstHandle.reportReady(device);
+
+      const firstConnection = await bridge.nextConnection();
+      const pendingRun = firstConnection.runTests('example.ts', {
+        runner: '/runner.js',
+      });
+      const pendingRunAssertion = expect(pendingRun).rejects.toThrow(
+        'The app bridge was replaced by a newer app connection.',
+      );
+
+      const secondHandle = await connect();
+      secondHandle.reportReady({
+        ...device,
+        model: 'iPhone 17 Pro Replacement',
+      });
+
+      await pendingRunAssertion;
+
+      await new Promise((r) => setTimeout(r, 20));
+
+      expect(bridge.connection?.device.model).toBe(
+        'iPhone 17 Pro Replacement',
+      );
+      secondHandle.disconnect();
+      firstHandle.disconnect();
+    });
   });
 
   describe('bridge events', () => {
@@ -178,7 +211,9 @@ describe('bridge: createHarnessBridge + connectToHarness', () => {
       const pending = bridge.nextConnection();
       bridge.dispose();
 
-      await expect(pending).rejects.toThrow('Bridge disposed');
+      await expect(pending).rejects.toThrow(
+        'The app bridge was disposed before the test file finished running.',
+      );
     });
   });
 });

package/src/__tests__/crash-monitor.test.ts

@@ -1,288 +1,239 @@
 import { describe, expect, it, vi } from 'vitest';
+import path from 'node:path';
 import type {
-  AppCrashDetails,
-  AppMonitor,
-  AppMonitorEvent,
-  AppMonitorListener,
-  HarnessPlatformRunner,
+  AppSession,
+  AppSessionEvent,
+  AppSessionListener,
+  AppSessionLog,
+  AppSessionState,
 } from '@react-native-harness/platforms';
 import {
   createCrashMonitor,
   CrashWatchCancelledError,
 } from '../crash-monitor.js';
-import { NativeCrashError } from '../errors.js';
+import { NativeCrashError, RuntimeDisconnectError } from '../errors.js';
 
 const noop = () => undefined;
-const resolveUndefined = async () => undefined;
-
-// ---------------------------------------------------------------------------
-// Test doubles
-// ---------------------------------------------------------------------------
-
-const createAppMonitorMock = () => {
-  let registeredListener: AppMonitorListener | null = null;
-
-  const monitor: AppMonitor = {
-    start: vi.fn(resolveUndefined),
-    stop: vi.fn(resolveUndefined),
-    dispose: vi.fn(resolveUndefined),
-    addListener: vi.fn((l: AppMonitorListener) => {
-      registeredListener = l;
+const waitForClassification = () =>
+  new Promise((resolve) => setTimeout(resolve, 1600));
+
+const createAppSessionMock = (
+  initialState: AppSessionState = { status: 'running' },
+  logs: AppSessionLog[] = [],
+  getCrashDetails?: AppSession['getCrashDetails']
+) => {
+  let state = initialState;
+  let listener: AppSessionListener | null = null;
+
+  const session: AppSession = {
+    dispose: vi.fn(async () => undefined),
+    getState: vi.fn(async () => state),
+    getLogs: vi.fn(() => logs),
+    addListener: vi.fn((l: AppSessionListener) => {
+      listener = l;
     }),
-    removeListener: vi.fn((l: AppMonitorListener) => {
-      if (registeredListener === l) registeredListener = null;
+    removeListener: vi.fn((l: AppSessionListener) => {
+      if (listener === l) listener = null;
     }),
   };
 
+  if (getCrashDetails) {
+    session.getCrashDetails = getCrashDetails;
+  }
+
   return {
-    monitor,
-    emit: (event: AppMonitorEvent) => registeredListener?.(event),
+    session,
+    setState: (nextState: AppSessionState) => {
+      state = nextState;
+    },
+    emit: (event: AppSessionEvent) => listener?.(event),
   };
 };
 
-const createPlatformRunnerMock = (
-  isRunning = false,
-  crashDetails: AppCrashDetails | null = 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(),
-  }) as unknown as HarnessPlatformRunner;
-
-// ---------------------------------------------------------------------------
-// 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() });
+  it('starts not alive and becomes alive when an app session is attached', () => {
+    const cm = createCrashMonitor();
+    const { session } = createAppSessionMock();
 
-      emit({ type: 'app_started' });
-      const watch = cm.watch('test.ts', 'execution');
-      watch.promise.catch(noop);
+    expect(cm.isAlive()).toBe(false);
 
-      emit({ type: 'app_exited', isConfirmed: true });
-      await watch.promise.catch(noop);
+    cm.setAppSession(session);
 
-      expect(cm.isAlive()).toBe(false);
-    });
+    expect(cm.isAlive()).toBe(true);
   });
 
-  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: NativeCrashError) => 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('rejects a watch with NativeCrashError when the app session exits', async () => {
+    const { session, emit } = createAppSessionMock({
+      status: 'exited',
+      occurredAt: Date.now(),
+      reason: 'observed-exit',
     });
+    const cm = createCrashMonitor({ appSession: session });
+    const watch = cm.watch('/test/example.ts', 'execution');
+    watch.promise.catch(noop);
 
-    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 });
+    emit({ type: 'app_exited' });
 
-      await watch.promise.catch(noop);
-      // Second cancel should not throw or cause issues.
-      expect(() => watch.cancel()).not.toThrow();
-    });
+    const error = await watch.promise.catch((err: NativeCrashError) => err);
+    expect(error).toBeInstanceOf(NativeCrashError);
+    expect(error.testFilePath).toBe('/test/example.ts');
+    expect(error.details.phase).toBe('execution');
+    expect(cm.isAlive()).toBe(false);
   });
 
-  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 });
+  it('classifies bridge disconnect plus exited app as NativeCrashError', async () => {
+    const { session, setState } = createAppSessionMock();
+    const cm = createCrashMonitor({ appSession: session });
+    const watch = cm.watch('test.ts', 'execution');
+    watch.promise.catch(noop);
 
-      await expect(watch.promise).rejects.toBeInstanceOf(NativeCrashError);
+    cm.handleBridgeDisconnect();
+    setState({
+      status: 'exited',
+      occurredAt: Date.now(),
+      reason: 'process-gone',
     });
 
-    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();
-    });
+    await expect(watch.promise).rejects.toBeInstanceOf(NativeCrashError);
+  });
 
-    it('fires on possible_crash when confirmed', async () => {
-      const { monitor, emit } = createAppMonitorMock();
-      const cm = createCrashMonitor({ appMonitor: monitor, platformRunner: createPlatformRunnerMock() });
+  it('classifies bridge disconnect plus running app as RuntimeDisconnectError', async () => {
+    const { session } = createAppSessionMock({ status: 'running' });
+    const cm = createCrashMonitor({ appSession: session });
+    const watch = cm.watch('test.ts', 'execution');
+    watch.promise.catch(noop);
 
-      const watch = cm.watch('test.ts', 'execution');
-      watch.promise.catch(noop);
-      emit({ type: 'possible_crash', isConfirmed: true });
+    cm.handleBridgeDisconnect();
 
-      await expect(watch.promise).rejects.toBeInstanceOf(NativeCrashError);
-    });
+    await expect(watch.promise).rejects.toBeInstanceOf(RuntimeDisconnectError);
   });
 
-  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: NativeCrashError) => e);
-      expect(error.details.processName).toBe('MyApp');
-      expect(error.details.signal).toBe('SIGSEGV');
-      expect(error.details.pid).toBe(1234);
-    });
+  it('attaches matching session log evidence to native crash details', async () => {
+    const occurredAt = Date.now();
+    const logs = [
+      { line: 'ordinary app log', occurredAt },
+      { line: 'MyApp[123] fatal error: boom', occurredAt },
+    ];
+    const { session, setState } = createAppSessionMock(
+      { status: 'running' },
+      logs
+    );
+    const cm = createCrashMonitor({ appSession: session });
+    const watch = cm.watch('test.ts', 'execution');
+    watch.promise.catch(noop);
+
+    cm.handleBridgeDisconnect();
+    setState({ status: 'exited', occurredAt, reason: 'process-gone' });
+
+    const error = await watch.promise.catch((err: NativeCrashError) => err);
+    expect(error).toBeInstanceOf(NativeCrashError);
+    expect(error.details.rawLines).toEqual(['MyApp[123] fatal error: boom']);
   });
 
-  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));
+  it('asks the app session to extract native crash details for the current test', async () => {
+    const occurredAt = Date.now();
+    const getCrashDetails = vi.fn(async () => ({
+      artifactType: 'logcat' as const,
+      artifactPath: '/tmp/.harness/crash-reports/crash-logcat.txt',
+      processName: 'com.harnessplayground',
+      pid: 7777,
+    }));
+    const { session, setState } = createAppSessionMock(
+      { status: 'running' },
+      [],
+      getCrashDetails
+    );
+    const cm = createCrashMonitor({ appSession: session });
+    const watch = cm.watch('/test/example.ts', 'execution');
+    watch.promise.catch(noop);
+
+    cm.handleBridgeDisconnect();
+    setState({
+      status: 'exited',
+      occurredAt,
+      pid: 7777,
+      reason: 'process-gone',
+    });
+
+    const error = await watch.promise.catch((err: NativeCrashError) => err);
+
+    expect(getCrashDetails).toHaveBeenCalledWith({
+      occurredAt: expect.any(Number),
+      pid: 7777,
+      processName: undefined,
+      testFilePath: '/test/example.ts',
+    });
+    expect(error.details.artifactPath).toBe(
+      '/tmp/.harness/crash-reports/crash-logcat.txt'
+    );
+    expect(error.message).toContain(
+      `Harness extracted the crash log: ${path.relative(
+        process.cwd(),
+        '/tmp/.harness/crash-reports/crash-logcat.txt'
+      )}`
+    );
+  });
 
-      expect(settled).not.toHaveBeenCalled();
-      watch.cancel();
+  it('falls back to log details when native crash extraction fails', async () => {
+    const occurredAt = Date.now();
+    const getCrashDetails = vi.fn(async () => {
+      throw new Error('copy failed');
     });
+    const { session, setState } = createAppSessionMock(
+      { status: 'running' },
+      [{ line: 'MyApp[123] fatal error: boom', occurredAt }],
+      getCrashDetails
+    );
+    const cm = createCrashMonitor({ appSession: session });
+    const watch = cm.watch('/test/example.ts', 'execution');
+    watch.promise.catch(noop);
 
-    it('resumes monitoring after start()', async () => {
-      const { monitor, emit } = createAppMonitorMock();
-      const cm = createCrashMonitor({ appMonitor: monitor, platformRunner: createPlatformRunnerMock() });
-
-      await cm.stop();
-      await cm.start();
+    cm.handleBridgeDisconnect();
+    setState({ status: 'exited', occurredAt, reason: 'process-gone' });
 
-      const watch = cm.watch('test.ts', 'execution');
-      watch.promise.catch(noop);
-      emit({ type: 'app_exited', isConfirmed: true });
+    const error = await watch.promise.catch((err: NativeCrashError) => err);
 
-      await expect(watch.promise).rejects.toBeInstanceOf(NativeCrashError);
-    });
+    expect(error.details.rawLines).toEqual(['MyApp[123] fatal error: boom']);
+    expect(error.message).toContain("Harness couldn't extract the crash log.");
   });
 
-  describe('reset', () => {
-    it('clears alive state and pending watchers', async () => {
-      const { monitor, emit } = createAppMonitorMock();
-      const cm = createCrashMonitor({ appMonitor: monitor, platformRunner: createPlatformRunnerMock() });
+  it('settles the promise with CrashWatchCancelledError on cancel()', async () => {
+    const cm = createCrashMonitor();
+    const watch = cm.watch('test.ts', 'execution');
 
-      emit({ type: 'app_started' });
-      const watch = cm.watch('test.ts', 'execution');
-      watch.promise.catch(noop);
+    watch.cancel();
 
-      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);
-    });
+    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);
+  it('ignores session events while stopped', async () => {
+    const { session, emit } = createAppSessionMock({
+      status: 'exited',
+      occurredAt: Date.now(),
+    });
+    const cm = createCrashMonitor({ appSession: session });
+    await cm.stop();
 
-      await cm.dispose();
+    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));
+    emit({ type: 'app_exited' });
+    await waitForClassification();
 
-      // 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);
-    });
+    expect(settled).not.toHaveBeenCalled();
+    watch.cancel();
+  });
 
-    it('calls appMonitor.dispose()', async () => {
-      const { monitor } = createAppMonitorMock();
-      const cm = createCrashMonitor({ appMonitor: monitor, platformRunner: createPlatformRunnerMock() });
+  it('removes the app session listener on dispose', async () => {
+    const { session } = createAppSessionMock();
+    const cm = createCrashMonitor({ appSession: session });
 
-      await cm.dispose();
+    await cm.dispose();
 
-      expect(monitor.dispose).toHaveBeenCalledOnce();
-    });
+    expect(session.removeListener).toHaveBeenCalledOnce();
+    expect(cm.isAlive()).toBe(false);
   });
 });

package/src/__tests__/errors.test.ts

@@ -1,4 +1,6 @@
 import { describe, expect, it } from 'vitest';
+import path from 'node:path';
+import { AppBridgeDisconnectedError } from '@react-native-harness/bridge/server';
 import { NativeCrashError, PlatformReadyTimeoutError } from '../errors.js';
 
 describe('PlatformReadyTimeoutError', () => {
@@ -10,6 +12,62 @@ describe('PlatformReadyTimeoutError', () => {
 });
 
 describe('NativeCrashError', () => {
+  it('reports the extracted crash log path when available', () => {
+    const error = new NativeCrashError('/tmp/crash.harness.ts', {
+      phase: 'execution',
+      artifactPath: path.join(
+        process.cwd(),
+        '.harness',
+        'crash-reports',
+        'crash.ips'
+      ),
+    });
+
+    expect(error.message).toContain(
+      `Harness extracted the crash log: ${path.join(
+        '.harness',
+        'crash-reports',
+        'crash.ips'
+      )}`
+    );
+  });
+
+  it('lists enrichment artifact paths when available', () => {
+    const error = new NativeCrashError('/tmp/crash.harness.ts', {
+      phase: 'execution',
+      artifactPath: path.join(
+        process.cwd(),
+        '.harness',
+        'crash-reports',
+        'logcat.txt'
+      ),
+      enrichmentArtifacts: [
+        {
+          artifactType: 'dropbox-native-crash',
+          artifactPath: path.join(
+            process.cwd(),
+            '.harness',
+            'crash-reports',
+            'dropbox-native-crash.txt'
+          ),
+        },
+      ],
+    });
+
+    expect(error.message).toContain('Additional crash artifacts:');
+    expect(error.message).toContain(
+      path.join('.harness', 'crash-reports', 'dropbox-native-crash.txt')
+    );
+  });
+
+  it('reports crash log extraction failure when no artifact was pulled', () => {
+    const error = new NativeCrashError('/tmp/crash.harness.ts', {
+      phase: 'execution',
+    });
+
+    expect(error.message).toContain("Harness couldn't extract the crash log.");
+  });
+
   it('formats the extracted stack trace in the error message', () => {
     const error = new NativeCrashError('/tmp/crash.harness.ts', {
       phase: 'execution',
@@ -80,3 +138,20 @@ describe('NativeCrashError', () => {
     );
   });
 });
+
+describe('AppBridgeDisconnectedError', () => {
+  it('explains likely causes without exposing an internal stack', () => {
+    const error = new AppBridgeDisconnectedError('app-disconnected');
+
+    expect(error.message).toBe(
+      'The app bridge disconnected during test execution. This can happen if the app was killed, crashed, reloaded, or restarted while the test file was running.'
+    );
+    expect(error.stack).toBe(`AppBridgeDisconnectedError: ${error.message}`);
+  });
+
+  it('uses a reconnection-specific message when a newer app connection replaces the old one', () => {
+    expect(new AppBridgeDisconnectedError('app-replaced').message).toBe(
+      'The app bridge was replaced by a newer app connection. This can happen when the app reloads, restarts, or reconnects while a test file is still running.'
+    );
+  });
+});