Behavior of Hermes Builds When Mocking Native Modules in React Native Integration Tests

Answer

Hermes does not guarantee identical initialization of mocked native modules between debug and release builds. The likely explanation is that release builds use pre-compiled Hermes bytecode, which can evaluate modules earlier than the debug JIT path — potentially before your JS-level mock is applied. The fix is to apply mocks before any module evaluation and, when the module uses JSI host objects, to mock the native binding as well.

Confirmed facts vs. likely explanation

Confirmed: Hermes communicates with native modules via the JavaScript Interface (JSI), bypassing the asynchronous bridge. Mocking at the JavaScript layer (e.g., jest.mock) is engine-agnostic — the same mock code runs regardless of Hermes configuration. If a native module exposes JSI host objects, those bindings are created on the native side and cannot be intercepted by a JS-only mock unless the module is fully decoupled.

Likely (not definitively confirmed): The debug/release discrepancy comes from bytecode pre-compilation in release builds altering module evaluation timing, plus differences in memory management that can create race conditions during mock injection. This matches community reports but should be verified in your own setup.

Steps to eliminate JSI-related discrepancies

1. Apply the mock before any code that requires the module runs. Place jest.mock('path/to/module') at the very top of your test file or in a global setup file referenced by setupFiles in your Jest config.
2. Replace the entire module export, not just individual functions, so the native side never receives a reference to the real host object:

jest.mock('react-native-blur', () => ({
  BlurView: () => null,
  // if the module exports a host object, mock it as a plain object
  NativeBlurHost: {},
}));

1. If the module is a pure JavaScript wrapper (no JSI host objects), the JS-level mock alone is sufficient for parity. If it exposes JSI bindings, also mock the native side — either with a manual mock in __mocks__/<moduleName>.js returning an object matching the expected native interface, or by stubbing through NativeModules:

import { NativeModules } from 'react-native';
NativeModules.MyModule = { getEnv: () => 'test' };

1. Verify parity by logging the resolved module during setup in both configurations:

const mod = require('react-native-blur');
console.log(mod.NativeBlurHost); // should be the mock, not the native host

1. As an isolation check, run the same suite with Hermes disabled. If the discrepancy disappears, the issue is engine-specific (bytecode timing); if it persists, it is a general build-pipeline problem.

Recommended uniform mocking pattern

The pattern that works uniformly across both Hermes configurations is: intercept the module export in a global setup file, mock the full export surface (including any host objects as plain objects), and avoid importing the real module anywhere in test code paths. This guarantees the mock is in place before Hermes executes the bundled code, regardless of whether that code is JIT-compiled (debug) or pre-compiled bytecode (release).

One detail that changes the recommendation

Does the mocked native module expose JSI host objects or C++-bound methods, or is it a pure JavaScript wrapper? If pure JS, the JS-level mock alone guarantees parity. If it uses JSI, you must also mock the native bindings as shown above — otherwise release builds may initialize the real host object before your mock takes effect.