octopus-workflow/core/rules/testing.md

Core 中立版（Increment 2 改写）。术语对照见 core/adapters/TERMINOLOGY.md；本组织实例表述见 dogfood 对应文件。

Testing

• Avoid mocks as much as possible
• Test actual implementation, do not duplicate logic into tests
• Tests cannot run from repo root (guard: do-not-run-tests-from-root); run from package dirs.
• Local pre-check: run <test-cmd:changed> from the owning package after editing source. It selects only tests affected by your uncommitted + branch changes (path-mapping ∪ CodeGraph direct dependents) and runs them in a single process — seconds, machine stays responsive. Use --print to see the selection without running, --all to scan beyond the home package.
• Before a delivery push: <test-cmd:changed> green + <typecheck-cmd> clean — same selector as CI's PR side (local parity, [org-internal #4425]). The full suite (<test-cmd:parallel>) stays with nightly / run-full-tests / manual pre-merge runs. 实例命令绑定见 core/adapters/TERMINOLOGY.md。
• Never use the bare single-process test runner for the full suite; <test-cmd:parallel> shards it and process-isolates known-corrupting files. Parallelism is controlled by TEST_SHARDS (default 3; raise it on beefy CI runners, e.g. TEST_SHARDS=7).

Pre-existing test failures must be filed, not silently logged

When the full suite surfaces a failure that is NOT caused by the current change (it reproduces on the base branch / last-green commit too), it is a pre-existing / baseline failure. Do NOT silently drop it as "someone else's problem" and do NOT bury it in a report body.

• Classify it: run the failing test on the base commit (see verify Phase 2.6). Fails there too → pre-existing (BF); passes there → regression you must fix.
• De-duplicate BEFORE filing (retro [org-internal #2696]): search existing baseline-failure tickets — open AND closed — by test/file name to surface candidates, then match by failure signature (error signature + affected surface — one root-cause family may span several tests; see the ticket-lifecycle rule §"BF / FT family umbrellas"). On a signature hit, attach run evidence to the family umbrella; do NOT create a new ticket.
• File it: the Verifier registers every un-tracked pre-existing failure as a ticket-backend issue labeled baseline-failure with a BF-NNN id (verify Phase 5.55). The number is repo-wide sequential: highest existing NNN across ALL baseline-failure tickets (open AND closed) + 1 — duplicate ids forbidden, including against closed tickets.
• A pre-existing failure does not block the iteration that discovered it, but the iteration is NOT Done until it is filed — an un-filed baseline failure is a process gap.

Flaky tests must be filed, not silently tolerated

When a test passes and fails intermittently across runs (non-deterministic), it is a flaky test. Do NOT silently re-run until it passes and move on.

• Detect: re-run the suite (or use the project's flaky detector). Record every test that shows intermittent behavior — name, failure rate, and run count.
• De-duplicate BEFORE filing (retro [org-internal #2696]): same signature-based procedure as baseline failures above, against existing flaky-test tickets.
• File it: the Verifier registers every un-tracked flaky test as a ticket-backend issue labeled flaky-test with an FT-NNN id (verify Phase 5.56). FT-NNN allocation follows the same repo-wide sequential rule as BF-NNN, across ALL flaky-test tickets (open AND closed).
• A flaky test does not block the iteration verdict, but the iteration is NOT Done until every unfixed flaky test is filed — an un-filed flaky test is a process gap.

Filing is the whole job. If the failure was NOT caused by your change, do NOT fix it in place — classify, file, and return to your task per the session-scope-guard rule. A repository-wide flaky test is a shared magnet — fixing it in place drifts off-task and collides with its owner ([org-internal #1803]).

Testing Kobalte components with happydom

Kobalte's portal/context-based components (Collapsible, DropdownMenu, ContextMenu, FormControlContext) do not work reliably under happydom's DOM environment. For these components, use source-verification tests — assert that the correct JSX elements, props, and Kobalte primitives are present in the component's source rather than attempting full DOM rendering.

When implementing a component that uses these Kobalte primitives, prefer source-verification over render tests. The same applies to SolidJS SVG <filter>/<mask>/<linearGradient> elements, which happydom also cannot render reliably.

Test file naming convention (one file per component)

A single component MUST NOT carry both a .test.ts and a .test.tsx test file — the two-file split duplicated ~3300 lines of overlapping assertions across one UI package [org-internal #1712]. Use exactly one file per component, chosen by test style:

Test style	Extension	When to use
Source-verification	.test.ts	Kobalte portal/context components, SVG <filter>/<mask>/<linearGradient> components, and any component happydom cannot render reliably. Asserts against the component source.
DOM render / interaction	.test.tsx	Pure Solid components that render cleanly under happydom. Uses a testing-library harness.

Rules:

• One file per component. If a component needs both source-verification and DOM-render assertions, keep them in a single file matching the dominant style; do not split into a .test.ts/.test.tsx pair.
• When merging an existing dual pair, carry over any assertion unique to the deleted file into the surviving file before deletion.
• The app package's .sv.test.* suffix is a separate convention for storybook/storyshots source-verification and is unaffected.

Source-verification assertion boundaries

Source-verification tests (per the Kobalte/happydom carve-out above) must assert structural contracts, not implementation literals.

• Assert: props wiring, event handler attachment, i18n key presence, ARIA role/attributes present in JSX, namespace correctness, export shape.
• Do NOT assert: exact source-string literals (event.preventDefault(), 'block: "nearest"', event.movementX === 0), branch operators counted via regex, or any expression that changes when a constant is renamed.
• Do NOT write tautologies — source.includes("false") || source.includes("!") is true for nearly all TSX.
• One source-verification file per component (see naming convention above). When two test files read the same source, merge into one.
• Prefer behavioral tests — when source-verification and a behavioral/ interaction test cover the same contract, prefer the behavioral test; collapse the SV duplicate.

Namespace gate and test assertions

The namespace gate (pre-commit hook + the check-namespace script) scans ALL string literals in .ts/.tsx/.json files under the product packages for a reserved vendor namespace. Do NOT write test assertions containing that namespace literal — the gate cannot distinguish a test's namespace-absence check from an actual namespace violation, and will fail the commit.

Instead, use patterns that avoid the literal:

const NAMESPACE = "vendor-prefix"
expect(source).not.toContain(`@${NAMESPACE}`)

Single test root (per package)

Each package MUST have exactly ONE test root — no parallel tracks (src/**/__tests__/, a tests/ dir alongside colocated src/, or a test/ alongside tests/); a second root drifts and breaks test discovery ([org-internal #1711], extended to all packages by [org-internal #1821]).

Rules:

• New tests: create them at the package's single root from the start.
• Do NOT create src/**/__tests__/ directories in any package — parallel tracks drift (residuals eliminated by [org-internal #1821]).
• For test/-root packages: mirror the src/ path (test/<src-relative>.test.ts); type-level tests live alongside the behavioral suites in the config area.
• For colocated-root packages: keep tests next to the source file; one test file per component [org-internal #1712].

Per-package root tables live in the instance layer (they name concrete package paths); the invariant itself — ONE root per package — is universal.