test: create a clean "native coverage upload" failed signal in CI

native coverage was still failing to upload correctly, and it was a silent
false positive

this doesn't enforce a specific level of native coverage but enforces that it
is correctly collected and uploaded - that the plumbing + system is working

Author: mikehardy

.github/workflows/tests_e2e_android.yml

@@ -273,9 +273,20 @@ jobs:
             yarn tests:android:post-e2e-coverage
 
       # https://github.com/codecov/codecov-action/releases
-      - uses: codecov/codecov-action@e53489f4d376d79066609109e7a95a29eb3740b1 # v7.0.0
+      - name: Upload Codecov e2e TS (Android)
+        uses: codecov/codecov-action@e53489f4d376d79066609109e7a95a29eb3740b1 # v7.0.0
         continue-on-error: true
         with:
+          files: coverage/lcov.info
+          flags: e2e-ts-android
+          verbose: true
+
+      - name: Upload Codecov Android native
+        uses: codecov/codecov-action@e53489f4d376d79066609109e7a95a29eb3740b1 # v7.0.0
+        continue-on-error: true
+        with:
+          files: tests/android/app/build/reports/jacoco/jacocoAndroidTestReport/jacocoAndroidTestReport.xml
+          flags: android-native
           verbose: true
 
       - name: Upload Emulator Log

.github/workflows/tests_e2e_ios.yml

@@ -420,10 +420,22 @@ jobs:
           path: .github/workflows/scripts/*.log
 
       # https://github.com/codecov/codecov-action/releases
-      - uses: codecov/codecov-action@e53489f4d376d79066609109e7a95a29eb3740b1 # v7.0.0
+      - name: Upload Codecov e2e TS (iOS)
+        uses: codecov/codecov-action@e53489f4d376d79066609109e7a95a29eb3740b1 # v7.0.0
         if: contains(matrix.buildmode, 'debug')
         continue-on-error: true
         with:
+          files: coverage/lcov.info
+          flags: e2e-ts-ios
+          verbose: true
+
+      - name: Upload Codecov iOS native
+        uses: codecov/codecov-action@e53489f4d376d79066609109e7a95a29eb3740b1 # v7.0.0
+        if: contains(matrix.buildmode, 'debug')
+        continue-on-error: true
+        with:
+          files: coverage/ios-native/lcov.info
+          flags: ios-native
           verbose: true
 
       - name: Yarn Cache Save

.github/workflows/tests_e2e_other.yml

@@ -281,6 +281,8 @@ jobs:
       - uses: codecov/codecov-action@e53489f4d376d79066609109e7a95a29eb3740b1 # v7.0.0
         continue-on-error: true
         with:
+          files: coverage/lcov.info
+          flags: e2e-ts-macos
           verbose: true
 
       - name: Stop Screen Recording and System Logging

.github/workflows/tests_jest.yml

@@ -65,6 +65,8 @@ jobs:
       # https://github.com/codecov/codecov-action/releases
       - uses: codecov/codecov-action@e53489f4d376d79066609109e7a95a29eb3740b1 # v7.0.0
         with:
+          files: coverage/lcov.info
+          flags: jest
           verbose: true
       # https://github.com/actions/cache/releases
       - uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5

codecov.yml

@@ -14,7 +14,27 @@ coverage:
     changes: no
 
 comment:
-  layout: 'header, diff'
+  layout: 'header, diff, flags'
   behavior: default
   require_changes: false
   after_n_builds: 3
+
+# Native upload gates. Flag names must match codecov-action `flags:` in CI workflows
+# (see okf-bundle/testing/coverage-design.md).
+flag_management:
+  individual_flags:
+    - name: ios-native
+      carryforward: false
+      statuses:
+        - type: project
+          target: 1%
+          threshold: 0%
+          informational: false
+
+    - name: android-native
+      carryforward: false
+      statuses:
+        - type: project
+          target: 1%
+          threshold: 0%
+          informational: false

okf-bundle/ci-workflows/android.md

@@ -4,7 +4,7 @@
 
 1. `yarn tests:android:test-cover --headless` — Detox + Jet (pass/fail gate)
 2. `yarn tests:android:post-e2e-coverage` — poll/pull `coverage.ec`, Jacoco report (best-effort, never fails the job)
-3. Codecov upload — `continue-on-error: true`
+3. **Codecov upload** — two flagged uploads (`e2e-ts-android`, `android-native`); `continue-on-error: true` on the action steps. **`codecov/project/android-native`** fails if the native flag upload is missing (see [coverage design](../testing/coverage-design.md#native-upload-gates)).
 
 Native Android coverage is **not** pulled inside `tests/e2e/firebase.test.js`. The Jet `after` hook in `tests/app.js` calls `RNFBTestingCoverage.flush()` in the **app process** to write `coverage.ec` before Detox SIGINTs instrumentation. Post-e2e pull runs after Detox exits.
 
@@ -50,3 +50,4 @@ Full inventory: [detox-patches.md](detox-patches.md).
 | Empty Jacoco XML (~235 bytes) | No `.ec` pulled — check post-e2e logs |
 | `adb reverse --remove` in Detox logs | Expected on 1006; should be warn-only after Detox patch |
 | Detox red, tests green in log | Pre-patch: teardown adb error; re-run or check patch applied |
+| `codecov/project/android-native` fail | Jacoco XML not uploaded — check post-e2e logs and Codecov Uploads tab for `android-native` flag |

okf-bundle/ci-workflows/index.md

@@ -14,4 +14,4 @@ Knowledge for GitHub Actions workflows in this repository: how jobs are structur
 
 ## Related
 
-* [Testing / coverage design](../testing/coverage-design.md) — e2e coverage collection that runs inside the iOS workflow
+* [Testing / coverage design](../testing/coverage-design.md) — e2e coverage collection, Codecov flags, and upload gates

okf-bundle/ci-workflows/ios.md

@@ -85,6 +85,10 @@ A long gap with only `com.apple.datamigrator` activity and no `com.invertase.tes
 
 Device type is defined in `tests/.detoxrc.js` (`devices.simulator.device.type`). The boot script and Detox both use this name. CI does not hard-code a UDID.
 
+### Codecov (debug matrix only)
+
+After Detox, the debug leg runs `yarn tests:ios:test:process-coverage` then two flagged Codecov uploads (`e2e-ts-ios`, `ios-native`). **`codecov/project/ios-native`** blocks if the native flag upload is missing. Release legs skip coverage. Details: [coverage design](../testing/coverage-design.md#codecov-uploads-ci).
+
 ### E2E test app orchestration (Detox + Jet)
 
 After pre-boot succeeds, failures often move **inside** the test app process (`com.invertase.testing`, binary `testing`). Simulator boot and app install are fine; Detox `launchApp` stalls while the app stays alive. Several overlapping issues show up in CI logs.
@@ -205,7 +209,8 @@ rg 'testing\[' simulator.log | rg -i 'FIRApp|RNFB|RCTBridge|configure'
 | Pattern | Meaning |
 |---------|---------|
 | `ready action too early` in Detox step only | Early-ready race (patch should fix; check patch applied in `yarn install`) |
-| `ECOMPROMISED` / `Unable to update lock within the stale threshold` | Device registry lock heartbeat missed — see [detox-patches.md](detox-patches.md); check `ExclusiveLockfile.js` patch |
+| `ECOMPROMISED` / `Unable to update lock within the stale threshold` | Device registry lock heartbeat missed — see [detox-patches.md](detox-patches.md) |
+| `codecov/project/ios-native` fail | Native lcov not uploaded — check process-coverage step and Codecov Uploads tab for `ios-native` flag |
 | `waitForActive` without `waitForActiveDone` | Scene/active hang (issue 4) **or** Metro/JS load failure (issue 5) — check `[rnfb-lifecycle]` probes |
 | `probe+30s` / `probe+60s` with `UIApplication.state=inactive` or scene `unattached` | App never became foreground-active (issue 4); compare with SpringBoard `foreground-interactive` lines |
 | `probe+30s` / `probe+60s` with `active` / `foregroundActive` but no `waitForActiveDone` | Metro/JS bundle failure despite active UIKit (issue 5); check `RCTJavaScriptDidFailToLoad` and `packager-status-fetch` |

okf-bundle/testing/coverage-design.md

@@ -161,22 +161,48 @@ The Podfile `post_install` coverage flags are temporary. When native dependencie
 
 # Codecov uploads (CI)
 
-CI uses [codecov-action](https://github.com/codecov/codecov-action) v7 with `verbose: true`. It auto-discovers coverage files under the repo, including:
+CI uses [codecov-action](https://github.com/codecov/codecov-action) v7 with explicit `files` and `flags` per upload (no auto-discovery for gated artifacts). Workflow steps use `continue-on-error: true` so a Codecov API hiccup does not fail the test job; **blocking gates** are the Codecov GitHub status checks configured in `codecov.yml`.
 
-| Workflow | Artifacts |
-|----------|-----------|
-| `tests_jest.yml` | `coverage/lcov.info`, `coverage-final.json`, `clover.xml` |
-| `tests_e2e_android.yml` | `coverage/lcov.info` + Jacoco XML |
-| `tests_e2e_other.yml` | `coverage/lcov.info` (macOS TS) |
-| `tests_e2e_ios.yml` (debug) | `coverage/lcov.info` + `coverage/ios-native/lcov.info` |
+## Flag inventory
 
-The iOS workflow runs `yarn tests:ios:test:process-coverage` after Detox (`if: always()`, `continue-on-error: true` for now). The process step exits 1 when profraw is missing.
+Flag names are defined in **`codecov.yml`** (`flag_management`) and must match **`flags:`** in the workflow step. Do not rename in one place without the other.
+
+| Flag | Workflow | File uploaded | Blocks PR? |
+|------|----------|---------------|------------|
+| `jest` | `tests_jest.yml` | `coverage/lcov.info` | No |
+| `e2e-ts-ios` | `tests_e2e_ios.yml` (debug only) | `coverage/lcov.info` | No |
+| `ios-native` | `tests_e2e_ios.yml` (debug only) | `coverage/ios-native/lcov.info` | **Yes** — `codecov/project/ios-native` |
+| `e2e-ts-android` | `tests_e2e_android.yml` | `coverage/lcov.info` | No |
+| `android-native` | `tests_e2e_android.yml` | `tests/android/app/build/reports/jacoco/jacocoAndroidTestReport/jacocoAndroidTestReport.xml` | **Yes** — `codecov/project/android-native` |
+| `e2e-ts-macos` | `tests_e2e_other.yml` | `coverage/lcov.info` | No |
+
+iOS **release** matrix legs do not upload coverage. macOS e2e has TS coverage only (no native gate).
+
+## Native upload gates
+
+Blocking flags use `carryforward: false` and `target: 1%` in `codecov.yml`:
+
+- **Upload present** with any reasonable native coverage → flag status **passes** (well above 1%).
+- **Upload missing** (file not produced, step skipped, or upload failed) → flag has **0%** → status **fails**.
+
+This gates **upload presence**, not native coverage percentage regressions. Overall `codecov/project` remains `informational: true`.
+
+PR comments include a **flags** table (`comment.layout: …, flags`).
+
+## Per-workflow artifacts
+
+| Workflow | Steps before Codecov |
+|----------|---------------------|
+| `tests_jest.yml` | `yarn tests:jest-coverage` |
+| `tests_e2e_ios.yml` (debug) | Detox → `yarn tests:ios:test:process-coverage` (`continue-on-error: true` on process step for now) |
+| `tests_e2e_android.yml` | Detox → `yarn tests:android:post-e2e-coverage` (soft-fail poll/pull in script) |
+| `tests_e2e_other.yml` | macOS Jet e2e |
 
 ## File naming
 
-The repo standard for JavaScript lcov is **`coverage/lcov.info`**. iOS native lcov is **`coverage/ios-native/lcov.info`** — the basename `lcov.info` is required for codecov-action auto-discovery (files like `ios-native.lcov.info` are not matched). Android native coverage is **Jacoco XML**, not lcov; codecov discovers `jacoco*.xml` once the report is generated.
+JavaScript lcov: **`coverage/lcov.info`**. iOS native lcov: **`coverage/ios-native/lcov.info`** (basename `lcov.info` required). Android native: **Jacoco XML** at the path in the table above after `jacocoAndroidTestReport`.
 
-Check the Codecov commit **Uploads** tab for **Processed** vs **Unusable** per upload — that is the authoritative signal, not small project percentage deltas.
+Check the Codecov commit **Uploads** tab: each flag should appear as **Processed**. **Unusable** means wrong format or paths — fix before relying on the gate.
 
 # Local iteration
 
@@ -231,8 +257,9 @@ These must all be true for native coverage to work. If any break, the e2e test s
 | iOS link: `swiftCompatibility56` undefined | Profile link flags applied to all Pods | Restrict `OTHER_LDFLAGS` profile flags to app target; RNFB pods compile-only |
 | No `[jet-coverage] WS received` lines | Patches not applied | `yarn install` from repo root; check `.yarn/patches/` |
 | NYC summary missing / empty `lcov.info` | Jet not run from `tests/` cwd | Detox spawns `yarn jet` inside `tests/`; macOS uses `cd tests && npx jet` |
-| Codecov missing iOS native files | Output not named `lcov.info` | Use `coverage/ios-native/lcov.info` (not `coverage/ios-native.lcov.info`) |
+| Codecov missing iOS native files | Output not named `lcov.info` or wrong path | Use `coverage/ios-native/lcov.info`; confirm `ios-native` flag upload in iOS debug workflow |
 | Codecov upload **Unusable** | Wrong `SF:` paths | Confirm path rewrite in `process-ios-native-coverage.js`; check Uploads tab message |
+| `codecov/project/ios-native` or `android-native` **fail** | Native flag upload missing (`carryforward: false` → 0%) | Check Uploads tab for that flag; iOS: process-coverage step + `coverage/ios-native/lcov.info`; Android: post-e2e Jacoco XML path |
 
 # Future cleanups (non-blocking)
 

okf-bundle/testing/index.md

@@ -1,3 +1,3 @@
 # Testing
 
-* [Coverage design](coverage-design.md) - how unit and e2e coverage is collected, transformed, and uploaded
+* [Coverage design](coverage-design.md) — unit and e2e coverage collection, Codecov flags, and native upload gates