Skip to content

validation-checklist.md

Latest commit

 

History

History
194 lines (137 loc) · 18.2 KB

validation-checklist.md

File metadata and controls

194 lines (137 loc) · 18.2 KB
Raw
type Reference
title Validation checklist
description Canonical command sequence for validating RNFB TS/JS changes, e2e, and handoff.
tags
testing
validation
jest
compare-types
lint
coverage
timestamp 2026-06-24 00:00:00 UTC

Validation checklist

Validation commands for development/handoff. Other docs/skills link here; do not restate.

Coverage acceptance: expectations + completion signal on every touched file.

When to run what

Work types and tiers: change authoring workflow. Term ids: iteration vocabulary.

Work type Scope Shortcuts
gap-analysis compare:types, config read, SDK declarations n/a
baseline-capture Full loaded spec(s) + e2e on every required platform area-focused tier; area narrowing required; no .only, no :test-cover-reuse; no platform shortcuts
implementation Unit-focused Jest + e2e on every required platform when native bridge or macOS TS/runtime path changed — Jest-only does not close implementation_gate; lib/** edits need yarn lerna:prepare + Metro restart, not platform :build for JS alone (running e2e § Rules #3) unit-focused tier; harness overrides + RNFBDebug before :test-cover; optional .only / sub-suite for diagnosis; platform coverage gate — no platform shortcuts
independent-review Full checklist; e2e on every required platform (macOS / iOS / Android per harness) area-focused tier; platform coverage gate — no shortcuts; frozen tree; never commit overrides, sub-suite .only, or temporary tests/app.js edits (fail-fast §)
pre-merge-validation Full unfocused suite full tier — running-e2e § merge; entire PR branch, once

Prepare and compile

Repo root. Agents: agent command policy — only these invocations; never yarn workspace … prepare or package-scoped yarn run build for diagnostics.

yarn                                  # install + postinstallDev (includes lerna:prepare)
yarn lerna:prepare                    # after packages/*/lib/** edits — transpiles lib → dist/module via each package prepare target
yarn tsc:compile
yarn tsc:compile:consumer
yarn attw:check                    # scoped attw + Expo plugin smoke — [Types-AD-1..4](architecture-decisions.md)

yarn lerna:prepare runs each package prepare script (build then compile/bob). That is the canonical lib/**→dist/module/** path. Do not use cd packages/<pkg> && yarn compile as a substitute — compile is a step inside prepare, not a standalone agent entrypoint.

Blocking: yarn and yarn lerna:prepare must exit 0 before any other command (Jest, tsc, e2e, Metro, builds) — never parallelize. Agent command policy § prepare must finish first; e2e pre-flight: running e2e § prepare completion gate. Before native :build: install / patch / fmt gate (fmt ≥ 12.1.0).

API reference and type parity

yarn reference:api                    # after consumer tsc
yarn compare:types                    # remove stale config entries when fixed

Configs: .github/scripts/compare-types/configs/. Package workflows define ordering (e.g. pipelines).

When typedoc.json or packages/*/typedoc.json changes anything that can alter reference URL structure, also run the legacy redirect audit (verify every docs.json → redirects target; add mappings for newly orphaned legacy /reference/... paths).

For any package registered in compare:types, type parity is a review-gate requirement, not a best-effort signal. Before closing independent-review, the touched package must have:

  • no undocumented differences,
  • no stale config entries,
  • and any intentional RN-only exports documented in that package config to the compare-types justification bar.

If yarn compare:types fails because of unrelated packages, keep the touched package's result in the handoff and add/fix a work-queue item for the unrelated drift. Do not close a review gate for a registered package when its own compare-types output is failing.

Jest

yarn tests:jest                       # full suite at handoff

Focused example:

yarn tests:jest --watchman=false packages/firestore/__tests__/pipelines.test.ts

Optional: yarn tests:jest-coverage.

Android JVM unit tests

When packages/*/android/** Java bridge/state-machine logic changed (or added under src/test/java):

yarn tests:android:unit               # Robolectric + Mockito — [AndroidTest-AD-1](android-architecture-decisions.md#androidtest-ad-1--robolectric--mockito-for-android-jvm-unit-tests--accepted)

Produces Jacoco *.exec that counts toward native touched-line coverage when merged. After Android e2e:

yarn tests:android:post-e2e-coverage  # pull .ec → jacocoTestReport (unit + e2e merge)
# optional explicit merge:
yarn tests:android:test:jacoco-report

Merged Codecov path: jacocoTestReport.xml — coverage design. JVM unit does not replace platform coverage gate e2e.

Lint and formatting

Blocking before implementation handoff and on the frozen tree for independent-review. Run from repo root after prepare/compile when TS/JS changed.

yarn lint:js                          # eslint packages/* — must exit 0
yarn lint:js --fix                    # auto-fix; re-run yarn lint:js until clean
yarn lint:deps                        # dependency-cruiser no-circular on packages/*/lib/** — blocking when packages/*/lib/** in diff (see [prepare-and-cache § dependency-cycle linting](../monorepo-tooling/prepare-and-cache.md#dependency-cycle-linting))
yarn lint:android                     # google-java-format on packages/*/android/src — ONLY entrypoint ([agent command policy](agent-command-policy.md)); never invent yarn google-java-format / npx google-java-format
yarn format:js                        # inspect diff after; prefer lint:js --fix first

Docs (when docs/** or OKF markdown changed):

yarn lint:markdown
yarn lint:spellcheck

CI Lint job equivalent (required before review / publication when the diff touches JS, Java, or Objective-C/C++ sources):

yarn lint                              # lint:js + lint:deps + lint:android + lint:ios:check — matches .github/workflows/linting.yml

When packages/*/lib/** is in the diff, yarn lint:deps is a blocking gate (runs inside yarn lint, which matches the CI Lint job). Config and rule detail: prepare-and-cache § dependency-cycle linting.

yarn lint:android runs google-java-format and fails if it would change committed files — commit formatter output. Agents: only yarn lint:android (agent command policy) — do not invent yarn google-java-format or bare/npx google-java-format. lint:android can flake; rerun once/twice if failure is not clearly in diff.

CI docs job equivalent (required before review / publication when docs/** changed):

yarn lint:markdown                     # matches .github/workflows/docs.yml
yarn lint:spellcheck

E2e with coverage

Pre-flight (host-clear probes + services + harness tier) before every run — agent command policy and e2e agent rule: use only yarn tests:* commands from running e2e. Match harness to work type — unit-focused/area-focused never use full app load (running e2e § harness).

Commands: Running e2e tests. Post-process: Coverage design (iOS tests:ios:test:process-coverage, Android tests:android:unit + tests:android:post-e2e-coverage → merged jacocoTestReport).

Some suites hit cloud APIs, e.g. Firestore Pipelines → pipelines-e2e Enterprise DB (pipelines.md).

OKF bundle review

Before handoff, follow OKF policy:

  1. Update relevant okf-bundle/packages/<pkg>/ docs with durable learnings.
  2. Check okf-bundle/testing/ for conflicts with verified behavior; fix drift.
  3. Run independent scan for canonical ownership, DRY refs, link hygiene, durability.

Goal: each iteration improves OKF and removes conflicting guidance.

Validation evidence package (blocking)

Before closing implementation_gate, review_gate, commit_gate, or publishing (git push / PR update), record evidence per change authoring § validation evidence. Minimum template:

| Step                      | Command                       | Exit | Evidence                                                                                                                          |
| ------------------------- | ----------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------- |
| prepare                   | yarn lerna:prepare            | 0    | —                                                                                                                                 |
| jest                      | yarn tests:jest <paths>       | 0    | N/N tests                                                                                                                         |
| android JVM unit          | yarn tests:android:unit       | 0    | when packages/*/android/** Java changed — [AndroidTest-AD-1](android-architecture-decisions.md)                                  |
| e2e macOS                 | yarn tests:macos:test-cover   | 0    | X passing — /tmp/...log                                                                                                           |
| e2e iOS                   | yarn tests:ios:test-cover     | 0    | Y passing — /tmp/...log                                                                                                           |
| e2e Android               | yarn tests:android:test-cover | 0    | Z passing — /tmp/...log                                                                                                           |
| android merged Jacoco     | yarn tests:android:post-e2e-coverage | 0 | jacocoTestReport.xml (unit + e2e) — [coverage design](coverage-design.md)                                                         |
| compare:types             | yarn compare:types            | 0    | <pkg> 0/0/0                                                                                                                       |
| lint (CI)                 | yarn lint                     | 0    | —                                                                                                                                 |
| lint:deps (lib diff)      | yarn lint:deps                | 0    | when packages/\*/lib/\*\* in diff — [dependency-cycle linting](../monorepo-tooling/prepare-and-cache.md#dependency-cycle-linting) |
| lint:markdown (CI docs)   | yarn lint:markdown            | 0    | when docs/\*\* in diff                                                                                                            |
| lint:spellcheck (CI docs) | yarn lint:spellcheck          | 0    | when docs/\*\* in diff                                                                                                            |
| coverage                  | post-process + region table   | —    | see coverage-design § evidence package                                                                                            |

History rewrite invalidates prior rows — re-run and replace the table after amend/rebase.

Handoff checklist

  • yarn lerna:prepare (after any packages/*/lib/** edits)
  • yarn tsc:compile, yarn tsc:compile:consumer
  • yarn attw:check when package.json exports, plugin/build, or published types changed (Types-AD)
  • yarn reference:api
  • Redirect audit when TypeDoc config changed (documentation site maintenance § redirect audit)
  • yarn tests:jest
  • yarn tests:android:unit when packages/*/android/** Java / src/test/java changed (AndroidTest-AD-1)
  • TurboModule wrapper contract (NewArch-AD-17.1) when packages/app/lib/internal/registry/nativeModule.ts, nativeModuleAndroidIos.ts, or TurboModule wrapper behavior changed: yarn tests:jest -- packages/app/__tests__/nativeModuleContract.test.ts
  • yarn compare:types (stale config entries removed)
  • yarn lint (CI Lint job) including yarn lint:android when Java changed (agent command policy); yarn lint:deps when packages/*/lib/** in diff (dependency-cycle linting); yarn lint:markdown + yarn lint:spellcheck when docs/** changed
  • E2e green on every required platform for the changed module (platform coverage gate; harness narrowing gate; no .only; committed RNFBDebug remains false)
  • Android post-e2e merged Jacoco when Android native touched: yarn tests:android:post-e2e-coverage → jacocoTestReport.xml (coverage design)
  • Validation evidence package recorded (exit codes, e2e counts, log paths)
  • Coverage evidence package when lib/native bridge touched — gaps investigated to fix, delete, or acceptable-exception bar
  • OKF bundle reviewed/updated per § above

Package workflows may add items (e.g. pipeline before/after snapshots — pipeline workflow).