@react-native-firebase/app 26.3.3 → 27.0.0

package/ios/RNFBAppUnitTests/RNFBMetaTests.m

@@ -0,0 +1,65 @@
+/**
+ * Copyright (c) 2016-present Invertase Limited & Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this library except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#import <XCTest/XCTest.h>
+
+#import "RNFBHandleMapStorage-Swift.inc"
+#import "RNFBMeta.h"
+
+@interface RNFBMetaTests : XCTestCase
+@end
+
+@implementation RNFBMetaTests
+
+- (void)testPublicClassSelectorsAndReturnEncodingsAreUnchanged {
+  NSArray<NSString *> *selectorNames = @[
+    @"contains:",
+    @"getBooleanValue:defaultValue:",
+    @"getStringValue:defaultValue:",
+    @"getAll",
+  ];
+  for (NSString *selectorName in selectorNames) {
+    XCTAssertTrue([RNFBMeta respondsToSelector:NSSelectorFromString(selectorName)]);
+  }
+
+  NSMethodSignature *contains = [RNFBMeta methodSignatureForSelector:@selector(contains:)];
+  XCTAssertEqual(strcmp(contains.methodReturnType, @encode(BOOL)), 0);
+
+  NSMethodSignature *boolean = [RNFBMeta methodSignatureForSelector:@selector(getBooleanValue:
+                                                                                 defaultValue:)];
+  XCTAssertEqual(strcmp(boolean.methodReturnType, @encode(BOOL)), 0);
+  XCTAssertEqual(strcmp([boolean getArgumentTypeAtIndex:3], @encode(BOOL)), 0);
+
+  NSMethodSignature *string = [RNFBMeta methodSignatureForSelector:@selector(getStringValue:
+                                                                               defaultValue:)];
+  XCTAssertEqual(strcmp(string.methodReturnType, @encode(id)), 0);
+
+  NSMethodSignature *getAll = [RNFBMeta methodSignatureForSelector:@selector(getAll)];
+  XCTAssertEqual(strcmp(getAll.methodReturnType, @encode(id)), 0);
+}
+
+- (void)testFacadeForwardsToSharedMainBundleStorage {
+  // Smoke: class methods are callable and getAll returns a dictionary (may be empty).
+  XCTAssertNotNil([RNFBMeta getAll]);
+  XCTAssertTrue([[RNFBMeta getAll] isKindOfClass:[NSDictionary class]]);
+  XCTAssertFalse([RNFBMeta contains:@"__rnfb_meta_unit_test_missing_key__"]);
+  XCTAssertTrue([RNFBMeta getBooleanValue:@"__rnfb_meta_unit_test_missing_key__" defaultValue:YES]);
+  XCTAssertEqualObjects([RNFBMeta getStringValue:@"__rnfb_meta_unit_test_missing_key__"
+                                    defaultValue:@"fallback"],
+                        @"fallback");
+}
+
+@end

package/ios/RNFBAppUnitTests/RNFBNullSentinelDecodingTests.swift

@@ -0,0 +1,286 @@
+/**
+ * Copyright (c) 2016-present Invertase Limited & Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this library except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import Foundation
+import XCTest
+
+final class RNFBNullSentinelDecodingTests: XCTestCase {
+  private func decode(_ value: Any?) -> Any? {
+    RNFBNullSentinelDecoder.decodeNullSentinels(value)
+  }
+
+  private func sentinel(_ flag: Any = true) -> NSDictionary {
+    ["__rnfbNull": flag] as NSDictionary
+  }
+
+  private func serverTimestamp() -> NSDictionary {
+    [".sv": "timestamp"] as NSDictionary
+  }
+
+  func testNilAndNonContainersPreserveIdentity() {
+    XCTAssertNil(decode(nil))
+
+    let number = NSNumber(value: 42)
+    let string = "hello" as NSString
+    let date = NSDate()
+    let data = NSData()
+    let null = NSNull()
+
+    XCTAssertTrue(decode(number) as AnyObject === number)
+    XCTAssertTrue(decode(string) as AnyObject === string)
+    XCTAssertTrue(decode(date) as AnyObject === date)
+    XCTAssertTrue(decode(data) as AnyObject === data)
+    XCTAssertTrue(decode(null) as AnyObject === null)
+  }
+
+  func testDecodeAndDecodeNullSentinelsSelectorsAreEquivalent() {
+    let input: NSDictionary = ["a": sentinel(), "b": "keep"]
+    let viaCanonical = RNFBNullSentinelDecoder.decodeNullSentinels(input) as! NSDictionary
+    let viaAlias = RNFBNullSentinelDecoder.decode(input) as! NSDictionary
+    XCTAssertEqual(viaCanonical, viaAlias)
+    XCTAssertTrue(viaCanonical["a"] is NSNull)
+    XCTAssertEqual(viaCanonical["b"] as? String, "keep")
+  }
+
+  func testRootSentinelBecomesNSNull() {
+    XCTAssertTrue(decode(sentinel()) is NSNull)
+    XCTAssertTrue(decode(sentinel(NSNumber(value: 1))) is NSNull)
+  }
+
+  func testRootSentinelRequiresExactlyOneKeyAndTruthyFlag() {
+    XCTAssertFalse(decode(sentinel(false)) is NSNull)
+    XCTAssertEqual(decode(sentinel(false)) as? NSDictionary, ["__rnfbNull": false] as NSDictionary)
+
+    let extraKey = ["__rnfbNull": true, "other": 1] as NSDictionary
+    XCTAssertEqual(decode(extraKey) as? NSDictionary, extraKey)
+
+    let empty = decode(NSDictionary()) as! NSDictionary
+    XCTAssertEqual(empty.count, 0)
+    XCTAssertTrue(empty is NSMutableDictionary)
+  }
+
+  func testStringFlagIsNotASentinel() {
+    for flag in ["true", "YES", "yes", "1"] as [NSString] {
+      let input = sentinel(flag)
+      XCTAssertEqual(decode(input) as? NSDictionary, input)
+    }
+  }
+
+  func testNonBoolRespondingFlagIsNotASentinel() {
+    let exotic = sentinel(NSDate())
+    let decoded = decode(exotic) as! NSDictionary
+    XCTAssertEqual(decoded.count, 1)
+    XCTAssertTrue(decoded["__rnfbNull"] is NSDate)
+  }
+
+  func testRootSentinelFlagNonNumberUnchangedWithoutCrash() {
+    let nullFlag = ["__rnfbNull": NSNull()] as NSDictionary
+    let dictFlag = ["__rnfbNull": ["a": 1] as NSDictionary] as NSDictionary
+    let arrayFlag = ["__rnfbNull": [1] as NSArray] as NSDictionary
+
+    XCTAssertEqual(decode(nullFlag) as? NSDictionary, nullFlag)
+    XCTAssertEqual(decode(dictFlag) as? NSDictionary, dictFlag)
+    XCTAssertEqual(decode(arrayFlag) as? NSDictionary, arrayFlag)
+  }
+
+  func testRootServerValueUnchanged() {
+    let input = serverTimestamp()
+    XCTAssertEqual(decode(input) as? NSDictionary, input)
+  }
+
+  func testNestedDictionarySentinelsBecomeNSNull() {
+    let input: NSDictionary = [
+      "a": sentinel(),
+      "b": "keep",
+      "nested": [
+        "inner": sentinel(),
+        "n": 1,
+        "falseFlag": sentinel(false),
+        "empty": NSDictionary(),
+      ] as NSDictionary,
+    ]
+
+    let result = decode(input) as! NSDictionary
+    XCTAssertTrue(result["a"] is NSNull)
+    XCTAssertEqual(result["b"] as? String, "keep")
+    let nested = result["nested"] as! NSDictionary
+    XCTAssertTrue(nested["inner"] is NSNull)
+    XCTAssertEqual(nested["n"] as? Int, 1)
+    XCTAssertEqual(nested["falseFlag"] as? NSDictionary, ["__rnfbNull": false] as NSDictionary)
+    XCTAssertEqual((nested["empty"] as? NSDictionary)?.count, 0)
+  }
+
+  func testNestedSentinelWithExtraKeysUnchanged() {
+    let input: NSDictionary = ["child": ["__rnfbNull": true, "other": "x"] as NSDictionary]
+    XCTAssertEqual(decode(input) as? NSDictionary, input)
+  }
+
+  func testNestedSentinelFlagNonNumberUnchanged() {
+    let input: NSDictionary = [
+      "nullFlag": ["__rnfbNull": NSNull()] as NSDictionary,
+      "dictFlag": ["__rnfbNull": ["a": 1] as NSDictionary] as NSDictionary,
+      "arrayFlag": ["__rnfbNull": [1] as NSArray] as NSDictionary,
+      "stringFlag": ["__rnfbNull": "true"] as NSDictionary,
+    ]
+    XCTAssertEqual(decode(input) as? NSDictionary, input)
+
+    let arrayInput: NSArray = [
+      ["__rnfbNull": NSNull()] as NSDictionary,
+      ["__rnfbNull": ["a": 1] as NSDictionary] as NSDictionary,
+      ["__rnfbNull": [1] as NSArray] as NSDictionary,
+      ["__rnfbNull": "true"] as NSDictionary,
+    ]
+    XCTAssertEqual(decode(arrayInput) as? NSArray, arrayInput)
+  }
+
+  func testValidSentinelSiblingDecodedWhileNonNumberFlagPassesThrough() {
+    let input: NSDictionary = [
+      "valid": sentinel(),
+      "guarded": ["__rnfbNull": NSNull()] as NSDictionary,
+      "list": [sentinel(), ["__rnfbNull": [1] as NSArray] as NSDictionary] as NSArray,
+    ]
+    let result = decode(input) as! NSDictionary
+    XCTAssertTrue(result["valid"] is NSNull)
+    XCTAssertEqual(result["guarded"] as? NSDictionary, ["__rnfbNull": NSNull()] as NSDictionary)
+    let list = result["list"] as! NSArray
+    XCTAssertTrue(list[0] is NSNull)
+    XCTAssertEqual(list[1] as? NSDictionary, ["__rnfbNull": [1] as NSArray] as NSDictionary)
+  }
+
+  func testArrayWalkPreservesNSNullAndReplacesSentinels() {
+    let input: NSArray = [
+      sentinel(),
+      NSNull(),
+      "x",
+      3,
+      serverTimestamp(),
+      [sentinel(), 2] as NSArray,
+    ]
+
+    let result = decode(input) as! NSArray
+    XCTAssertEqual(result.count, 6)
+    XCTAssertTrue(result[0] is NSNull)
+    XCTAssertTrue(result[1] is NSNull)
+    XCTAssertEqual(result[2] as? String, "x")
+    XCTAssertEqual(result[3] as? Int, 3)
+    XCTAssertEqual(result[4] as? NSDictionary, serverTimestamp())
+    let nested = result[5] as! NSArray
+    XCTAssertTrue(nested[0] is NSNull)
+    XCTAssertEqual(nested[1] as? Int, 2)
+    XCTAssertTrue(result is NSMutableArray)
+  }
+
+  func testRootEmptyArrayReturnsEmptyMutableArray() {
+    let decoded = decode([] as NSArray) as! NSArray
+    XCTAssertEqual(decoded.count, 0)
+    XCTAssertTrue(decoded is NSMutableArray)
+  }
+
+  func testNestedArraysSentinelsDecodedAtEveryLevel() {
+    let input: NSArray = [[sentinel(), [sentinel(), "leaf"] as NSArray] as NSArray, [] as NSArray]
+    let result = decode(input) as! NSArray
+    let first = result[0] as! NSArray
+    XCTAssertTrue(first[0] is NSNull)
+    XCTAssertTrue((first[1] as! NSArray)[0] is NSNull)
+    XCTAssertEqual((first[1] as! NSArray)[1] as? String, "leaf")
+    XCTAssertEqual((result[1] as! NSArray).count, 0)
+  }
+
+  func testArrayInsideDictionaryAndMixedMatrixDecoded() {
+    let input: NSDictionary = [
+      "list": [sentinel(), "x", [sentinel()] as NSArray] as NSArray,
+      "items": [
+        ["id": 1, "note": sentinel()] as NSDictionary,
+        ["id": 2, "tags": [sentinel()] as NSArray] as NSDictionary,
+      ] as NSArray,
+    ]
+    let result = decode(input) as! NSDictionary
+    let list = result["list"] as! NSArray
+    XCTAssertTrue(list[0] is NSNull)
+    XCTAssertEqual(list[1] as? String, "x")
+    XCTAssertTrue((list[2] as! NSArray)[0] is NSNull)
+
+    let items = result["items"] as! NSArray
+    XCTAssertTrue((items[0] as! NSDictionary)["note"] is NSNull)
+    XCTAssertTrue(((items[1] as! NSDictionary)["tags"] as! NSArray)[0] is NSNull)
+  }
+
+  func testChildAndParentTypeMatrix() {
+    let dictInput: NSDictionary = [
+      "dictChild": ["k": 1] as NSDictionary,
+      "arrayChild": ["leaf", [2] as NSArray, sentinel(), NSNull()] as NSArray,
+      "primitiveChild": "text",
+      "nullChild": NSNull(),
+    ]
+    let arrayRoot: NSArray = [
+      ["inner": sentinel()] as NSDictionary,
+      ["nested"] as NSArray,
+      3,
+      sentinel(),
+      NSNull(),
+    ]
+
+    let decodedDict = decode(dictInput) as! NSDictionary
+    XCTAssertEqual(decodedDict["dictChild"] as? NSDictionary, ["k": 1] as NSDictionary)
+    let arrayChild = decodedDict["arrayChild"] as! NSArray
+    XCTAssertEqual(arrayChild[0] as? String, "leaf")
+    XCTAssertTrue(arrayChild[2] is NSNull)
+    XCTAssertTrue(decodedDict["nullChild"] is NSNull)
+
+    let decodedArray = decode(arrayRoot) as! NSArray
+    XCTAssertTrue((decodedArray[0] as! NSDictionary)["inner"] is NSNull)
+    XCTAssertTrue(decodedArray[3] is NSNull)
+    XCTAssertTrue(decodedArray[4] is NSNull)
+  }
+
+  func testContainersReturnNewMutableCopiesEvenWithoutSentinels() {
+    let dict = ["k": "v"] as NSDictionary
+    let array = ["a", 1] as NSArray
+
+    let decodedDict = decode(dict)
+    let decodedArray = decode(array)
+
+    XCTAssertFalse(decodedDict as AnyObject === dict)
+    XCTAssertFalse(decodedArray as AnyObject === array)
+    XCTAssertTrue(decodedDict is NSMutableDictionary)
+    XCTAssertTrue(decodedArray is NSMutableArray)
+    XCTAssertEqual(decodedDict as? NSDictionary, dict)
+    XCTAssertEqual(decodedArray as? NSArray, array)
+  }
+
+  func testCountOneNumberFalseIsNotSentinel() {
+    let input: NSDictionary = [
+      "a": ["__rnfbNull": false] as NSDictionary,
+      "b": ["__rnfbNull": NSNumber(value: 0)] as NSDictionary,
+    ]
+    XCTAssertEqual(decode(input) as? NSDictionary, input)
+  }
+
+  func testDeepNestingDoesNotOverflow() {
+    let depth = 1000
+    var leaf: Any = ["value": sentinel()] as NSDictionary
+    for _ in 0..<depth {
+      leaf = ["child": leaf] as NSDictionary
+    }
+
+    var cursor = decode(leaf) as! NSDictionary
+    for _ in 0..<depth {
+      XCTAssertTrue(cursor is NSMutableDictionary)
+      cursor = cursor["child"] as! NSDictionary
+    }
+    XCTAssertTrue(cursor["value"] is NSNull)
+  }
+}

package/ios/RNFBAppUnitTests/RNFBNullSentinelInterceptorTests.m

@@ -0,0 +1,312 @@
+/**
+ * Copyright (c) 2016-present Invertase Limited & Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this library except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+#import <XCTest/XCTest.h>
+#import <objc/runtime.h>
+
+#import "RNFBNullSentinelInterceptor.h"
+
+/** Set by the original (pre-swizzle) IMPs of every runtime-created stand-in class. */
+static id gLastJsonSeenByOriginalIMP = nil;
+
+static NSString *const kSpecSelector = @"JS_NativeRNFBTurboFunctions_SpecHttpsCallableData:";
+/** Prefix matches JS_NativeRNFBTurbo* but lacks _Spec: must not be wrapped. */
+static NSString *const kNotASpecSelector = @"JS_NativeRNFBTurboFunctions_NotASpecMethod:";
+static NSString *const kUnrelatedSelector = @"unrelatedConverter:";
+static NSString *const kCxxConvertSpecSelector = @"JS_NativeRNFBTurboApp_SpecData:";
+static NSString *const kCxxConvertClassName = @"RCTCxxConvert";
+
+@interface RNFBNullSentinelInterceptorTests : XCTestCase
+@end
+
+/**
+ * Each test that needs a class builds its own uniquely named one at runtime and disposes of it in
+ * tearDown, so no test observes IMP wrapping or a global RCTCxxConvert registered by another test.
+ * That makes the suite independent of XCTest execution order and safe to run singly.
+ */
+@implementation RNFBNullSentinelInterceptorTests {
+  // Class pointers are stored as NSValue so ARC never retains/releases a class after disposal.
+  // Per-test stand-ins: scheduled blocks may capture these, so tearDown spares them on a drain
+  // timeout.
+  NSMutableArray<NSValue *> *_standInClasses;
+  // Fake global RCTCxxConvert: nothing queued captures it, so tearDown always disposes it.
+  NSMutableArray<NSValue *> *_globalClasses;
+  // Class pointer -> the IMPs of the block-backed methods this test added to it.
+  NSMutableDictionary<NSValue *, NSArray<NSValue *> *> *_originalIMPsByClass;
+  // Heap-allocated dispatch_once_t storage (see -newOnceToken), freed in tearDown.
+  NSMutableArray<NSValue *> *_onceTokens;
+}
+
+- (void)setUp {
+  [super setUp];
+  gLastJsonSeenByOriginalIMP = nil;
+  _standInClasses = [NSMutableArray array];
+  _globalClasses = [NSMutableArray array];
+  _originalIMPsByClass = [NSMutableDictionary dictionary];
+  _onceTokens = [NSMutableArray array];
+}
+
+- (void)tearDown {
+  // schedule...WithOnceToken: dispatches a block to the main queue that captures the once token
+  // pointer and the stand-in class. Drain the main queue (FIFO, so every block queued by the test
+  // has run once the drain block does) before disposing those or freeing the token. If the drain
+  // times out, leak them instead of risking a use-after-free in a late block. The global
+  // RCTCxxConvert is never captured by a queued block, so it is always disposed; otherwise a
+  // leaked registration would fail every later RCTCxxConvert test.
+  BOOL drained = [self drainMainQueue];
+  [self disposeClasses:_globalClasses];
+  if (drained) {
+    [self disposeClasses:_standInClasses];
+    for (NSValue *tokenValue in _onceTokens) {
+      free(tokenValue.pointerValue);
+    }
+  }
+  [_standInClasses removeAllObjects];
+  [_globalClasses removeAllObjects];
+  [_originalIMPsByClass removeAllObjects];
+  [_onceTokens removeAllObjects];
+  gLastJsonSeenByOriginalIMP = nil;
+  [super tearDown];
+}
+
+/**
+ * Disposes of the given classes and removes their block-backed IMPs. Each block IMP must be
+ * removed exactly once (a second imp_removeBlock crashes), so gather the unique set per class: the
+ * original stand-in IMPs plus any wrapper IMPs the interceptor swizzled in.
+ */
+- (void)disposeClasses:(NSArray<NSValue *> *)classValues {
+  for (NSValue *classValue in classValues) {
+    __unsafe_unretained Class cls = (__bridge Class)classValue.pointerValue;
+    NSMutableSet<NSValue *> *blockIMPs =
+        [NSMutableSet setWithArray:_originalIMPsByClass[classValue] ?: @[]];
+    unsigned int count = 0;
+    Method *methods = class_copyMethodList(object_getClass(cls), &count);
+    for (unsigned int i = 0; i < count; i++) {
+      [blockIMPs
+          addObject:[NSValue valueWithPointer:(const void *)method_getImplementation(methods[i])]];
+    }
+    free(methods);
+    objc_disposeClassPair(cls);
+    for (NSValue *value in blockIMPs) {
+      imp_removeBlock((IMP)value.pointerValue);
+    }
+  }
+}
+
+/**
+ * Creates and registers a class named `name` whose class methods (one per selector name) record
+ * the received json in gLastJsonSeenByOriginalIMP and return it. Disposed in tearDown. `global`
+ * marks a class registered under a well-known global name (RCTCxxConvert).
+ */
+- (Class)registerClassNamed:(NSString *)name
+              selectorNames:(NSArray<NSString *> *)selectorNames
+                     global:(BOOL)global {
+  Class cls = objc_allocateClassPair([NSObject class], name.UTF8String, 0);
+  XCTAssertTrue(cls != Nil, @"could not allocate class %@", name);
+  if (cls == Nil) {
+    return Nil;
+  }
+  Class meta = object_getClass(cls);
+  NSMutableArray<NSValue *> *imps = [NSMutableArray array];
+  for (NSString *selectorName in selectorNames) {
+    IMP imp = imp_implementationWithBlock(^id(__unused id receiver, id json) {
+      gLastJsonSeenByOriginalIMP = json;
+      return json;
+    });
+    BOOL added = class_addMethod(meta, NSSelectorFromString(selectorName), imp, "@@:@");
+    XCTAssertTrue(added, @"could not add class method %@ to %@", selectorName, name);
+    [imps addObject:[NSValue valueWithPointer:(const void *)imp]];
+  }
+  objc_registerClassPair(cls);
+  NSValue *classValue = [NSValue valueWithPointer:(__bridge const void *)cls];
+  _originalIMPsByClass[classValue] = imps;
+  [global ? _globalClasses : _standInClasses addObject:classValue];
+  return cls;
+}
+
+/** Stand-in for RCTCxxConvert codegen categories, uniquely named per call. */
+- (Class)makeStandInConvertClass {
+  static NSUInteger counter = 0;  // XCTest runs test methods serially on one thread.
+  NSString *name =
+      [NSString stringWithFormat:@"RNFBNullSentinelStandInConvert_%lu", (unsigned long)++counter];
+  return [self registerClassNamed:name
+                    selectorNames:@[ kSpecSelector, kNotASpecSelector, kUnrelatedSelector ]
+                           global:NO];
+}
+
+- (NSDictionary *)nullSentinel {
+  return @{@"__rnfbNull" : @YES};
+}
+
+- (NSDictionary *)unrelatedOneKeyDictionary {
+  return @{@".sv" : @"timestamp"};
+}
+
+- (IMP)classMethodIMP:(Class)cls selector:(SEL)selector {
+  Method method = class_getClassMethod(cls, selector);
+  XCTAssertTrue(method != NULL, @"missing class method %@", NSStringFromSelector(selector));
+  return method_getImplementation(method);
+}
+
+/** Invokes the class method's current IMP, so swizzled wrappers are exercised. */
+- (id)callConvert:(Class)cls selectorName:(NSString *)selectorName json:(id)json {
+  typedef id (*ConvertFunc)(id, SEL, id);
+  SEL selector = NSSelectorFromString(selectorName);
+  ConvertFunc convert = (ConvertFunc)[self classMethodIMP:cls selector:selector];
+  return convert(cls, selector, json);
+}
+
+/**
+ * Heap-allocated once token. A stack token would dangle if a dispatched block ran after the test
+ * method returned. Freed in tearDown, after the main queue is drained.
+ */
+- (dispatch_once_t *)newOnceToken {
+  dispatch_once_t *token = calloc(1, sizeof(dispatch_once_t));
+  [_onceTokens addObject:[NSValue valueWithPointer:token]];
+  return token;
+}
+
+/** Returns YES once every main-queue block queued before this call has run. */
+- (BOOL)drainMainQueue {
+  XCTestExpectation *drained = [self expectationWithDescription:@"main queue drained"];
+  dispatch_async(dispatch_get_main_queue(), ^{
+    [drained fulfill];
+  });
+  XCTWaiterResult result = [XCTWaiter waitForExpectations:@[ drained ] timeout:2.0];
+  XCTAssertEqual(result, XCTWaiterResultCompleted, @"main queue did not drain in time");
+  return result == XCTWaiterResultCompleted;
+}
+
+- (void)testSwizzleTurboModuleConversions_nullSentinel_handsNSNullToOriginalIMP {
+  Class standIn = [self makeStandInConvertClass];
+  SEL selector = NSSelectorFromString(kSpecSelector);
+  IMP before = [self classMethodIMP:standIn selector:selector];
+
+  [RNFBNullSentinelInterceptor swizzleTurboModuleConversions:standIn];
+
+  IMP after = [self classMethodIMP:standIn selector:selector];
+  XCTAssertNotEqual(before, after);
+
+  gLastJsonSeenByOriginalIMP = nil;
+  id result = [self callConvert:standIn selectorName:kSpecSelector json:[self nullSentinel]];
+  XCTAssertEqualObjects(gLastJsonSeenByOriginalIMP, [NSNull null]);
+  XCTAssertEqualObjects(result, [NSNull null]);
+}
+
+- (void)testSwizzleTurboModuleConversions_unrelatedOneKeyDictionary_unchanged {
+  Class standIn = [self makeStandInConvertClass];
+  [RNFBNullSentinelInterceptor swizzleTurboModuleConversions:standIn];
+
+  gLastJsonSeenByOriginalIMP = nil;
+  NSDictionary *payload = [self unrelatedOneKeyDictionary];
+  id result = [self callConvert:standIn selectorName:kSpecSelector json:payload];
+
+  XCTAssertEqualObjects(gLastJsonSeenByOriginalIMP, payload);
+  XCTAssertEqualObjects(result, payload);
+}
+
+- (void)testScheduleSwizzle_doesNotSwizzleUntilMainQueueRuns {
+  Class standIn = [self makeStandInConvertClass];
+  SEL selector = NSSelectorFromString(kSpecSelector);
+  IMP before = [self classMethodIMP:standIn selector:selector];
+
+  dispatch_once_t *onceToken = [self newOnceToken];
+  [RNFBNullSentinelInterceptor scheduleSwizzleOnMainQueueWithOnceToken:onceToken
+                                                     turboConvertClass:standIn];
+
+  IMP afterSchedule = [self classMethodIMP:standIn selector:selector];
+  XCTAssertEqual(before, afterSchedule, @"swizzle must not run synchronously from schedule");
+
+  [self drainMainQueue];
+
+  IMP afterDrain = [self classMethodIMP:standIn selector:selector];
+  XCTAssertNotEqual(before, afterDrain, @"swizzle must run once the main queue drains");
+
+  gLastJsonSeenByOriginalIMP = nil;
+  [self callConvert:standIn selectorName:kSpecSelector json:[self nullSentinel]];
+  XCTAssertEqualObjects(gLastJsonSeenByOriginalIMP, [NSNull null]);
+}
+
+- (void)testScheduleSwizzle_secondCallDoesNotDoubleWrap {
+  Class standIn = [self makeStandInConvertClass];
+  SEL selector = NSSelectorFromString(kSpecSelector);
+
+  dispatch_once_t *onceToken = [self newOnceToken];
+  [RNFBNullSentinelInterceptor scheduleSwizzleOnMainQueueWithOnceToken:onceToken
+                                                     turboConvertClass:standIn];
+  [self drainMainQueue];
+  IMP afterFirst = [self classMethodIMP:standIn selector:selector];
+
+  [RNFBNullSentinelInterceptor scheduleSwizzleOnMainQueueWithOnceToken:onceToken
+                                                     turboConvertClass:standIn];
+  [self drainMainQueue];
+  IMP afterSecond = [self classMethodIMP:standIn selector:selector];
+
+  XCTAssertEqual(afterFirst, afterSecond, @"dispatch_once must prevent a second IMP wrap");
+}
+
+// Nil arm of `if (cxxConvertClass)`.
+// Precondition: the unit host has no React runtime (RNFBAppUnitTests.xcodeproj links no React), so
+// RCTCxxConvert is absent. The original missing-case test made the same assumption. The only test
+// that registers a global RCTCxxConvert (the "present" test) disposes of it in tearDown, so the
+// class is also absent here regardless of which test ran first.
+- (void)testSwizzleRCTConvertMethods_missingRCTCxxConvert_isNoOp {
+  XCTAssertNil(NSClassFromString(kCxxConvertClassName));
+  XCTAssertNoThrow([RNFBNullSentinelInterceptor swizzleRCTConvertMethods]);
+}
+
+// Non-nil arm of `if (cxxConvertClass)`. Registers a global RCTCxxConvert stand-in (disposed in
+// tearDown). Same no-React-in-the-host precondition as the missing-class test above.
+- (void)testSwizzleRCTConvertMethods_whenRCTCxxConvertPresent_swizzlesSpecMethods {
+  XCTAssertNil(NSClassFromString(kCxxConvertClassName),
+               @"no RCTCxxConvert may exist before this test registers its stand-in");
+  Class convertClass = [self registerClassNamed:kCxxConvertClassName
+                                  selectorNames:@[ kCxxConvertSpecSelector ]
+                                         global:YES];
+  XCTAssertNotNil(convertClass);
+  if (convertClass == Nil) {
+    return;
+  }
+
+  SEL selector = NSSelectorFromString(kCxxConvertSpecSelector);
+  IMP before = [self classMethodIMP:convertClass selector:selector];
+  [RNFBNullSentinelInterceptor swizzleRCTConvertMethods];
+  IMP after = [self classMethodIMP:convertClass selector:selector];
+  XCTAssertNotEqual(before, after);
+
+  gLastJsonSeenByOriginalIMP = nil;
+  id result = [self callConvert:convertClass
+                   selectorName:kCxxConvertSpecSelector
+                           json:[self nullSentinel]];
+  XCTAssertEqualObjects(gLastJsonSeenByOriginalIMP, [NSNull null]);
+  XCTAssertEqualObjects(result, [NSNull null]);
+}
+
+- (void)testSwizzleTurboModuleConversions_prefixWithoutSpec_leavesIMPUnchanged {
+  Class standIn = [self makeStandInConvertClass];
+  SEL notASpec = NSSelectorFromString(kNotASpecSelector);
+  SEL unrelated = NSSelectorFromString(kUnrelatedSelector);
+  IMP notASpecBefore = [self classMethodIMP:standIn selector:notASpec];
+  IMP unrelatedBefore = [self classMethodIMP:standIn selector:unrelated];
+
+  [RNFBNullSentinelInterceptor swizzleTurboModuleConversions:standIn];
+
+  XCTAssertEqual(notASpecBefore, [self classMethodIMP:standIn selector:notASpec]);
+  XCTAssertEqual(unrelatedBefore, [self classMethodIMP:standIn selector:unrelated]);
+}
+
+@end