/happier-testing

name: happier-testing
description: Repo-specific TDD and test-validation workflow for Happier changes, with lane selection, fixture policy, and anti-flake guardrails.
metadata: {"openclaw":{"homepage":"https://github.com/happier-dev/happier"}}

Happier Testing And TDD

Use this skill for behavior-changing work in this repository, especially when changes touch shared runtime contracts, CLI/server/UI flows, or any lane that historically accumulates stale fixtures.

Goal

Apply strict RED-GREEN-REFACTOR while following Happier-specific lane, fixture, and rerun rules so changes do not silently drift until a late pipeline sweep.

Workflow

1. **Inventory first**

• Search for existing tests by symbol, route, command, feature id, config key, component name, or error code.
• Map the affected lane(s) and any shared/package-local harnesses the change can invalidate before editing code.
• Name the observable contract or material risk the test must distinguish before writing it.
• For user-visible or environment-dependent work, define the composed live recipe before implementation: exact entry point, provider/account/state, actions, expected outcome, recovery path, and build/bundle/runtime identity that will prove the result.
• Update the most relevant existing test first when possible.
• Consolidate overlapping tests instead of stacking new ones on top.

2. **Classify failures correctly**

• `production bug`: runtime behavior is wrong
• `test drift`: assertions/fixtures assume an obsolete contract
• `harness drift`: helpers/mocks/testkit no longer match real runtime wiring
• `infra/resource issue`: disk, Docker, stale child processes, or similar environment failures

3. **RED**

• Write or update the smallest relevant test first.
• Run only the smallest relevant slice and confirm it fails because the intended behavior is missing or wrong, not because of setup, fixtures, mocks, wording, syntax, or an unrelated error.

4. **GREEN**

• Implement the smallest fix that satisfies the failing behavior.
• Keep internal behavior real; mock only system boundaries.

5. **REFACTOR**

• Extract shared helpers only when there is repeated real duplication or repeated stale drift.
• Keep file responsibilities focused.

6. **Broaden validation**

• After a targeted green run in a shared area, rerun one broader related lane.
• Before handoff, rerun the touched package typecheck/build-enforcing lane and the relevant repo lanes.

Test Value Gate

• Scope-preserving solution economy never caps evidence. Test and QA depth follow materially distinct behavior, reachable failure modes, and risk; implementation size, line count, or a desire for one runnable check cannot justify dropping a required contract, edge/failure/recovery case, compatibility direction, platform path, or live gate.
• TDD proves an observable contract; it does not require a new test for every changed function, branch, helper, or file.
• Prefer strengthening or consolidating the canonical owner-level test over adding overlapping coverage.
• One discriminating test is more valuable than many shallow permutations. Add cases only for materially different contracts, boundaries, or failure modes.
• A useful test distinguishes the intended implementation from at least one plausible incorrect implementation. If it would pass both, strengthen or remove it.
• Do not add runtime tests that merely restate TypeScript types, mirror implementation structure, assert pass-through wiring or incidental call counts, or police wording, formatting, raw styles, or example values.
• Exercise real internal behavior through the canonical/public owner boundary whenever practical.
• Remove or consolidate redundant tests introduced or exposed by the change.

Compatibility Contract Gate

• Use `skills/happier-compatibility` when a behavior change affects wire/semantic contracts, persistence, schemas/migrations, feature negotiation, installer/service state, mixed versions, upgrades, or rollback.
• Name the exact released/predecessor producer and consumer plus the direction the test proves. Prefer the real historical serializer/client/artifact or a provenance-pinned golden vector; do not reconstruct “old” behavior from current types or a new mock.
• Add one discriminating contract/vector test per material reachable direction, then only the risk-selected end-to-end flows. Do not multiply UI × CLI × daemon × server permutations when the changed seam does not couple them.
• Inventory and consolidate existing compatibility fixtures and harnesses before adding another family; a compatibility test must not create a second implementation of the protocol it is meant to verify.

Happier Lane Map

Canonical top-level lanes:

• `yarn test`
• `yarn test:integration`
• `yarn test:e2e:core:fast`
• `yarn test:e2e:core:slow`
• `yarn test:e2e:ui`
• `yarn test:providers`
• `yarn test:db-contract:docker`

CLI lane rule:

• `apps/cli` unit tests must not force a full CLI `dist` build.
• Use the lane-specific global setup files:
• `src/test-setup.unit.ts`
• `src/test-setup.integration.ts`
• `src/test-setup.slow.ts`

Fixture And Mock Policy

• Do not partially mock central shared modules such as `@/sync/domains/state/storage`.
• Prefer package-local shared factories/testkits for repeated boundary mocks.
• Keep cross-repo primitives in `packages/tests/src/testkit`.
• Before adding a new helper or mock family, inspect the codebase for the existing canonical testkit/helper for that boundary.
• Prefer reusing, extending, generalizing, or extracting from canonical helpers over introducing similar-but-different variants.
• When a new canonical helper replaces older local variants, migrate or remove the overlapping variants instead of leaving parallel helper families behind.
• Be careful with repeat-offender boundaries: prefer canonical helpers over fresh inline mocks for UI boundaries such as `expo-router`, `@/text`, `@/modal`, `react-native`, and `react-native-unistyles`; prefer exis