rsc-universal 0.1.1

package/skills/testing-go/references/mocks-and-fakes.md

@@ -0,0 +1,140 @@
+# Mocks, fakes & HTTP test doubles
+
+The default is a hand-written fake. This file covers the decision, minimal templates for the three approaches, and `net/http/httptest` recipes.
+
+## Which double?
+
+| You have | Use |
+|---|---|
+| An interface you own, small surface, you care about values not call order | Hand-rolled func-field fake |
+| A large interface where the **sequence and arguments** of calls is the contract under test | `go.uber.org/mock` (gomock) |
+| An existing codebase already standardized on testify | `testify/mock` (consistency over preference) |
+| An HTTP client or handler | `net/http/httptest` (below) — not a mock |
+
+`go.uber.org/mock` is the maintained successor to the archived `github.com/golang/mock`. Use it, not the original.
+
+## Hand-rolled fake (default)
+
+Declare the interface at the consumer, keep it minimal, give the fake a func field per method so each test sets exactly the behavior it needs.
+
+```go
+type Store interface {
+	Get(ctx context.Context, id string) (Item, error)
+	Put(ctx context.Context, it Item) error
+}
+
+type fakeStore struct {
+	get func(ctx context.Context, id string) (Item, error)
+	put func(ctx context.Context, it Item) error
+}
+
+func (f fakeStore) Get(ctx context.Context, id string) (Item, error) { return f.get(ctx, id) }
+func (f fakeStore) Put(ctx context.Context, it Item) error          { return f.put(ctx, it) }
+
+func TestService_NotFound(t *testing.T) {
+	s := Service{store: fakeStore{
+		get: func(context.Context, string) (Item, error) { return Item{}, ErrNotFound },
+	}}
+	if _, err := s.Lookup(t.Context(), "x"); !errors.Is(err, ErrNotFound) {
+		t.Fatalf("err = %v, want ErrNotFound", err)
+	}
+}
+```
+
+For a stateful fake (e.g. an in-memory store), back it with a `map` and a `sync.Mutex` instead of func fields. That doubles as a usable test fixture for many tests at once.
+
+## gomock template
+
+Generate from the interface, then set expectations:
+
+```bash
+go install go.uber.org/mock/mockgen@latest
+mockgen -source=store.go -destination=mock_store_test.go -package=mypkg
+```
+
+```go
+func TestService_callsPutOnce(t *testing.T) {
+	ctrl := gomock.NewController(t)
+	m := NewMockStore(ctrl)
+	m.EXPECT().Put(gomock.Any(), gomock.Any()).Return(nil).Times(1)
+	// ... exercise; ctrl asserts expectations at test cleanup
+}
+```
+
+The payoff is automatic call-count and argument verification; the cost is generated files, regen on every interface change, and tests coupled to call order. Worth it only when that order is the contract.
+
+## testify/mock template
+
+```go
+type MockStore struct{ mock.Mock }
+
+func (m *MockStore) Get(ctx context.Context, id string) (Item, error) {
+	args := m.Called(ctx, id)
+	return args.Get(0).(Item), args.Error(1)
+}
+
+// in the test:
+m := new(MockStore)
+m.On("Get", mock.Anything, "x").Return(Item{}, ErrNotFound)
+m.AssertExpectations(t)
+```
+
+Use only where the repo already uses testify for mocks; otherwise prefer the func-field fake.
+
+## httptest recipes
+
+**Test an HTTP client** against a fake server:
+
+```go
+func TestClient_Fetch(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/items/42" {
+			http.NotFound(w, r)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = io.WriteString(w, `{"id":"42"}`)
+	}))
+	defer srv.Close()
+
+	c := NewClient(srv.URL)
+	it, err := c.Fetch(t.Context(), "42")
+	if err != nil {
+		t.Fatalf("Fetch: %v", err)
+	}
+	if it.ID != "42" {
+		t.Errorf("ID = %q, want 42", it.ID)
+	}
+}
+```
+
+**Test an `http.Handler`** with a recorder — no server, no socket:
+
+```go
+func TestHandler_OK(t *testing.T) {
+	req := httptest.NewRequest(http.MethodGet, "/health", nil)
+	rec := httptest.NewRecorder()
+	Handler().ServeHTTP(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Errorf("status = %d, want 200", rec.Code)
+	}
+}
+```
+
+**Fake transport** when you cannot change the base URL — swap the `RoundTripper`:
+
+```go
+type roundTripFunc func(*http.Request) (*http.Response, error)
+
+func (f roundTripFunc) RoundTrip(r *http.Request) (*http.Response, error) { return f(r) }
+
+client := &http.Client{Transport: roundTripFunc(func(r *http.Request) (*http.Response, error) {
+	return &http.Response{
+		StatusCode: 200,
+		Body:       io.NopCloser(strings.NewReader(`{"ok":true}`)),
+		Header:     make(http.Header),
+	}, nil
+})}
+```
+
+Prefer `httptest.NewServer` when the code under test takes a URL; reach for the `RoundTripper` only when it constructs the client internally.

package/skills/testing-go/references/synctest-and-concurrency.md

@@ -0,0 +1,82 @@
+# synctest & concurrency
+
+Deterministic tests for goroutines, timers, and `context` deadlines, plus the race detector and leak detection. Target Go 1.25.
+
+## The bubble model
+
+`synctest.Test(t, func(t *testing.T){ ... })` runs the body inside an isolated **bubble**:
+
+- The bubble has its own **fake clock**, starting at a fixed instant. `time.Now`, `time.Sleep`, `time.After`, `time.NewTimer`, `time.NewTicker`, and `context` deadlines inside the bubble all read this fake clock.
+- The fake clock **does not tick on its own**. It only advances when every goroutine in the bubble is **durably blocked** — at which point it jumps forward to the next scheduled timer instantly. A test of a one-hour timeout therefore finishes in microseconds.
+- Goroutines started inside the bubble belong to the bubble. The bubble is done when all of them exit.
+
+```go
+func TestRetryBackoff(t *testing.T) {
+	synctest.Test(t, func(t *testing.T) {
+		start := time.Now()
+		err := retry(t.Context(), 3, time.Second, alwaysFail)
+		elapsed := time.Since(start) // fake-clock elapsed, computed instantly
+		if !errors.Is(err, errExhausted) {
+			t.Fatalf("err = %v", err)
+		}
+		if elapsed != 3*time.Second { // 1s + 2s backoff, deterministic
+			t.Errorf("elapsed = %v, want 3s", elapsed)
+		}
+	})
+}
+```
+
+## Durably blocked — the exact definition
+
+A goroutine is **durably blocked** when it is blocked and can only be unblocked by another goroutine in the same bubble. That covers: receiving/sending on a bubble channel with no ready counterpart, `select` with no ready case, `sync.WaitGroup.Wait`, `sync.Mutex.Lock` contention, and `time.Sleep`.
+
+It does **not** cover blocking on something outside the bubble: a real network read, a system call, a channel shared with a goroutine started before the bubble. If a bubble goroutine blocks on the outside world, the fake clock will not advance and the test hangs. Keep all I/O inside the bubble fake, or out of the synctest body entirely.
+
+## synctest.Wait()
+
+`synctest.Wait()` blocks the calling goroutine until every **other** goroutine in the bubble is durably blocked. Use it to reach a known quiescent point before asserting:
+
+```go
+go worker(ch)
+ch <- job
+synctest.Wait()        // worker has processed and is now blocked waiting again
+if got := metrics.Load(); got != 1 {
+	t.Errorf("processed = %d, want 1", got)
+}
+```
+
+Without `Wait()` you would race the assertion against the worker.
+
+## Race detector
+
+Run anything concurrent with `-race`:
+
+```bash
+go test -race ./...
+go test -race -run TestRetryBackoff -count=10 ./internal/retry
+```
+
+`-count=10` re-runs to flush out order-dependent flakiness. The race detector instruments memory access; it roughly doubles runtime and memory, so it lives in CI and in targeted local runs, not necessarily every `go test`. A clean `-race` run is not a proof of correctness, but a failing one is always a real bug.
+
+## Goroutine-leak detection
+
+A test that starts a goroutine and returns before it exits leaks it. Two approaches:
+
+- Inside a synctest bubble, a leak surfaces naturally: the bubble blocks waiting for the stray goroutine, and the fake clock cannot advance, so the test hangs or the leak is obvious.
+- Outside synctest, use `go.uber.org/goleak`:
+
+```go
+func TestMain(m *testing.M) {
+	goleak.VerifyTestMain(m)
+}
+```
+
+This fails the run if any unexpected goroutine survives the suite. Prefer `t.Cleanup` to cancel contexts and `synctest.Wait` to drain workers so you never leak in the first place.
+
+## Migration: GOEXPERIMENT → GA
+
+- **Go 1.24**: `testing/synctest` shipped behind `GOEXPERIMENT=synctest`, exposing only `synctest.Run(func(){...})`.
+- **Go 1.25**: GA, no build flag. The preferred entry point is `synctest.Test(t, func(t *testing.T){...})`, which takes `*testing.T` and integrates with subtests and cleanup.
+- **Go 1.26**: `synctest.Run` is deprecated. Migrate `Run(func(){...})` calls to `Test(t, func(t *testing.T){...})` and use the passed `t` for assertions instead of capturing the outer one.
+
+If you see `GOEXPERIMENT=synctest` in a Makefile or CI config and the module is on 1.25+, delete the flag.

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

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# verify.sh — read-only checks for Go test artifacts.
+# Finds the nearest Go module at/under the target dir, then runs gofmt -l,
+# go vet, and go test. No module => clean skip, exit 0 (no false failure).
+#
+# Usage: scripts/verify.sh [target-dir]   (defaults to current directory)
+set -euo pipefail
+
+target="${1:-.}"
+
+if [ ! -d "$target" ]; then
+  echo "verify: target '$target' is not a directory; nothing to check." >&2
+  exit 0
+fi
+
+# Locate a go.mod: prefer one directly in target, else search downward.
+modfile=""
+if [ -f "$target/go.mod" ]; then
+  modfile="$target/go.mod"
+else
+  modfile="$(find "$target" -name go.mod -type f -not -path '*/vendor/*' 2>/dev/null | head -n1 || true)"
+fi
+
+if [ -z "$modfile" ]; then
+  echo "verify: no go.mod found under '$target' — skipping (nothing to verify)."
+  exit 0
+fi
+
+if ! command -v go >/dev/null 2>&1; then
+  echo "verify: 'go' toolchain not on PATH — skipping." >&2
+  exit 0
+fi
+
+moddir="$(dirname "$modfile")"
+echo "verify: Go module at $moddir"
+
+status=0
+
+# 1. Formatting — gofmt -l lists files that are NOT formatted; empty output is good.
+unformatted="$(gofmt -l "$moddir" 2>/dev/null || true)"
+if [ -n "$unformatted" ]; then
+  echo "FAIL gofmt: the following files are not gofmt-clean:" >&2
+  echo "$unformatted" >&2
+  status=1
+else
+  echo "ok   gofmt: all files formatted"
+fi
+
+# 2. Vet — static checks. Run from the module dir.
+if ( cd "$moddir" && go vet ./... ); then
+  echo "ok   go vet"
+else
+  echo "FAIL go vet" >&2
+  status=1
+fi
+
+# 3. Tests — try -race first; fall back if the platform lacks the race detector.
+if ( cd "$moddir" && go test ./... -count=1 -race ) 2>/dev/null; then
+  echo "ok   go test (-race)"
+elif ( cd "$moddir" && go test ./... -count=1 ); then
+  echo "ok   go test (no race detector available)"
+else
+  echo "FAIL go test" >&2
+  status=1
+fi
+
+if [ "$status" -eq 0 ]; then
+  echo "verify: PASS"
+else
+  echo "verify: FAIL" >&2
+fi
+exit "$status"

package/skills/testing-py/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: testing-py
+description: "Use when writing or fixing Python tests with pytest and the suite is green but bugs still ship, when you must mock an external dependency and aren't sure where to patch, when coverage looks high but catches nothing, or when adding property-based tests for parsers/encoders/invariants. Triggers: 'write pytest tests', 'how do I mock this call', 'why does my mock pass when the code is broken', 'coverage is high but useless', 'patch where it's used', 'add Hypothesis property tests', 'fixture scope leaking state between tests', 'tests en Python', 'cómo mockeo esta llamada', 'la cobertura no detecta nada', 'tests de propietats'. NOT browser end-to-end flows (that is e2e-testing), NOT JS/TS unit tests (that is testing-web), NOT Go tests (that is testing-go)."
+tags: [pytest, python, testing, coverage, hypothesis, mocking, fixtures, property-based]
+recommends: [python, code-review, github-actions, e2e-testing]
+origin: risco
+---
+
+# Testing Python
+
+A green suite is not a tested suite. Most Python suites pass while shipping bugs because they lie in four predictable ways, and your job is to refuse each lie:
+
+1. **Line-only coverage** reports 95% while every `else` and `except` arm is unvisited.
+2. **Mocks patched at the wrong place** never apply, so the test runs the real code or asserts nothing.
+3. **autospec-less mocks** pass even when you typo a method name or change a signature — a false green.
+4. **autouse fixtures** mutate hidden global state, so tests pass alone and fail in CI order.
+
+The posture, non-negotiable: pytest 9 strict markers and strict config on, **branch coverage on**, `autospec=` on every mock, and Hypothesis property tests for any pure logic with an invariant. Assert on behavior, never on a mock's internals.
+
+Versions you are on (2026-06): pytest **9.0.2**, coverage.py **7.14.1**, pytest-cov **7.x** (needs coverage ≥ 7.10.6), Hypothesis **6.155.x**.
+
+## Which test do I need?
+
+Pick the cheapest test that still catches the bug.
+
+| Situation | Test type | Reach for |
+|---|---|---|
+| Pure function, many input shapes, an invariant holds | property test | Hypothesis `@given(...)` |
+| Same logic, a small fixed matrix of inputs/outputs | parametrized test | `@pytest.mark.parametrize` |
+| Code calls an external boundary (HTTP, DB, SDK, clock) | unit test + mock **at the boundary** | `autospec=True` / `mocker` |
+| Several real components must work together | integration test | real objects, fixtures, `tmp_path` |
+| One test needs an env var / attr swapped and reverted | inline patch | `monkeypatch` |
+
+Default to property + parametrized for logic; reserve mocks for boundaries you do not own.
+
+## Layout and config
+
+`tests/` mirrors the package tree. Put each fixture in the **nearest** `conftest.py`, not always the root one — proximity is documentation. Drive everything from `pyproject.toml`:
+
+```toml
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--strict-markers --strict-config --cov=mypkg --cov-branch --cov-report=term-missing --cov-fail-under=85"
+markers = [
+  "slow: deselect with -m 'not slow'",
+  "integration: touches a real boundary",
+]
+
+[tool.coverage.run]
+branch = true            # measure both arms of every conditional, not just lines
+source = ["mypkg"]
+
+[tool.coverage.report]
+show_missing = true
+fail_under = 85
+exclude_lines = [
+  "if TYPE_CHECKING:",
+  "raise NotImplementedError",
+  "def __repr__",
+  "pragma: no cover",
+]
+```
+
+`--strict-markers` turns a typo'd `@pytest.mark.slwo` into an error instead of a silently-skipped test. `--strict-config` rejects unknown config keys. pytest 9 also exposes `strict_markers`, `strict_config`, `strict_xfail`, and `strict_parametrization_ids` as config aliases — treat strict as the default, not an upgrade.
+
+## Fixtures
+
+Scope is a contract about reuse and isolation. Default to `function` and widen only when setup is genuinely expensive and the object is genuinely immutable.
+
+| Scope | Recreated | Use when |
+|---|---|---|
+| `function` (default) | every test | anything mutable — the safe default |
+| `class` | per test class | a group sharing read-only setup |
+| `module` | once per file | costly read-only object (a parsed config) |
+| `package` | once per dir | shared fixture for a sub-tree |
+| `session` | once per run | a process-wide resource you never mutate |
+
+A `yield` fixture's pre-yield code is setup, post-yield is teardown — **and teardown runs even when the test fails**, so it is where cleanup belongs.
+
+```python
+# Bad: everything in the root conftest.py, plus a hidden autouse reset.
+# Nobody can trace why a test depends on the DB, and the reset masks state leaks.
+@pytest.fixture(autouse=True)
+def reset_db():
+    db.truncate_all()
+
+# Good: scoped fixture in tests/api/conftest.py, explicit, documented.
+# The docstring shows up in `pytest --fixtures`, so it is discoverable.
+@pytest.fixture
+def api_client(tmp_path):
+    """An isolated API client backed by a throwaway sqlite file."""
+    client = ApiClient(db_path=tmp_path / "test.db")
+    yield client
+    client.close()  # runs even if the test raises
+```
+
+Parametrize a fixture when several tests should each run against multiple backings:
+
+```python
+@pytest.fixture(params=["sqlite", "memory"])
+def store(request):
+    return make_store(request.param)  # every test using `store` runs twice
+```
+
+Use `autouse=True` only for something every test in scope truly needs (a frozen clock, a captured log). A hidden global dependency makes a failure impossible to read.
+
+## Mocking
+
+**Patch the name where it is looked up, not where it is defined.** This is the single most common mocking bug. If `mymod` does `from httpx import get`, then `get` now lives at `mymod.get`; patching `httpx.get` changes a name `mymod` no longer reads, so the mock never applies and the test silently hits the network.
+
+```python
+# Bad: patches the definition site; mymod already bound its own `get` at import.
+with patch("httpx.get") as m:        # no effect on mymod.get
+    result = mymod.fetch(url)
+
+# Good: patch the name in the module under test, and autospec it.
+with patch("mymod.get", autospec=True) as m:
+    m.return_value.json.return_value = {"ok": True}
+    result = mymod.fetch(url)
+    m.assert_called_once_with(url, timeout=5)
+```
+
+**`autospec=True` is mandatory.** Without it a typo'd method or a wrong arg count still passes — the mock invents any attribute you touch. With autospec the mock enforces the real object's signature, so a refactor that renames a method or drops a parameter fails the test like it should. Use `create_autospec(obj)` when you need a standalone fake of a class or callable.
+
+Choosing the swap tool:
+
+- **`monkeypatch`** (built into pytest, no install): env vars, attributes, `chdir`. `monkeypatch.setenv` / `delenv` / `setattr` / `chdir` auto-revert after the test. Use it for "swap one thing for this test."
+- **`mocker`** (`pytest-mock`): `unittest.mock` with automatic undo and call tracking. Less boilerplate for `return_value` / `side_effect` and `assert_called_*`. Use it for "fake a callable and inspect how it was called."
+
+Both are correct; pick by what you are swapping. Faking time, HTTP, DB, the filesystem, `side_effect`, asserting calls, and `AsyncMock` for async code live in **[references/mocking.md](references/mocking.md)**.
+
+## Coverage that means something
+
+Run it with branch coverage and a floor:
+
+```bash
+pytest --cov=mypkg --cov-branch --cov-report=term-missing --cov-fail-under=85
+```
+
+Line coverage lies because executing a line is not the same as testing its outcomes. A function with `if x: a() else: b()` reaches 100% line coverage from a single test that only takes the `if` arm — the `else` ships untested. `--cov-branch` (or `branch = true`) forces both arms to be exercised, which is exactly where happy-path-only suites leak bugs. `term-missing` prints the unhit line and branch numbers so you know what to write next. Exclude only code that is correctly never run by tests (`if TYPE_CHECKING:`, `raise NotImplementedError`, `__repr__`) — never exclude a branch just to make the number go up.
+
+## Property testing
+
+Reach for Hypothesis when a fixed example matrix can't cover the input space: parsers, serializers, encoders, math, anything with an invariant. You assert a *property* that must hold for all inputs and let Hypothesis hunt counterexamples.
+
+```python
+from hypothesis import given, assume, strategies as st
+
+@given(st.text())
+def test_encode_decode_roundtrip(s):
+    assume("\x00" not in s)            # skip inputs the encoder legitimately rejects
+    assert decode(encode(s)) == s      # roundtrip: the core property
+```
+
+The property shapes worth knowing: **roundtrip** (`decode(encode(x)) == x`), **idempotence** (`f(f(x)) == f(x)`), and **invariant** (a sorted list stays the same length and is ordered). On failure Hypothesis **shrinks** to the simplest failing input and stores it in the `.hypothesis/` example DB, so the next run replays that exact case until you fix it — commit the DB or persist it in CI to keep regressions pinned. Use `assume()` to discard inputs that aren't meant to be valid, and bound slow strategies so the deadline doesn't flake. Strategy catalog, composite strategies, settings/profiles, `@example`, and stateful testing live in **[references/property-testing.md](references/property-testing.md)**.
+
+## Anti-patterns
+
+| Anti-pattern | Why it is wrong | Do instead |
+|---|---|---|
+| `patch(...)` without `autospec=`/`spec=` | false green on a renamed or mis-called method | always `autospec=True` (or `create_autospec`) |
+| Patching the definition site (`httpx.get`) | the mock never applies to the module under test | patch the use site (`mymod.get`) |
+| `time.sleep(...)` to "fix" flakiness | slow and still flaky | fake the clock / poll on a condition |
+| Asserting on `mock._mock_calls` or private attrs | test breaks on refactor, not on bugs | assert on the return value / observable behavior |
+| Session-scoped mutable fixture with no reset | state leaks across tests, order-dependent failures | `function` scope, or explicit teardown |
+| `--cov` without `--cov-branch` | 100% lines while branches are untested | always `--cov-branch` / `branch = true` |
+| One giant test asserting 12 things | first failure hides the rest; can't tell what broke | one behavior per test, parametrize the matrix |
+| `@given` with no `assume`/bounds on slow code | deadline timeouts, flaky property tests | bound the strategy, raise/disable deadline deliberately |
+| `assert True` or bare `pytest.skip()` | a test that can never fail or never runs | assert a real outcome; `skip(reason=...)` |
+
+## Verify
+
+Before declaring a suite done, run the static gate over the test tree. It flags the skill's own banned patterns — mocks without `autospec`/`spec`, `--cov` without `--cov-branch`, `time.sleep` in tests, and no-op tests:
+
+```bash
+scripts/verify.sh tests/
+```
+
+It is read-only, prints `file:line` for each hit, exits non-zero on any finding, and exits 0 on a clean or empty tree. A clean run is necessary, not sufficient — it cannot tell you the branches are actually tested, only that the obvious lies are absent.

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

@@ -0,0 +1,5 @@
+# Evals — testing-py
+
+`cases.yaml` is the behavioral spec for this skill. `should_trigger` lists prompts the skill must own (pytest authoring, the false-green mock symptom, branch-coverage gaps, Hypothesis properties, fixture state leaks, plus Spanish and Catalan phrasings). `should_not_trigger` lists nearby prompts that must route to a real sibling (`e2e-testing`, `testing-web`, `testing-go`, `python`, `code-review`) so the boundary stays sharp. `capability` is a single end-to-end scenario with a `must_include` rubric covering the load-bearing claims: patch-at-the-use-site, autospec, branch coverage, behavior-not-internals assertions, the strict posture, and an error-path test.
+
+There is no automated runner here. To evaluate manually, give a fresh agent each `should_trigger` / `should_not_trigger` prompt and confirm it engages or routes as the `why`/`route_to` says; then run the `capability` scenario and grade the output against every `must_include` line. To check the shipped gate, run `scripts/verify.sh path/to/tests` — it is read-only, exits 0 on a clean or empty tree, and prints `file:line` for any banned pattern.

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

@@ -0,0 +1,44 @@
+skill: testing-py
+
+should_trigger:
+  - prompt: "Write a pytest suite for this payment parser, with fixtures and a coverage gate."
+    why: "Core duty: authoring a real pytest suite with fixtures and meaningful coverage."
+  - prompt: "My mock passes but the real function is broken — why doesn't the test catch it?"
+    why: "Non-obvious: the false-green symptom of patch-at-the-wrong-place and missing autospec, without the user naming either."
+  - prompt: "Coverage says 95% but we keep shipping bugs in the error path."
+    why: "Branch-coverage gap — line coverage lies about the unhit except/else arm; this skill's posture is --cov-branch."
+  - prompt: "Add property-based tests for our base64 encoder/decoder."
+    why: "Hypothesis roundtrip property over an input space a fixed matrix can't cover."
+  - prompt: "Mis tests comparten estado entre ejecuciones y fallan aleatoriamente."
+    why: "Spanish + non-obvious: fixture scope / autouse state-leak diagnosis described by symptom, not tool."
+  - prompt: "Com mockejo la crida HTTP a Stripe en aquest mòdul de Python?"
+    why: "Catalan: mocking a boundary in a Python module — patch-where-used + autospec the client."
+
+should_not_trigger:
+  - prompt: "Write Playwright tests for the checkout flow across three pages."
+    route_to: "e2e-testing"
+    why: "Real browser, multi-page user flow — that is end-to-end, not pytest unit/integration."
+  - prompt: "Add Vitest tests for my React hook with React Testing Library."
+    route_to: "testing-web"
+    why: "JS/TS unit tests in the frontend toolchain, not Python/pytest."
+  - prompt: "Write table-driven tests for my Go service using testify."
+    route_to: "testing-go"
+    why: "Non-Python: Go's testing package and testify are owned by testing-go."
+  - prompt: "Refactor this Python module to be more idiomatic and add type hints."
+    route_to: "python"
+    why: "Language idiom and typing, not test technique; python carries the baseline."
+  - prompt: "Review my PR for correctness bugs across the diff."
+    route_to: "code-review"
+    why: "General correctness review of a diff, not authoring or fixing a test suite."
+
+capability:
+  - scenario: "A module does `from httpx import Client` and calls `Client().get(url)`, raising on a
+      non-200 status. Write a unit test that mocks the HTTP call correctly, plus a coverage command
+      that proves the untested error branch is caught. Include at least one error-path test."
+    must_include:
+      - "patches the name in the module under test (the use site, e.g. mymod.Client), NOT httpx.Client globally — or injects the client as a dependency"
+      - "uses autospec=True / create_autospec so a wrong signature or typo'd method fails the test"
+      - "the coverage command includes --cov-branch (or the config sets branch = true)"
+      - "asserts on the return value / observable behavior, not on mock private internals like _mock_calls"
+      - "mentions a strict posture: --strict-markers and/or --strict-config (or the pytest 9 strict_* aliases)"
+      - "at least one negative/error-path test (e.g. raises on non-200), not only the happy path"

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

@@ -0,0 +1,141 @@
+# Mocking reference
+
+Depth behind the SKILL.md mocking section: the where-to-patch worked example, the autospec/spec/spec_set ladder, side effects and call assertions, and faking time/HTTP/DB/filesystem/async.
+
+## Where to patch — a full worked example
+
+The rule: **patch the name the module under test looks up at call time**, not the name in the library where it was defined.
+
+```python
+# mymod.py
+from httpx import Client          # `Client` is now bound as mymod.Client
+
+def fetch(url: str) -> dict:
+    with Client(timeout=5) as c:
+        return c.get(url).raise_for_status().json()
+```
+
+```python
+# test_mymod.py
+from unittest.mock import patch, create_autospec
+import httpx
+import mymod
+
+# Bad: patches httpx.Client. mymod already bound its own `Client` at import time,
+# so this changes a name mymod never reads again. The real client runs. Test hits the network.
+def test_fetch_bad():
+    with patch("httpx.Client") as m:        # NO EFFECT on mymod.Client
+        mymod.fetch("https://x")            # makes a real request
+
+# Good: patch the name in mymod, autospec'd so the fake matches httpx.Client's real API.
+def test_fetch_good():
+    fake_client = create_autospec(httpx.Client, instance=True)
+    resp = create_autospec(httpx.Response, instance=True)
+    resp.raise_for_status.return_value = resp
+    resp.json.return_value = {"ok": True}
+    fake_client.get.return_value = resp
+    fake_client.__enter__.return_value = fake_client   # support `with Client(...)`
+
+    with patch("mymod.Client", return_value=fake_client):
+        assert mymod.fetch("https://x") == {"ok": True}   # assert on behavior
+        fake_client.get.assert_called_once_with("https://x")
+```
+
+The cleaner alternative is to **not patch at all**: pass the client in as an argument (dependency injection) and hand the test a fake. Patching is the tool when you cannot change the signature.
+
+## autospec vs spec vs spec_set
+
+| Form | What it enforces | Use when |
+|---|---|---|
+| `Mock()` (no spec) | nothing — any attribute exists | almost never; this is the false-green factory |
+| `Mock(spec=Klass)` | attribute names match `Klass`, signatures **not** checked on the instance | a quick guard against typo'd attributes |
+| `create_autospec(Klass)` / `patch(..., autospec=True)` | attribute names **and** call signatures recursively | the default for any non-trivial fake |
+| `Mock(spec_set=Klass)` | like spec, and **setting** an unknown attr also raises | locking a fake so the test can't drift |
+
+Autospec is recursive: `create_autospec(Client).get.return_value.json` is itself signature-checked. The cost is that you configure return values explicitly, which is the point — the fake can't quietly diverge from the real object.
+
+## return_value, side_effect, asserting calls
+
+```python
+m.return_value = 42                      # every call returns 42
+m.side_effect = ConnectionError("down")  # every call raises
+m.side_effect = [1, 2, 3]                # successive calls return 1, then 2, then 3
+m.side_effect = lambda x: x * 2          # compute from args
+
+m.assert_called_once_with(url, timeout=5)   # exact args, exactly once
+m.assert_not_called()
+assert m.call_count == 2
+args, kwargs = m.call_args                  # inspect the last call when needed
+```
+
+Assert on the **return value or observable effect** of the code under test, plus the *contract* with the boundary (it was called with the right URL). Never assert on `m._mock_children`, `m._mock_calls` internals, or other private attributes — those break on refactors that didn't change behavior.
+
+## Faking time
+
+Do not `time.sleep`. Inject or patch the clock.
+
+```python
+# Best: the code reads a clock you can swap.
+def expired(token, *, now=time.time):
+    return token.exp < now()
+
+def test_expired(monkeypatch):
+    assert expired(tok, now=lambda: 10_000)   # no patching needed at all
+```
+
+For pervasive `datetime.now()` use `freezegun`:
+
+```python
+from freezegun import freeze_time
+
+@freeze_time("2026-06-02T12:00:00Z")
+def test_stamp():
+    assert record().created_at.year == 2026
+```
+
+## Faking HTTP
+
+Two clean options:
+
+- **`respx`** (for `httpx`) / **`responses`** (for `requests`): intercept at the transport layer, so your real client code runs and you assert on the request.
+
+```python
+import respx, httpx
+@respx.mock
+def test_fetch():
+    route = respx.get("https://x").mock(return_value=httpx.Response(200, json={"ok": True}))
+    assert mymod.fetch("https://x") == {"ok": True}
+    assert route.called
+```
+
+- **autospec the client** (shown above) when you want zero network layer at all.
+
+Prefer transport interception when you care that the right request was built; prefer autospec when the client is an injected dependency.
+
+## Faking the DB and filesystem
+
+- **Filesystem:** use the built-in `tmp_path` (a `pathlib.Path` to a unique temp dir) and `tmp_path_factory` for session scope. Never write to the repo or `/tmp` by hand.
+- **DB:** prefer a real in-memory or `tmp_path` sqlite over a mock — it tests your SQL, not your mock of SQL. Mock the DB only when the boundary is a remote service you don't run in CI.
+
+```python
+def test_store(tmp_path):
+    store = Store(tmp_path / "t.db")   # real sqlite, isolated, auto-cleaned
+    store.put("k", "v")
+    assert store.get("k") == "v"
+```
+
+## Async code
+
+Use `AsyncMock` (it returns awaitables) and run under `pytest.mark.asyncio` or `anyio`:
+
+```python
+from unittest.mock import AsyncMock, patch
+
+async def test_afetch():
+    with patch("mymod.aget", new_callable=AsyncMock) as m:
+        m.return_value = {"ok": True}
+        assert await mymod.afetch("https://x") == {"ok": True}
+        m.assert_awaited_once_with("https://x")   # note: awaited, not called
+```
+
+`create_autospec` of an async function yields an `AsyncMock` automatically, so autospec still applies.