Add unit tests for RCTInstance eager main-queue module setup (#56919)

Summary:
Pull Request resolved: https://github.com/facebook/react-native/pull/56919

There was no unit-test coverage for `enableEagerMainQueueModulesOnIOS`, the
runtime gate that lets selected native modules initialize on the main thread
during React Native init. These characterization tests pin down the behavior
end-to-end through the real production path:

- With the flag off, `RCTInstanceDelegate.unstableModulesRequiringMainQueueSetup`
  is never consulted and no eager module is instantiated.
- With the flag on, the delegate is consulted exactly once and each returned
  module name flows through `RCTTurboModuleManager` to a real `-init` on the
  main queue.
- The JS thread that drives `_loadScriptFromSource:` blocks at the `beforeLoad`
  hook until the eager module setup completes. The bundle-load test runs init
  on a background queue, gates `FakeEagerModule.init` on a semaphore, and
  observes the `RCTInstanceDidLoadBundle` notification fired from `afterLoad` —
  asserting that by the time the gate opens, the module's constructor has fully
  returned.

The tests exercise the real `RCTModuleRegistry` + `RCTTurboModuleManager` path
(no subclass shims, no KVC into private ivars). The fixture provides a minimal
`FakeEagerModule` conforming to `<RCTBridgeModule, RCTTurboModule>` so it
survives TMM's `_shouldCreateObjCModule:` filter when interop is off.

Changelog: [Internal]

Reviewed By: sammy-SC

Differential Revision: D105953816

fbshipit-source-id: 8173ed56225587bfd86de735ead00d4d52685f1d
This commit is contained in:
Pieter De Baets authored and meta-codesync[bot] committed 2026-05-21 07:54:33 -07:00
1 parent 630e3768c4
commit 5e0fd8e229
1 file changed
+276
@@ -0,0 +1,276 @@
/*
* Copyright (c) Meta Platforms, Inc. and affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*/
#import <XCTest/XCTest.h>
#import <OCMock/OCMock.h>
#import <React/RCTBridgeModule.h>
#import <React/RCTBundleManager.h>
#import <React/RCTJavaScriptLoader.h>
#import <ReactCommon/RCTHermesInstance.h>
#import <ReactCommon/RCTInstance.h>
#import <ReactCommon/RCTTurboModule.h>
#import <ReactCommon/RCTTurboModuleManager.h>
#import <react/featureflags/ReactNativeFeatureFlags.h>
#import <react/featureflags/ReactNativeFeatureFlagsDefaults.h>
using namespace facebook::react;
namespace {
class EagerMainQueueOverride : public ReactNativeFeatureFlagsDefaults {
public:
explicit EagerMainQueueOverride(bool enabled) : enabled_(enabled) {}
bool enableEagerMainQueueModulesOnIOS() override
{
return enabled_;
}
private:
bool enabled_;
};
} // namespace
@interface FakeEagerModule : NSObject <RCTBridgeModule, RCTTurboModule>
@property (class, readonly) NSCountedSet<NSString *> *initCounts;
@property (class, nullable) void (^onInit)(void);
+ (void)reset;
@end
@implementation FakeEagerModule
static NSCountedSet<NSString *> *sInitCounts;
static void (^sOnInit)(void);
+ (NSCountedSet<NSString *> *)initCounts
{
if (sInitCounts == nil) {
sInitCounts = [NSCountedSet new];
}
return sInitCounts;
}
+ (void)setOnInit:(void (^)(void))block
{
sOnInit = [block copy];
}
+ (void (^)(void))onInit
{
return sOnInit;
}
+ (NSString *)moduleName
{
return @"FakeEagerModule";
}
+ (BOOL)requiresMainQueueSetup
{
return YES;
}
+ (void)reset
{
[[FakeEagerModule initCounts] removeAllObjects];
sOnInit = nil;
}
- (instancetype)init
{
if (self = [super init]) {
// Block FIRST, then bump the counter. This way "init has fully completed"
// is observable as count == 1, distinct from "init has been entered".
if (sOnInit) {
sOnInit();
}
@synchronized([FakeEagerModule initCounts]) {
[[FakeEagerModule initCounts] addObject:[[self class] moduleName]];
}
}
return self;
}
- (std::shared_ptr<facebook::react::TurboModule>)getTurboModule:
(const facebook::react::ObjCTurboModule::InitParams &)params
{
return nullptr;
}
@end
@interface RCTInstanceTests : XCTestCase
@end
@implementation RCTInstanceTests {
id<RCTInstanceDelegate> _mockDelegate;
id<RCTTurboModuleManagerDelegate> _mockTMMDelegate;
id _bundleLoadObserver;
}
- (void)setUp
{
[super setUp];
ReactNativeFeatureFlags::dangerouslyReset();
[FakeEagerModule reset];
_mockDelegate = OCMProtocolMock(@protocol(RCTInstanceDelegate));
_mockTMMDelegate = OCMProtocolMock(@protocol(RCTTurboModuleManagerDelegate));
// Match only FakeEagerModule by name; anything else returns nil so unrelated
// lookups (RCTDevMenu, RCTImageLoader, ...) don't accidentally instantiate it.
OCMStub([_mockTMMDelegate getModuleClassFromName:nullptr]).ignoringNonObjectArgs().andDo(^(NSInvocation *invocation) {
const char *requestedName = nullptr;
[invocation getArgument:&requestedName atIndex:2];
Class result =
(requestedName != nullptr && strcmp(requestedName, "FakeEagerModule") == 0) ? [FakeEagerModule class] : Nil;
[invocation setReturnValue:&result];
});
}
- (void)tearDown
{
if (_bundleLoadObserver != nil) {
[[NSNotificationCenter defaultCenter] removeObserver:_bundleLoadObserver];
_bundleLoadObserver = nil;
}
ReactNativeFeatureFlags::dangerouslyReset();
[FakeEagerModule reset];
_mockDelegate = nil;
_mockTMMDelegate = nil;
[super tearDown];
}
- (RCTInstance *)makeInstance
{
RCTBundleManager *bundleManager = [RCTBundleManager new];
// bundleURL asserts the bridgeless getter is non-nil; without it the NSException
// unwinds the JS-thread init callback before reaching _loadJSBundle:.
NSURL * (^urlGetter)(void) = ^{
return [NSURL URLWithString:@"file:///empty.bundle"];
};
[bundleManager setBridgelessBundleURLGetter:urlGetter
andSetter:^(NSURL *_) {
}
andDefaultGetter:urlGetter];
return [[RCTInstance alloc] initWithDelegate:_mockDelegate
jsRuntimeFactory:std::make_shared<RCTHermesInstance>()
bundleManager:bundleManager
turboModuleManagerDelegate:_mockTMMDelegate
moduleRegistry:[RCTModuleRegistry new]
parentInspectorTarget:nullptr
launchOptions:nil];
}
- (void)testFlagOff_doesNotConsultDelegate
{
OCMReject([_mockDelegate unstableModulesRequiringMainQueueSetup]);
RCTInstance *instance = [self makeInstance];
XCTAssertEqual([FakeEagerModule.initCounts countForObject:FakeEagerModule.moduleName], 0u);
[instance invalidate];
}
- (void)testFlagOn_consultsDelegateExactlyOnce
{
ReactNativeFeatureFlags::override(std::make_unique<EagerMainQueueOverride>(true));
OCMStub([_mockDelegate unstableModulesRequiringMainQueueSetup]).andReturn(@[]);
RCTInstance *instance = [self makeInstance];
OCMVerify(OCMTimes(1), [_mockDelegate unstableModulesRequiringMainQueueSetup]);
[instance invalidate];
}
- (void)testFlagOn_instantiatesRequestedModuleOnMainQueue
{
ReactNativeFeatureFlags::override(std::make_unique<EagerMainQueueOverride>(true));
OCMStub([_mockDelegate unstableModulesRequiringMainQueueSetup]).andReturn(@[ FakeEagerModule.moduleName ]);
RCTInstance *instance = [self makeInstance];
XCTAssertEqual(
[FakeEagerModule.initCounts countForObject:FakeEagerModule.moduleName],
1u,
@"FakeEagerModule should have been constructed exactly once during eager setup");
[instance invalidate];
}
- (void)testFlagOn_bundleLoadAwaitsMainQueueModuleSetup
{
ReactNativeFeatureFlags::override(std::make_unique<EagerMainQueueOverride>(true));
OCMStub([_mockDelegate unstableModulesRequiringMainQueueSetup]).andReturn(@[ FakeEagerModule.moduleName ]);
// Hand the instance an empty bundle the moment it asks for one. The JS thread
// will then drive _loadScriptFromSource: which invokes the wait block before
// evaluating the script. RCTInstance posts RCTInstanceDidLoadBundle from the
// `afterLoad` lambda, i.e. after the wait block has returned.
RCTSource *emptySource = OCMClassMock([RCTSource class]);
OCMStub([emptySource url]).andReturn([NSURL URLWithString:@"file:///empty.bundle"]);
OCMStub([emptySource data]).andReturn([NSData data]);
OCMStub([_mockDelegate loadBundleAtURL:[OCMArg any] onProgress:[OCMArg any] onComplete:[OCMArg any]])
.andDo(^(NSInvocation *invocation) {
__unsafe_unretained RCTSourceLoadBlock onComplete;
[invocation getArgument:&onComplete atIndex:4];
onComplete(nil, emptySource);
});
dispatch_semaphore_t initEntered = dispatch_semaphore_create(0);
dispatch_semaphore_t releaseInit = dispatch_semaphore_create(0);
FakeEagerModule.onInit = ^{
dispatch_semaphore_signal(initEntered);
dispatch_semaphore_wait(releaseInit, DISPATCH_TIME_FOREVER);
};
XCTestExpectation *bundleLoaded = [self expectationWithDescription:@"RCTInstanceDidLoadBundle"];
__block NSUInteger initCountAtBundleLoad = 0;
_bundleLoadObserver = [[NSNotificationCenter defaultCenter]
addObserverForName:@"RCTInstanceDidLoadBundle"
object:nil
queue:nil
usingBlock:^(NSNotification *_) {
initCountAtBundleLoad = [FakeEagerModule.initCounts countForObject:FakeEagerModule.moduleName];
[bundleLoaded fulfill];
}];
XCTestExpectation *done = [self expectationWithDescription:@"orchestration complete"];
__block RCTInstance *instance = nil;
// Orchestration runs off-main so the main thread is free to service the
// RCTExecuteOnMainQueue block from _start, where FakeEagerModule.init runs.
dispatch_async(dispatch_get_global_queue(QOS_CLASS_USER_INITIATED, 0), ^{
instance = [self makeInstance];
XCTAssertEqual(
dispatch_semaphore_wait(initEntered, dispatch_time(DISPATCH_TIME_NOW, 5 * NSEC_PER_SEC)),
0,
@"FakeEagerModule -init did not run on main queue within timeout");
// Releasing here unblocks main-queue setup, which signals the wait block,
// which lets the JS thread proceed past `beforeLoad` and post the bundle
// notification.
dispatch_semaphore_signal(releaseInit);
[done fulfill];
});
// Invalidate AFTER the notification fires; otherwise `_valid = false` makes
// _loadScriptFromSource: short-circuit and `afterLoad` never runs.
[self waitForExpectations:@[ bundleLoaded, done ] timeout:10.0];
[instance invalidate];
XCTAssertEqual(
initCountAtBundleLoad,
1u,
@"FakeEagerModule -init must have fully returned before the JS bundle finishes loading");
}
@end