@dsalazardev/ai-hub-cli 0.0.0-stage → 0.2.0

package/skills/shared/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/shared/testing-py/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: testing-py
+description: "Use when writing or fixing Python tests with pytest — especially when the suite is green but bugs still ship, when you must decide where to patch a mocked dependency, when coverage is high but catches nothing, when fixture scope leaks state, or when adding property-based tests for parsers and invariants. 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: ai-hub
+---
+
+# 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.
+
+## Mutation: does the suite actually notice?
+
+Branch coverage tells you which code ran. It cannot tell you whether any test would have **noticed** if that code were wrong — and a test with no assertion, or an assertion that cannot fail, raises coverage without detecting anything. Mutation testing closes that gap by planting bugs on purpose: if the suite still passes, the mutant *survived* and you have found a test that asserts nothing.
+
+```bash
+# pyproject.toml → [tool.mutmut]  source_paths = ["src/"]
+mutmut run                    # whole source tree
+mutmut run "mypkg.core*"      # scope it — this is the normal case
+mutmut results                # what survived
+```
+
+Reach for the real tool, not a hand-written mutant list: mutmut generates mutants from the syntax tree, so it cannot apply one to code that moved and cannot report one it never ran.
+
+- **Scale it to risk.** This is not a default toll — it is minutes-to-hours on a real tree. Run it where a bug is expensive (money, auth, data loss, concurrency, a public API) or where a green suite keeps shipping bugs anyway. Always scope to the code you changed.
+- **A survivor is not automatically a failure.** Some mutants are semantically equivalent to the original and cannot be killed. Classify those with the reason ("equivalent: both branches return the same value for every reachable input"). Never add a test that asserts non-behaviour just to kill one — that is the same gaming that coverage-chasing is.
+- **A survivor that is a real bug gets a test, not an excuse.** Write the assertion that kills it, then rerun.
+- **If you hand-roll a runner, prove it executed every mutant.** Clear `__pycache__` and set `PYTHONDONTWRITEBYTECODE` per mutant: two same-size mutants written in the same second can share a bytecode cache, and the runner then reports a kill for code it never ran. That defect can only ever *inflate* the score, so it will never show up as a red run — which is why the proof has to be built in rather than assumed.
+
+## 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/shared/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/shared/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/shared/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.

package/skills/shared/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.