Testing Nexus
Context: every Jest lane resolves obsidian to a hand-written mock — see
moduleNameMapper in jest.config.js. A green suite therefore proves the code
agrees with tests/mocks/obsidian/, not with Obsidian. Three ranking defects
shipped past that suite. Everything below exists to close the gap between what
Jest can prove and what the running plugin does.
Workflow
Pick the job and open its protocol. Work from the protocol, not from this
router — the router names procedures, it does not contain them.
| Job |
Protocol |
| Add or change a test |
protocols/write-a-test.md |
| Prove a change works in the running plugin |
protocols/live-loop.md |
| No Obsidian here (container / cloud session) |
protocols/headless-obsidian.md |
| Run a gated live-smoke lane or the eval harness |
protocols/run-gated-lanes.md |
shippedGuidanceCommands or ToolManagerCliSyntax is red |
protocols/fix-shipped-docs-drift.md |
| Merge a PR (what to run first, how to gate on CI) |
protocols/merge-a-pr.md |
| A symptom you cannot place |
references/troubleshooting.md |
Derive every list from the tree, never from a document. This skill states no
test counts, no lane inventory and no env-var table on purpose, and you MUST
NOT add one — those rot silently and a rotted list is worse than none.
references/lanes.md holds the discovery commands.
Before calling a testing change done, run both checks from the repo root and
fix anything they print:
python3 .claude/skills/nexus-testing/scripts/check_live_lane_gates.py
python3 .claude/skills/nexus-testing/scripts/check_catalog_target.py
NEVER claim a change is verified in the app on the strength of Jest alone.
If the change touches load order, rendering, hydration or anything that only
exists once the plugin is running, protocols/live-loop.md is the proof and
nothing else is.
At the end of a session that used this skill, run protocols/self-refine.md.
Map
protocols/ the procedures: write-a-test, live-loop, headless-obsidian,
run-gated-lanes, fix-shipped-docs-drift, self-refine.references/ read on demand: lanes.md (where a test goes and how to find
what exists), mock-honesty.md (the two habits that make a test able to fail),
troubleshooting.md (symptom → cause).scripts/ the mechanical checks named in step 3. Run them; do not
reimplement them.refinement-log.md what past sessions changed here and why.
Siblings — do not duplicate them here
nexus-eval-harness — configuring, extending and debugging the eval harness.
This skill covers only running it and the two knobs that surprise people.nexus-model-eval — grading specific models.nexus-tool-schemas — regenerating the tool catalog (no running vault needed).nexus-agents — the two-tool contract and the useTools payload shape a test
has to build.nexus-mobile-compat — the mobile failure class the in-app loop cannot see.nexus-storage — resetting persisted state when a plugin reload is not enough.
Status of the in-app loop
Exercised 2026-08-14 against Obsidian 1.13.7 in a headless Linux container
and 2026-08-21 against Obsidian 1.12.7 on macOS. Setup, vault-targeted
plugin:reload, dev:errors, dev:console, dev:screenshot, dev:debug, and
synchronous eval are confirmed working. The first run found a startup-ordering
bug that every Jest lane was blind to; the macOS run confirmed explicit
vault=<name> targeting and clean repeated reloads.
1---2name: nexus-testing3description: Verify a Nexus change — pick a Jest lane, write a test that can actually fail, run the in-app Obsidian CLI loop, drive the eval harness, or fix a shipped-docs drift failure. Use when adding or changing tests, when a mock might be deciding the outcome, when a change has to be proven in the running plugin, or when the guidance gate fails.4---56# Testing Nexus78Context: every Jest lane resolves `obsidian` to a hand-written mock — see9`moduleNameMapper` in jest.config.js. A green suite therefore proves the code10agrees with `tests/mocks/obsidian/`, not with Obsidian. Three ranking defects11shipped past that suite. Everything below exists to close the gap between what12Jest can prove and what the running plugin does.1314## Workflow15161. Pick the job and open its protocol. Work from the protocol, not from this17 router — the router names procedures, it does not contain them.1819 | Job | Protocol |20 |---|---|21 | Add or change a test | `protocols/write-a-test.md` |22 | Prove a change works in the running plugin | `protocols/live-loop.md` |23 | No Obsidian here (container / cloud session) | `protocols/headless-obsidian.md` |24 | Run a gated live-smoke lane or the eval harness | `protocols/run-gated-lanes.md` |25 | `shippedGuidanceCommands` or `ToolManagerCliSyntax` is red | `protocols/fix-shipped-docs-drift.md` |26 | Merge a PR (what to run first, how to gate on CI) | `protocols/merge-a-pr.md` |27 | A symptom you cannot place | `references/troubleshooting.md` |28292. Derive every list from the tree, never from a document. This skill states no30 test counts, no lane inventory and no env-var table on purpose, and you MUST31 NOT add one — those rot silently and a rotted list is worse than none.32 `references/lanes.md` holds the discovery commands.33343. Before calling a testing change done, run both checks from the repo root and35 fix anything they print:3637 ```bash38 python3 .claude/skills/nexus-testing/scripts/check_live_lane_gates.py39 python3 .claude/skills/nexus-testing/scripts/check_catalog_target.py40 ```41424. NEVER claim a change is verified in the app on the strength of Jest alone.43 If the change touches load order, rendering, hydration or anything that only44 exists once the plugin is running, `protocols/live-loop.md` is the proof and45 nothing else is.46475. At the end of a session that used this skill, run `protocols/self-refine.md`.4849## Map5051- `protocols/` the procedures: write-a-test, live-loop, headless-obsidian,52 run-gated-lanes, fix-shipped-docs-drift, self-refine.53- `references/` read on demand: `lanes.md` (where a test goes and how to find54 what exists), `mock-honesty.md` (the two habits that make a test able to fail),55 `troubleshooting.md` (symptom → cause).56- `scripts/` the mechanical checks named in step 3. Run them; do not57 reimplement them.58- `refinement-log.md` what past sessions changed here and why.5960## Siblings — do not duplicate them here6162- `nexus-eval-harness` — configuring, extending and debugging the eval harness.63 This skill covers only running it and the two knobs that surprise people.64- `nexus-model-eval` — grading specific models.65- `nexus-tool-schemas` — regenerating the tool catalog (no running vault needed).66- `nexus-agents` — the two-tool contract and the `useTools` payload shape a test67 has to build.68- `nexus-mobile-compat` — the mobile failure class the in-app loop cannot see.69- `nexus-storage` — resetting persisted state when a plugin reload is not enough.7071## Status of the in-app loop7273**Exercised 2026-08-14** against Obsidian 1.13.7 in a headless Linux container74and **2026-08-21** against Obsidian 1.12.7 on macOS. Setup, vault-targeted75`plugin:reload`, `dev:errors`, `dev:console`, `dev:screenshot`, `dev:debug`, and76synchronous `eval` are confirmed working. The first run found a startup-ordering77bug that every Jest lane was blind to; the macOS run confirmed explicit78`vault=<name>` targeting and clean repeated reloads.
ProfSynapse