rsc-universal 0.1.1

package/skills/testing-py/references/property-testing.md

@@ -0,0 +1,99 @@
+# Property testing reference
+
+Depth behind the SKILL.md Hypothesis section: the strategy catalog, composite strategies, settings/profiles for CI vs local, regression pinning, the example DB, and stateful testing.
+
+Hypothesis is at 6.155.x (2026-06). The model: declare *strategies* describing the input space, assert a *property* that must hold for every input, and let Hypothesis search for a counterexample. On failure it **shrinks** the input to the minimal failing case and stores it in the `.hypothesis/` example database so the exact failure replays.
+
+## Strategy catalog
+
+```python
+from hypothesis import strategies as st
+
+st.integers(min_value=0, max_value=100)
+st.floats(allow_nan=False, allow_infinity=False)
+st.text()                              # arbitrary unicode
+st.text(alphabet="abc", min_size=1)
+st.from_regex(r"\d{3}-\d{4}", fullmatch=True)   # strings matching a pattern
+st.lists(st.integers(), min_size=1, max_size=10, unique=True)
+st.dictionaries(st.text(), st.integers())
+st.sampled_from(["GET", "POST", "PUT"])
+st.one_of(st.none(), st.integers())
+st.datetimes()
+st.builds(User, name=st.text(), age=st.integers(0, 120))   # construct a dataclass/object
+```
+
+`st.builds(Klass, ...)` is the workhorse for generating valid domain objects — give it the constructor and a strategy per field.
+
+## Composite strategies
+
+When fields are interdependent (a `start` before an `end`), build them together:
+
+```python
+@st.composite
+def date_ranges(draw):
+    start = draw(st.datetimes())
+    end = draw(st.datetimes(min_value=start))
+    return (start, end)
+
+@given(date_ranges())
+def test_range_duration_nonnegative(rng):
+    start, end = rng
+    assert (end - start).total_seconds() >= 0
+```
+
+## Common property shapes
+
+- **Roundtrip:** `decode(encode(x)) == x` — for serializers, codecs, parsers.
+- **Idempotence:** `f(f(x)) == f(x)` — for normalizers, dedupers, sorts.
+- **Invariant:** `len(sort(xs)) == len(xs)` and output is ordered — structure preserved.
+- **Oracle / cross-check:** the fast implementation agrees with a slow obviously-correct one.
+- **Metamorphic:** `sum(xs + ys) == sum(xs) + sum(ys)` — a relation between related inputs.
+
+## assume vs filter
+
+Use `assume(predicate)` to discard a generated input that is not a valid case. Prefer it over `st.filter` when the rejection is rare; if you reject most inputs, narrow the strategy instead (Hypothesis raises on too many filtered examples).
+
+```python
+from hypothesis import assume
+
+@given(st.integers())
+def test_inverse(n):
+    assume(n != 0)        # division undefined at 0; skip it
+    assert (1 / n) * n == pytest.approx(1)
+```
+
+## Pinning regressions with @example
+
+When a property test finds a bug, the example DB replays it locally — but pin it explicitly so it survives a cleared DB and documents the case:
+
+```python
+from hypothesis import given, example
+
+@given(st.text())
+@example("")            # the empty string broke us once; never regress
+@example("‮")      # a right-to-left override broke the parser once
+def test_parse(s):
+    assert parse(s) is not None
+```
+
+## Settings and profiles
+
+Run fewer examples locally for speed, more in CI for thoroughness:
+
+```python
+from hypothesis import settings, HealthCheck
+
+settings.register_profile("ci", max_examples=1000, deadline=None)
+settings.register_profile("dev", max_examples=50)
+# select with: HYPOTHESIS_PROFILE=ci pytest   (or settings.load_profile(...))
+```
+
+`deadline` aborts an example that runs too long (default 200ms); set `deadline=None` for legitimately slow code rather than letting it flake, and bound the strategy so examples stay cheap. Suppress `HealthCheck.too_slow` only when you have a concrete reason.
+
+## The example database in CI
+
+The `.hypothesis/examples` directory caches failing inputs so they replay first on the next run. To keep regression pinning across CI runs, persist that directory between builds (cache it) or commit it. Without persistence, CI re-searches from scratch and may not re-hit a rare failure, so combine the DB with explicit `@example` pins for anything important.
+
+## Stateful testing
+
+For systems whose correctness depends on a sequence of operations (a cache, a connection pool, a state machine), use `RuleBasedStateMachine`: declare `@rule` methods Hypothesis sequences randomly, with `@invariant` checks after each step. It finds order-dependent bugs that single-call property tests miss. Reach for it when "the bug only happens after a specific sequence of calls" — see the Hypothesis stateful-testing docs for the full API.

package/skills/testing-py/scripts/verify.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# verify.sh — testing-py static gate.
+#
+# Read-only lint over a Python test tree. It NEVER runs the tests, NEVER imports
+# anything, and NEVER writes a file. It greps for the false-green patterns this
+# skill bans and prints file:line for each hit.
+#
+# What it flags:
+#   1. .patch( / mock.patch( / mocker.patch( WITHOUT autospec= / spec= / spec_set=
+#      on the same logical call  -> mocks that pass on typos and signature drift.
+#   2. A --cov invocation that lacks --cov-branch, AND no `branch = true` /
+#      `--cov-branch` anywhere in pyproject.toml / .coveragerc / setup.cfg
+#      -> 100% lines, untested branches.
+#   3. time.sleep( inside test files  -> flaky-by-design.
+#   4. assert True  /  pytest.skip( with no reason  /  empty test bodies (def test_*(): pass)
+#      -> tests that can never fail or never run.
+#
+# Exit: non-zero if any hit; 0 when clean OR when the target has no test files
+# (an empty / missing tree is a clean skip, never a false failure).
+#
+# Portable to stock macOS bash 3.2: no mapfile, no associative arrays; arrays are
+# initialised so they expand safely under `set -u`.
+
+GREEN=$'\033[32m'; YELLOW=$'\033[33m'; RED=$'\033[31m'; NC=$'\033[0m'
+EXIT=0
+ok()   { printf '%s[ok]%s %s\n'   "$GREEN"  "$NC" "$*"; }
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; }
+fail() { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; EXIT=1; }
+
+TARGET="${1:-tests}"
+
+if [ ! -e "$TARGET" ]; then
+  skip "target '$TARGET' does not exist — nothing to lint"
+  exit 0
+fi
+
+# Collect Python test files. A bare file arg is scanned directly even if unnamed.
+FILES=()
+if [ -d "$TARGET" ]; then
+  while IFS= read -r -d '' f; do
+    FILES+=("$f")
+  done < <(find "$TARGET" -type f \( -name 'test_*.py' -o -name '*_test.py' -o -name 'conftest.py' \) -print0 2>/dev/null)
+elif [ -f "$TARGET" ]; then
+  FILES+=("$TARGET")
+fi
+
+if [ "${#FILES[@]}" -eq 0 ]; then
+  skip "no test files under '$TARGET' (test_*.py / *_test.py / conftest.py) — clean"
+  exit 0
+fi
+
+# ---- 1. patch/mock without autospec/spec/spec_set ----
+# A patch call is suspect when the same physical line has a patch( and none of
+# autospec= / spec= / spec_set=. Multi-line patch calls are a known false-negative;
+# this gate targets the common single-line form.
+for f in "${FILES[@]}"; do
+  while IFS=: read -r ln _; do
+    [ -n "${ln:-}" ] && fail "$f:$ln: patch() without autospec=/spec=/spec_set= (false-green risk)"
+  done < <(grep -nE '(mock\.|mocker\.|[^A-Za-z_])patch\(' "$f" 2>/dev/null \
+             | grep -Ev 'autospec=|spec=|spec_set=' \
+             | grep -Ev '^[[:space:]]*#' \
+             | cut -d: -f1 | sed 's/$/:/' )
+done
+
+# ---- 2. time.sleep( in test files ----
+for f in "${FILES[@]}"; do
+  while IFS=: read -r ln _; do
+    [ -n "${ln:-}" ] && fail "$f:$ln: time.sleep() in a test (flaky-by-design; fake the clock)"
+  done < <(grep -nE 'time\.sleep\(|[^A-Za-z_]sleep\(' "$f" 2>/dev/null | cut -d: -f1 | sed 's/$/:/')
+done
+
+# ---- 3. no-op tests ----
+for f in "${FILES[@]}"; do
+  while IFS=: read -r ln _; do
+    [ -n "${ln:-}" ] && fail "$f:$ln: assert True / no-op assertion (a test that can never fail)"
+  done < <(grep -nE 'assert[[:space:]]+True[[:space:]]*$|assert[[:space:]]+True[[:space:]]*#' "$f" 2>/dev/null | cut -d: -f1 | sed 's/$/:/')
+  # pytest.skip( with no reason string
+  while IFS=: read -r ln _; do
+    [ -n "${ln:-}" ] && fail "$f:$ln: pytest.skip() with no reason"
+  done < <(grep -nE 'pytest\.skip\([[:space:]]*\)' "$f" 2>/dev/null | cut -d: -f1 | sed 's/$/:/')
+  # def test_*(...): pass  on one line
+  while IFS=: read -r ln _; do
+    [ -n "${ln:-}" ] && fail "$f:$ln: empty test body (def test_*(): pass)"
+  done < <(grep -nE 'def[[:space:]]+test_[A-Za-z0-9_]*\([^)]*\)[[:space:]]*:[[:space:]]*pass[[:space:]]*$' "$f" 2>/dev/null | cut -d: -f1 | sed 's/$/:/')
+done
+
+# ---- 4. --cov without --cov-branch (config-aware) ----
+# Only meaningful if a --cov invocation is present somewhere in the target's scope
+# or its config. We look at the test files plus the usual config files near them.
+CONFIG_HAS_BRANCH=0
+SEARCH_ROOTS=()
+if [ -d "$TARGET" ]; then SEARCH_ROOTS+=("$TARGET" "$TARGET/.."); else SEARCH_ROOTS+=("$(dirname "$TARGET")"); fi
+for root in "${SEARCH_ROOTS[@]}"; do
+  for cfg in "$root/pyproject.toml" "$root/.coveragerc" "$root/setup.cfg" "$root/tox.ini"; do
+    if [ -f "$cfg" ] && grep -Eq 'branch[[:space:]]*=[[:space:]]*[Tt]rue|--cov-branch' "$cfg" 2>/dev/null; then
+      CONFIG_HAS_BRANCH=1
+    fi
+  done
+done
+
+if [ "$CONFIG_HAS_BRANCH" -eq 0 ]; then
+  for f in "${FILES[@]}"; do
+    while IFS=: read -r ln _; do
+      [ -n "${ln:-}" ] && fail "$f:$ln: --cov without --cov-branch and no branch=true in config (line coverage lies)"
+    done < <(grep -nE -- '--cov[=[:space:]]' "$f" 2>/dev/null | grep -Ev -- '--cov-branch' | cut -d: -f1 | sed 's/$/:/')
+  done
+fi
+
+printf '\n'
+if [ "$EXIT" -eq 0 ]; then
+  ok "verify.sh passed — no banned test patterns in '$TARGET' (${#FILES[@]} files)"
+else
+  fail "verify.sh found banned test patterns"
+fi
+exit "$EXIT"

package/skills/testing-web/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: testing-web
+description: "Use when writing or fixing frontend unit, component, or custom-hook tests with Vitest or Jest plus Testing Library — rendering a React/Vue/Svelte component in jsdom, testing a hook in isolation, killing 'not wrapped in act' warnings, or migrating a Jest suite to Vitest. Triggers: 'test this component', 'renderHook for my useCountdown', 'getBy vs findBy, my query is flaky', 'An update to X was not wrapped in act warning', 'mock fetch in a Vitest test', 'set up Vitest with React Testing Library', 'test mi componente de carrito', 'provar un hook amb renderHook'. NOT real-browser multi-page journeys (that is e2e-testing), NOT pytest suites (that is testing-py), NOT axe/contrast/keyboard auditing (that is accessibility)."
+tags: [testing, frontend, vitest, jest, testing-library, react, hooks, component-testing, jsdom]
+recommends: [e2e-testing, accessibility, testing-py, react, nextjs, debug]
+origin: risco
+---
+
+# testing-web — fast, trustworthy component and hook tests
+
+A frontend test is only worth keeping if it survives a refactor and fails for the right reason.
+The way to get there is boring and non-negotiable: render the thing, query it the way a user finds
+it, drive it with real events, and assert on what the user can see. Everything in this skill bends
+toward that. Tests that reach into `className`, `state`, props, or instance methods pass while the UI
+is broken and break while the UI is fine — delete that instinct.
+
+## What this owns / what it doesn't
+
+This skill owns unit, component, and custom-hook tests that run in a simulated DOM (jsdom) or Vitest
+Browser Mode at component granularity. The moment scope crosses a boundary, switch skills:
+
+- Real browser driving a whole app, page navigation, multi-page login-to-dashboard journeys -> [`../e2e-testing/SKILL.md`](../e2e-testing/SKILL.md).
+- pytest / fixtures / Python suites -> [`../testing-py/SKILL.md`](../testing-py/SKILL.md).
+- axe runs, contrast ratios, keyboard-nav auditing as the *goal* -> [`../accessibility/SKILL.md`](../accessibility/SKILL.md). (You will use role queries here; auditing is not the job.)
+- Render/runtime perf, re-render counts, web vitals -> [`../debug/SKILL.md`](../debug/SKILL.md) for diagnosis.
+- How to build the component in the first place -> [`../react/SKILL.md`](../react/SKILL.md) or [`../nextjs/SKILL.md`](../nextjs/SKILL.md).
+
+## Pick the runner (do this once, never run both)
+
+| Project shape | Runner | Why |
+|---|---|---|
+| New Vite / React 19 / Next 16 repo | **Vitest 4** | Shares your `vite.config`, zero second transform pipeline, Browser Mode is stable as of v4.0 (Oct 2025). |
+| Established Jest / CRA / React Native repo | **Jest 30** | Migration cost outweighs the win; Jest 30 is current (min Node 18.x, min TS 5.4). |
+| Both installed | pick one and rip the other out | Two runners means two configs, two mock APIs, doubled CI — and tests that pass in one, fail in the other. |
+
+Vitest is the de-facto default for new frontend projects in 2026; Jest stays where it already lives.
+Jest 30 specifics (ts-jest vs babel, the jsdom v26 `window.location` break) live in
+[`references/jest-setup.md`](references/jest-setup.md).
+
+## Minimal Vitest setup that works
+
+Pin current majors: `vitest ^4.0`, `@testing-library/react ^16.3`, `@testing-library/jest-dom ^6.9`,
+`@testing-library/user-event ^14.6`, `jsdom`, `@vitejs/plugin-react`.
+
+```ts
+// vitest.config.ts
+import { defineConfig } from "vitest/config";
+import react from "@vitejs/plugin-react";
+
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    environment: "jsdom",   // give the test a DOM; default 'node' has no document
+    globals: true,          // describe/it/expect without imports; jest-dom matchers register globally
+    setupFiles: ["./vitest.setup.ts"],
+  },
+});
+```
+
+```ts
+// vitest.setup.ts
+import "@testing-library/jest-dom/vitest"; // the /vitest entry — NOT the bare import (that is Jest's)
+```
+
+The `/vitest` import path matters: the bare `@testing-library/jest-dom` registers against Jest's
+`expect`. Wrong path = `toBeInTheDocument is not a function`.
+
+## The one rule: test what the user sees
+
+Query and assert on the rendered output a human perceives, never the mechanism. This is what makes a
+test outlive a refactor — rename a state variable, swap a class library, restructure the tree, and a
+behavioral test still passes.
+
+```tsx
+// Bad — coupled to internals; passes when broken, breaks when fine
+expect(wrapper.find(".btn--loading")).toHaveLength(1);
+expect(component.state.isOpen).toBe(true);
+
+// Good — coupled to user-observable behavior
+expect(screen.getByRole("button", { name: /saving/i })).toBeDisabled();
+expect(screen.getByRole("dialog")).toBeVisible();
+```
+
+## Query priority ladder
+
+Reach for the highest query that fits. `getByTestId` is the fire escape, not the front door — it
+asserts nothing about accessibility or labels.
+
+| Priority | Query | Use for |
+|---|---|---|
+| 1 | `getByRole(name)` | Almost everything: buttons, headings, inputs, dialogs, links. |
+| 2 | `getByLabelText` | Form fields tied to a `<label>`. |
+| 3 | `getByPlaceholderText` | Inputs with only a placeholder (prefer a real label). |
+| 4 | `getByText` | Non-interactive copy, paragraphs, list items. |
+| 5 | `getByDisplayValue` | Asserting a filled-in input's current value. |
+| last | `getByTestId` | Only when no role/label/text identifies the node. |
+
+Pick the right variant by what you expect:
+
+| Variant | Returns | Throws if absent? | Use when |
+|---|---|---|---|
+| `getBy*` | element now | yes | element must already be there |
+| `queryBy*` | element or `null` | no (returns null) | asserting **absence** (`expect(...).toBeNull()`) |
+| `findBy*` | Promise of element | rejects after timeout | element **appears later** (after fetch/async) |
+
+Never `getBy` something that arrives asynchronously — it throws before the element mounts. That is what
+`findBy` is for.
+
+## Driving interactions
+
+Set up `user-event` once per test and `await` every interaction. It dispatches the full realistic event
+sequence (pointerdown -> mousedown -> focus -> mouseup -> click), so it catches handlers `fireEvent`
+silently skips.
+
+```tsx
+import userEvent from "@testing-library/user-event";
+
+it("submits the typed name", async () => {
+  const user = userEvent.setup();           // call setup() before interacting
+  render(<Greeter />);
+  await user.type(screen.getByLabelText(/name/i), "Ada"); // await — these are async
+  await user.click(screen.getByRole("button", { name: /greet/i }));
+  expect(screen.getByText(/hello, ada/i)).toBeInTheDocument();
+});
+```
+
+Reach for `fireEvent` only for events `user-event` has no verb for (e.g. `scroll`). A missing `await`
+is the single most common source of "passes locally, flakes in CI."
+
+## Async and the act() warning
+
+"An update to X was not wrapped in act(...)" means state updated after your assertion ran — the test
+finished, the component kept working, React complained. The fix in a **component** test is almost never
+a manual `act()`. It is to *wait* for the observable result:
+
+```tsx
+// Bad — asserts before the fetch resolves; state lands "outside act"
+render(<Profile id="1" />);
+expect(screen.getByText("Ada")).toBeInTheDocument(); // throws / act warning
+
+// Good — findBy retries until the node appears, inside RTL's act wrapper
+render(<Profile id="1" />);
+expect(await screen.findByText("Ada")).toBeInTheDocument();
+```
+
+For a transition you can't pin to a single element, wrap the assertion in `waitFor`. Bare `act()` in a
+component test is a code smell — it belongs to hook tests (next section).
+
+## Testing hooks
+
+`renderHook` ships inside **`@testing-library/react`** itself. Do not install or import the long-deprecated
+`@testing-library/react-hooks`. Read live values off `result.current`; wrap any setter call you trigger
+yourself in `act()`; re-run with new props via `rerender`; await async settle with `waitFor`.
+
+```tsx
+import { renderHook, act, waitFor } from "@testing-library/react";
+
+it("counts down then stops at zero", async () => {
+  const { result, rerender } = renderHook(({ from }) => useCountdown(from), {
+    initialProps: { from: 3 },
+  });
+  expect(result.current.value).toBe(3);
+
+  act(() => result.current.start());     // a setter YOU invoke -> wrap in act
+  await waitFor(() => expect(result.current.value).toBe(0)); // async settle -> waitFor
+
+  rerender({ from: 10 });                // feed new props
+  expect(result.current.value).toBe(10);
+});
+```
+
+## Mocking the boundary
+
+Mock at the edge your code talks to the outside world — the network or the imported module — never the
+internal function you are trying to verify. Mock the unit under test and the test proves nothing.
+
+- **Network**: prefer **MSW** (`http.get(...)` handlers) so components hit a real `fetch`/`axios` path. It survives client-library swaps.
+- **A whole module**: `vi.mock("./api")` (Vitest) / `jest.mock("./api")` (Jest) for non-network collaborators.
+- **Time**: `vi.useFakeTimers()` for timers/debounce; advance with `vi.advanceTimersByTime(ms)`, then restore in cleanup.
+
+```ts
+import { vi } from "vitest";
+vi.mock("./flags", () => ({ isEnabled: () => true })); // a boundary module, not the component
+```
+
+Runnable copy-paste recipes — form submit, controlled input, MSW async data, a provider-wrapping custom
+`render`, fake timers, a hook with an effect + cleanup, an error-boundary test — live in
+[`references/recipes.md`](references/recipes.md).
+
+## Snapshots vs assertions
+
+Default to explicit behavioral assertions. A snapshot proves nothing about correctness — it proves output
+didn't change, and a giant DOM snapshot gets blindly `--updated` the first time it breaks. Snapshot only
+small, stable, serializable output (a formatted currency string, a normalized config object). Never
+snapshot a full component tree as your primary assertion.
+
+## Anti-patterns
+
+| Anti-pattern | Why it's wrong | Do instead |
+|---|---|---|
+| `getByTestId` as first choice | Asserts nothing about a11y or labels; survives broken markup | Climb the ladder: role > label > text first |
+| `getBy*` for async content | Throws before the element mounts | `await findBy*` / `await waitFor(...)` |
+| Interaction without `await` | Assertion runs before the event settles; flakes in CI | `await user.click(...)` every time |
+| `fireEvent.click` by default | Skips the realistic pointer/focus sequence | `userEvent.setup()` then `await user.click` |
+| Manual `act()` in a component test | Masks the real fix (waiting for output) | Await `findBy`/`waitFor` instead |
+| Asserting on `state`/`props`/`className` | Couples the test to internals; breaks on refactor | Assert on rendered role/text the user sees |
+| `setTimeout`/`sleep` to wait | Arbitrary delay = slow + still flaky | `findBy`/`waitFor` retries until ready |
+| Mocking the unit under test | The test verifies the mock, not the code | Mock the network/module boundary only |
+| Importing `@testing-library/react-hooks` | Deprecated; folded into `@testing-library/react` | Import `renderHook` from `@testing-library/react` |
+| Bare `@testing-library/jest-dom` in Vitest | Registers against Jest's expect -> matcher missing | Import `@testing-library/jest-dom/vitest` |
+| Running Jest and Vitest in one suite | Two configs/mock APIs; passes in one, fails in other | Pick one runner, remove the other |
+| A test file with zero `expect(...)` | Renders but verifies nothing; green by accident | Every test asserts an observable outcome |
+
+## Verify your suite
+
+Run the linter against a test file or directory to catch these shape violations before review:
+
+```bash
+scripts/verify.sh src/components/__tests__
+```
+
+It hard-fails on tests with no assertion and on un-awaited interactions, and warns on testid-first
+queries, raw `fireEvent`, stray `act()` in component files, and `setTimeout`-based waiting. It checks
+artifact *shape*, not whether your assertions are true.

package/skills/testing-web/evals/README.md

@@ -0,0 +1,11 @@
+# Evals — testing-web
+
+`cases.yaml` is the trigger-routing and capability spec for this skill. There is no automated runner
+bundled here; run it the way you run the rest of the catalog's evals. Feed each `should_trigger` /
+`should_not_trigger` prompt to the router and confirm `testing-web` is (or isn't) selected, checking that
+declined prompts route to the named sibling. For `capability`, hand the scenario to the agent with this
+skill loaded and grade the produced test file against the `must_include` rubric — every item should be
+demonstrably present (awaited user-event, role/label queries, boundary-mocked network, async findBy,
+real assertions, no internal-detail coupling). The rubric is pass/fail per line; a missing item is a
+miss. `scripts/verify.sh` can statically lint the generated test file as a fast pre-check, but it
+validates artifact shape, not whether the rubric's intent was met.

package/skills/testing-web/evals/cases.yaml

@@ -0,0 +1,52 @@
+skill: testing-web
+
+should_trigger:
+  - prompt: "Write a Vitest test for this LoginForm component that fills the fields and clicks submit."
+    why: Core component-test request — render in jsdom, drive with user-event, assert on output. The center of this skill.
+  - prompt: "I keep getting 'An update to Profile was not wrapped in act(...)' in my test. How do I fix it?"
+    why: Non-obvious symptom this skill owns; the real fix is awaiting findBy/waitFor, not a manual act() wrap.
+  - prompt: "How do I test my useCountdown custom hook in isolation?"
+    why: Hook testing via renderHook from @testing-library/react (not the deprecated react-hooks package).
+  - prompt: "test mi componente de carrito con Testing Library, que al añadir un producto suba el total"
+    why: Spanish trigger — component behavior test (add item -> total updates) via role/text queries.
+  - prompt: "Vull provar un hook amb renderHook però no sé com llegir result.current"
+    why: Catalan trigger — reading hook state off result.current and wrapping setters in act().
+  - prompt: "Should I use getByText or findByText here? My query passes sometimes and throws other times."
+    why: Non-obvious query-semantics flakiness — async content needs findBy, sync needs getBy. This skill's exact lane.
+  - prompt: "Migrate our Jest component tests to Vitest, including the jest-dom matchers and mocks."
+    why: Jest -> Vitest migration of frontend component tests, including the jest-dom import-path swap.
+
+should_not_trigger:
+  - prompt: "Write a Playwright test that logs in and verifies the dashboard page loads."
+    route_to: e2e-testing
+    why: Real browser driving a multi-page journey, not a jsdom component test.
+  - prompt: "Add pytest tests for my FastAPI endpoints with fixtures."
+    route_to: testing-py
+    why: Python test suite, a different runner and ecosystem entirely.
+  - prompt: "Run an axe accessibility audit on this page and fix the color-contrast failures."
+    route_to: accessibility
+    why: Auditing a11y/contrast as the goal, not authoring component tests (which merely use role queries).
+  - prompt: "Why does this React component re-render so many times and slow down the page?"
+    route_to: debug
+    why: Runtime performance diagnosis, not writing or fixing a test.
+  - prompt: "Review this PR diff for correctness bugs before I merge."
+    route_to: review
+    why: Code review of a diff, not authoring frontend tests.
+  - prompt: "Write Go table-driven tests for my handler package."
+    route_to: testing-go
+    why: Go test suite, outside the web/DOM scope of this skill.
+
+capability:
+  - scenario: >
+      Given a React <SearchBox> that calls fetch('/api/search?q=...') on submit and renders the result
+      titles as a list, write a complete Vitest + React Testing Library test file proving that typing a
+      query and submitting shows the matching results, and that a server error shows an error message.
+    must_include:
+      - Vitest config or test assumes jsdom environment and @vitejs/plugin-react (or relies on existing setup)
+      - Calls userEvent.setup() and awaits every interaction (await user.type / await user.click)
+      - Queries by role/label/text (e.g. getByRole searchbox/button), not getByTestId as the primary query
+      - Mocks the network at the boundary — MSW handlers or vi.mock of the fetch module, not the component internals
+      - Asserts rendered results appear via await findBy* (waiting for async data), not getBy for async content
+      - Tests an error path (500 -> visible error / role=alert) in a separate case
+      - No bare act() misuse in the component test; no assertions on state/props/className
+      - At least one real expect(...) assertion per test

package/skills/testing-web/references/jest-setup.md

@@ -0,0 +1,88 @@
+# Jest 30 setup (for repos already on Jest)
+
+Use this only when the project is already invested in Jest (CRA, React Native, an old monorepo).
+New projects: use Vitest 4 (see SKILL.md). Never run both runners in one suite.
+
+## Versions that go together
+
+- **Jest 30** (current, 30.2.x) — min **Node 18.x** (drops 14/16/19/21), min **TypeScript 5.4**.
+- `jest-environment-jsdom` runs on **jsdom v26/27**.
+- React 19 is supported in `pretty-format` (snapshot serialization).
+- `@testing-library/react ^16.3`, `@testing-library/user-event ^14.6`, `@testing-library/jest-dom ^6.9`.
+
+## Config
+
+```js
+// jest.config.js
+module.exports = {
+  testEnvironment: "jsdom",          // not the default 'node'
+  setupFilesAfterEnv: ["<rootDir>/jest.setup.ts"],
+  // ts-jest OR babel-jest below — pick one, see "TS transform"
+};
+```
+
+```ts
+// jest.setup.ts
+import "@testing-library/jest-dom"; // bare import here — this is the Jest entry (Vitest uses /vitest)
+```
+
+The import path is the opposite of Vitest: in Jest the **bare** `@testing-library/jest-dom` is correct
+because it registers against Jest's global `expect`. Using `/vitest` here fails.
+
+## TS transform: ts-jest vs babel-jest
+
+| Choice | When | Trade-off |
+|---|---|---|
+| **ts-jest** | You want real type-checking during tests | Slower; surfaces type errors as test failures |
+| **babel-jest** (`@babel/preset-typescript`) | You already have Babel; want speed | Strips types, no type-checking — rely on `tsc --noEmit` separately |
+
+```js
+// ts-jest
+module.exports = { preset: "ts-jest", testEnvironment: "jsdom" };
+```
+
+```js
+// babel-jest — add to babel.config.js
+module.exports = {
+  presets: [
+    ["@babel/preset-env", { targets: { node: "current" } }],
+    "@babel/preset-typescript",
+    ["@babel/preset-react", { runtime: "automatic" }],
+  ],
+};
+```
+
+## The Jest 30 breaking change that bites tests: window.location
+
+jsdom became spec-compliant, so `window.location` is **no longer freely reassignable**. The old trick
+breaks:
+
+```ts
+// Bad — throws "Cannot assign to read only property" under Jest 30 / jsdom v26+
+delete (window as any).location;
+window.location = { href: "https://x.test" } as any;
+```
+
+```ts
+// Good — mutate individual props, or stub the navigation method
+Object.defineProperty(window, "location", {
+  value: new URL("https://x.test/dashboard"),
+  writable: true,
+});
+// or, for assignment-based navigation:
+const assign = jest.fn();
+Object.defineProperty(window, "location", { value: { assign }, writable: true });
+```
+
+## Mock API parity with Vitest
+
+| Vitest | Jest |
+|---|---|
+| `vi.mock("./api")` | `jest.mock("./api")` |
+| `vi.fn()` | `jest.fn()` |
+| `vi.spyOn(obj, "m")` | `jest.spyOn(obj, "m")` |
+| `vi.useFakeTimers()` | `jest.useFakeTimers()` |
+| `vi.advanceTimersByTime(ms)` | `jest.advanceTimersByTime(ms)` |
+
+When migrating Jest -> Vitest, this table plus the jest-dom import swap (`/vitest`) and the config move
+(`jest.config` -> `test:` block in `vite.config`/`vitest.config`) covers the bulk of the mechanical diff.