zeus-validation-and-qa

Zeus Validation and QA

What counts as evidence in this repo, how the CI gate works internally, how to write tests that actually run, and the honest map of what is (and is not) covered by automation.

Facts verified 2026-07-06 against commit c5fd094fb (v13.1.3-alpha). See "Provenance and maintenance" for re-verification commands.

When to use / When NOT to use

Use this skill when you are:

• Running or debugging yarn verify or any of the four PR CI checks
• Writing, extending, or running Jest tests
• Deciding what manual testing / screenshots / backend coverage a change needs before PR
• Hit by the check-styles.test.ts lint failure or a jest transform error

Use a sibling skill instead when you need:

• PR/commit/review/locales rules, dependency policy, the storage-change gate → zeus-change-control
• Which of the 7 backends supports a feature, supports*() flags → zeus-backends-and-capabilities
• Recreating the dev environment, postinstall chain, native builds → zeus-build-and-env
• Running the app and connecting to test nodes (needed for manual testing) → zeus-run-and-operate
• Triage of runtime bugs (not CI failures) → zeus-debugging-playbook
• Logging/measurement tooling → zeus-diagnostics-and-tooling
• Formal proofs/analysis beyond tests (race analysis, migration proofs) → zeus-proof-and-analysis-toolkit

Glossary (skip if you know both stacks)

1) yarn verify anatomy — the entire quality gate

yarn verify (package.json) runs four checks in parallel via concurrently:

"verify": "concurrently \"yarn test\" \"yarn prettier\" \"yarn tsc\" \"yarn lint\""

These SAME four checks are the ENTIRE PR CI gate. .github/workflows/ contains test.yml, lint.yml, prettier.yml, tsc.yml (each: ubuntu-latest, Node 24.x, yarn install --frozen-lockfile, then the one script). build-android.yml and dependency-scan.yml are workflow_dispatch-only, and telegram.yml is a push/issues/release notification workflow, not a check — no mobile build, no emulator, no dependency scan runs on PRs. Green CI proves types, format, lint, and 48 unit-test suites. Nothing more.

Run the full gate before every PR. Node engines requirement is >= 22.11.0 (package.json); CI uses 24.x; there is no .nvmrc.

Checklist before opening a PR:

• yarn verify passes locally (all four)
• If you touched a utility: unit tests added/updated (the PR template asks this explicitly)
• Manual test evidence collected (section 5)

2) The check-styles.test.ts mechanism, precisely

check-styles.test.ts sits at the repo root. It is a Jest test, but it is NOT part of yarn test:

• package.json jest config: "testPathIgnorePatterns": ["check-styles.test.ts"] → excluded from the Test check.
• yarn lint re-includes it by passing an EMPTY ignore list: yarn run test check-styles.test.ts --testPathIgnorePatterns= → so a styling violation fails the Lint CI check, not Test. This surprises everyone once.

What it bans: calling themeColor() inside a static StyleSheet.create({...}) block in any .tsx file.

Why: StyleSheet.create at module scope executes ONCE, at import time. themeColor('key') reads the user's currently selected theme (Zeus ships 23 themes). A theme color baked into a static sheet freezes at whatever theme was active at first import and silently ignores theme switches — a real correctness bug, not a style nit. The test's own error message says exactly this.

How it detects: a dot-all regex — /\n[^\s][^\n]+StyleSheet\.create\(\{.*themeColor\(/s — flags any .tsx file where a non-indented (top-level) line containing StyleSheet.create({ is followed anywhere later in the file by themeColor(. Two practical consequences:

1. Keep const styles = StyleSheet.create({...}) as the LAST thing in the file (the repo-wide convention, e.g. components/WalletHeader.tsx) and keep it free of themeColor().
2. Because the .* spans newlines, a themeColor( call in ordinary component code placed BELOW the styles block will also trip the check even if the sheet itself is clean. Styles-at-bottom avoids this entirely.

How to fix a violation — move the themed color out of the static sheet:

// BANNED: frozen at import time
const styles = StyleSheet.create({
    label: { fontSize: 16, color: themeColor('text') }
});

// OK: static layout in the sheet, themed color applied at render time
const styles = StyleSheet.create({
    label: { fontSize: 16 }
});
// in render():
<Text style={[styles.label, { color: themeColor('text') }]} />
// or compute the style object inside render/a function, as components/Button.tsx does

Run just this check locally: yarn run test check-styles.test.ts --testPathIgnorePatterns=

3) Jest traps

transformIgnorePatterns whitelist. React Native ships untranspiled ESM in many packages; jest only transpiles node_modules packages explicitly whitelisted. The current list (package.json jest config):

react-native | @react-native | react-native-blob-util | react-native-randombytes |
react-native-nfc-manager | dateformat | nostr-tools | @nostr | @noble | @scure | uuid

Symptom of a missing entry: SyntaxError: Cannot use import statement outside a module (or Unexpected token 'export') pointing into node_modules/<pkg>. Fix: add the package name inside the (?!(...)) group in "transformIgnorePatterns" in package.json. (New dependencies themselves require maintainer discussion first — see zeus-change-control.)

moduleNameMapper for @noble/hashes. Five explicit mappings (_assert, pbkdf2, sha256, sha512, utils) pin @noble/hashes/* subpath imports to concrete .js files, because jest's resolver predates that package's exports-map style. If you import a new @noble/hashes subpath in tested code and jest says "Cannot find module", add a matching mapper line.

Colocated test convention. Tests live NEXT TO the code, named <File>.test.ts: utils/FeeUtils.ts + utils/FeeUtils.test.ts. No __tests__/ directories, no .spec.ts, no .test.tsx anywhere. Variants are allowed (utils/AddressUtils-testnet.test.ts, utils/UnitsUtils.alt.test.ts).

Mock before import. Test files start with jest.mock(...) calls for native modules and stores BEFORE importing the unit under test — see the top of utils/handleAnything.test.ts (mocks ../stores/Stores, react-native-notifications, AsyncStorage, ./BackendUtils, the Cashu FFI) and utils/MigrationUtils.test.ts. Copy one of these preambles when your unit transitively touches stores or native code; importing stores/Stores un-mocked pulls in the entire 30-store app graph and usually explodes on a native module.

Run a subset (verified working):

yarn test utils/Bolt11Utils.test.ts          # one file (path pattern)
yarn test utils/Bolt11Utils.test.ts -t "LRU" # one file, test-name filter
yarn jest --listTests                        # enumerate all suites jest will run

4) Coverage reality — where automation actually protects you

Counted at c5fd094fb: 48 test suites run by yarn test — utils/ 45, models/ 2 (Payment.test.ts, ClaimTransaction.test.ts), lndmobile/ 1 (channel.test.ts) — plus the lint-only check-styles.test.ts (49 .test.ts files total).

Zero tests exist for stores/, views/, components/, and backends/. That is: all MobX state logic (including the 5000+-line CashuStore), every screen, every reusable component, and all 7 node-backend implementations have NO automated safety net. Consequences you must act on:

• A green yarn verify on a store/view/backend change proves only that it compiles, lints, and didn't break utility tests. Manual testing is the real safety net there (section 5).
• CONTRIBUTING.md ("Test Coverage"): bug fixes should include a test that would have caught the bug. For store/view bugs, satisfy this via the extraction pattern in section 7.
• The maintainer-confirmed rule "no drive-by refactors in payment paths" exists largely BECAUSE of this coverage hole (see zeus-change-control).

5) Evidence standards — what a PR must prove

CI green is necessary, never sufficient. The evidence bar (CONTRIBUTING.md + PR template + maintainer rules confirmed 2026-07-06):

1. Manual testing on BOTH platforms is mandatory. CONTRIBUTING.md says "when possible"; the maintainer's actual rule (confirmed 2026-07-06, stricter than the written doc) is: no merge without hands-on iOS + Android testing by the author, regardless of CI green. See zeus-run-and-operate for how to run the app and connect nodes.
2. Fill out the PR template — never delete it (.github/PULL_REQUEST_TEMPLATE.md). It requires: change category; the four-check checklist; whether you added unit tests for touched utilities; platforms tested (with OS version and phone model/VM); and the 7-backend testing matrix: on-device LDK Node, Embedded LND; remote LND (REST), LND (Lightning Node Connect), Core Lightning (CLNRest), Nostr Wallet Connect, LndHub. Check ONLY the boxes for what you actually tested.
3. Screenshots/video for UI changes (CONTRIBUTING.md), tested on both platforms because rendering differs. First-time contributors MUST attach screenshot/video proof for features/UI or the PR is closed within 24 hours (CONTRIBUTING.md "Proof of Work").
4. Regression test with every bug fix where the logic is unit-testable (CONTRIBUTING.md).

Which backends to actually test — guidance derived from the capability matrix (authoritative flags live in zeus-backends-and-capabilities); the template asks you to report honestly, not to test all 7 for every change:

6) Golden inventory — the highest-value existing suites

Read these before writing your own; they are the house style. Line counts at c5fd094fb.

7) Testing store-like logic despite zero store tests

Do NOT try to instantiate a real MobX store in jest — none of the 30 stores is constructed in any existing test, the DI graph makes it impractical, and there is no established harness. The observed, accepted pattern is extract pure logic into utils/ and test it there:

• stores/ActivityStore.ts delegates filtering to utils/ActivityFilterUtils.ts → tested in utils/ActivityFilterUtils.test.ts (464 lines).
• stores/SettingsStore.ts and stores/CashuStore.ts delegate migrations to utils/MigrationUtils.ts → tested in utils/MigrationUtils.test.ts.

Recipe when fixing a bug in a store:

1. Isolate the buggy computation (parsing, filtering, amount math, migration transform) into a pure function in utils/<Thing>Utils.ts — inputs in, value out, no store references. Keep the store method as a thin caller. Keep the diff minimal if it's a payment path (zeus-change-control).
2. Add colocated utils/<Thing>Utils.test.ts with a case reproducing the bug (fails before the fix, passes after) — this satisfies CONTRIBUTING's "test that would have caught the bug".
3. Where the logic genuinely needs store/native context, mock at the boundary exactly as utils/MigrationUtils.test.ts mocks ../stores/Stores and utils/handleAnything.test.ts mocks ./BackendUtils — mock modules the unit imports, before importing the unit.

Writing the FIRST test harness for an actual store class would be new ground: treat it as a proposal for maintainer discussion, not something to bolt onto a bug-fix PR (see zeus-research-methodology for the evidence bar).

Provenance and maintenance

All facts verified 2026-07-06 against commit c5fd094fb (v13.1.3-alpha). Commands below were executed except where a fact is inherently CI-side (workflow YAML claims verified by reading .github/workflows/*.yml, not by dispatching CI).

Re-verify volatile facts:

Note: "no merge without hands-on iOS+Android testing" is a maintainer-stated rule (2026-07-06), stricter than CONTRIBUTING.md's written "when possible" — if CONTRIBUTING.md is later updated, prefer the doc.