| type | Reference | ||||||
|---|---|---|---|---|---|---|---|
| title | iOS unit testing decisions (ADR) | ||||||
| description | Canonical owner of durable decisions for in-package iOS XCTest (macOS/host first, Simulator only if UIKit required). | ||||||
| tags |
|
||||||
| timestamp | 2026-10-01 00:00:00 UTC |
Canonical owner of durable decisions for in-package iOS XCTest under packages/*/ios/*UnitTests/*.xcodeproj. Commands: agent command policy, validation checklist. Coverage contract: coverage design. CI shape: iOS CI workflows.
Host-first preference is the iOS counterpart of AndroidTest-AD-1 (JUnit over Robolectric unless Android APIs are required). Do not duplicate that Android table here.
Policy: OKF documentation policy. Do not duplicate these decisions in work queues.
Use the IosTest-AD-<n> prefix when citing these decisions in code or docs.
| Status | Meaning |
|---|---|
| Accepted | Decided; CI and local yarn scripts enforce this. |
| Proposed | Planned; not yet enforced. |
Prefer a tiny in-package xcodeproj that compiles the real production sources and runs XCTest on a macOS destination. Most projects compile Foundation-only sources (registries, handle maps). When a production file must import React, Firebase, or UIKit, the project still stays on macOS: it compiles that file unchanged against hand-written stub headers and test doubles kept inside the unit project directory (see stub-header projects). Use an iOS Simulator destination only when the class under test needs UIKit (or other iOS-only frameworks) that cannot be replaced by a very small stub or double.
| Aspect | Decision |
|---|---|
| Location | One xcodeproj per package, not per class: packages/<pkg>/ios/RNFB<Package>UnitTests/ (examples: RNFBAppUnitTests, RNFBFunctionsUnitTests) next to production packages/*/ios/** sources. Discovery glob stays packages/*/ios/*UnitTests/*.xcodeproj. Test sources keep the class name as the final path segment (e.g. RNFBHandleMapTests.m). Not CocoaPods test_spec. Not the Detox host (tests/ios/testingTests). |
| Default destination | platform=macOS for Foundation logic |
| Simulator | Only when UIKit / iOS-only APIs are required |
| Entry command | yarn tests:ios:unit → tests/scripts/run-ios-unit-tests.js (discovers *UnitTests.xcodeproj) |
| Coverage artifact | coverage/ios-unit/lcov.info, merged into coverage/ios-native/lcov.info so XCTest hits count toward the 100% touched-line bar — coverage design |
| CI | tests_e2e_ios.yml after yarn, analogous to yarn tests:android:unit on the Android e2e workflow |
Why: Detox/Jet e2e cannot reliably drive lock-only pointer maps, unique-put collisions, takeAll invalidate paths, or native paths gated behind a flag the test app leaves off. Host XCTest proves those contracts without a simulator. CocoaPods test_spec would pull the real React/Firebase pods into the unit graph; the Detox test app is an integration host, not a package unit harness.
Do not add a production *Bridge type solely so those tests can compile TurboModule collision/invalidate branches. Registry/HandleMap-style projects stay Foundation-only. TurboModule/Helper lines that only call Registry/HandleMap may stay uncovered — coverage design (user-accepted exception).
A package whose logic lives in TurboModule or delegate files (not a separable Registry) may compile those production .m/.mm files directly instead:
| Aspect | Decision |
|---|---|
| Production sources | Referenced from ../<Package>/ (for example RNFBMessagingModule.mm); never copied or edited for the test |
| Stubs | Stubs/ under the unit project: minimal headers for React, Firebase, GoogleUtilities, RNFBApp, UIKit, and the codegen'd TurboModule header; added to HEADER_SEARCH_PATHS ahead of the package sources |
| Generated-header stub | Name the stub file distinctly (for example RNFBMessagingTurboModulesStub.h, not RNFBMessagingTurboModules.h) and expose it under the name production imports through a clang VFS overlay (Stubs/rnfb-messaging-vfs-overlay.yaml, passed as -ivfsoverlay plus -I/<virtual-dir> in the project's OTHER_CFLAGS). Never copy a stub into any directory under a package's ios/ tree under the generated header's name, including build/ output |
| Doubles | One test-doubles .mm implements the stubbed classes (recording emitter, fake SDK object, UIKit shims) with *ForTesting hooks; no real SDK or React framework is linked |
| Scope | Stubs declare only the symbols the compiled production files reference; keep them as small as possible |
| Coverage | Same coverage/ios-unit/lcov.info path as every other unit project; real production lines get hits |
Why the distinct name: packages/app/__tests__/specNativeParityHelper.ts (findSingleMatch) walks packages/<pkg>/ios for /^RNFB.*TurboModules\.h$/ and throws on more than one match. A second physical file with a generated header's name anywhere under ios/ (gitignored build/ included) makes turboModuleSpecNativeParity.test.ts run 0 tests and fails the full yarn tests:jest.
Example: RNFBMessagingUnitTests, see messaging index.
Not a substitute for area e2e: In-package XCTest does not replace platform coverage gate delivery/integration e2e on platforms where the module loads.
Podspec: Exclude ios/*UnitTests/**/* from package source_files so XCTest sources (and nested trees such as HostStubs/) are not compiled into the production pod. CocoaPods FileList uses FNM_PATHNAME; the shallower ios/*UnitTests/** glob does not match nested paths under the unit-test directory.
Pack / attw: nested XCTest build/ trees — Types-AD-5.