@coralai/sps-cli 0.41.2 → 0.43.0

package/skills/python/references/testing.md

@@ -0,0 +1,269 @@
+# Python Testing
+
+pytest-specific patterns. For TDD cycle and general test-driven methodology, see the `coding-standards` skill (`references/tdd.md`).
+
+## Coverage targets
+
+| Layer | Target | Rationale |
+|---|---|---|
+| Unit (pure logic) | ≥ 90% | Fast, cheap, high signal |
+| Integration | ≥ 70% | Covers real dependencies (DB, cache, HTTP) |
+| E2E | Key flows only | Slow, brittle — don't overinvest |
+
+Use `pytest-cov`:
+```bash
+pytest --cov=myapp --cov-report=term-missing --cov-fail-under=80
+```
+
+## pytest structure
+
+File and function naming:
+- Files: `test_*.py` or `*_test.py`
+- Test functions: `test_*`
+- Classes (optional grouping): `class TestFoo`
+
+```python
+# test_user_service.py
+def test_create_user_returns_user_object():
+    service = UserService(db=FakeDB())
+    user = service.create(name="Alice", email="a@x.com")
+    assert user.name == "Alice"
+    assert user.id is not None
+
+def test_create_user_rejects_empty_email():
+    service = UserService(db=FakeDB())
+    with pytest.raises(ValidationError, match="email"):
+        service.create(name="Alice", email="")
+```
+
+## Assertions: prefer plain `assert`
+
+pytest rewrites `assert` to show helpful diffs. Never use `self.assertEqual` (that's unittest).
+
+```python
+# Good
+assert result == expected
+assert user in users
+assert "error" in str(caplog.records[0])
+assert 0 < percent <= 100
+
+# Bad
+self.assertEqual(result, expected)   # unittest style — ugly, no advantage
+assertTrue(result == expected)        # ditto
+```
+
+## Fixtures
+
+Use fixtures for setup/teardown, not manual init in every test.
+
+```python
+import pytest
+
+@pytest.fixture
+def user_service():
+    service = UserService(db=FakeDB())
+    yield service
+    service.cleanup()
+
+def test_create_user(user_service):
+    user = user_service.create(name="A", email="a@x.com")
+    assert user.id
+```
+
+Scope levels (reuse across tests):
+- `function` (default): new instance per test
+- `class`: shared within a class
+- `module`: shared within a file
+- `session`: shared across entire run
+
+```python
+@pytest.fixture(scope="session")
+def db_connection():
+    conn = connect_to_test_db()
+    yield conn
+    conn.close()
+```
+
+**Shared fixtures**: put in `conftest.py` in the test directory.
+
+## Parametrization
+
+Same test logic, multiple inputs — one line per case.
+
+```python
+@pytest.mark.parametrize("a,b,expected", [
+    (1, 2, 3),
+    (0, 0, 0),
+    (-1, 1, 0),
+    (100, 200, 300),
+])
+def test_add(a, b, expected):
+    assert add(a, b) == expected
+
+# With IDs for readable output
+@pytest.mark.parametrize("input,expected", [
+    ("hello", 5),
+    ("", 0),
+    ("a b c", 5),
+], ids=["simple", "empty", "with_spaces"])
+def test_len(input, expected):
+    assert len(input) == expected
+```
+
+## Mocking
+
+Use `pytest-mock` (`mocker` fixture) or `unittest.mock`.
+
+```python
+def test_sends_email_on_signup(mocker):
+    mock_send = mocker.patch('myapp.email.send')
+    service.signup(email="a@x.com")
+    mock_send.assert_called_once_with(to="a@x.com", template="welcome")
+
+def test_handles_api_timeout(mocker):
+    mocker.patch('myapp.http.get', side_effect=TimeoutError)
+    result = service.fetch_data()
+    assert result.error == "timeout"
+```
+
+### Mock rules
+
+| Rule | Why |
+|---|---|
+| Patch where it's USED, not where it's DEFINED | `patch('myapp.service.http.get')` not `patch('requests.get')` |
+| Use `autospec=True` for stricter signatures | Catches "mock called with wrong args" |
+| Don't over-mock | If you mock 8 things to test 10 lines, something's wrong |
+| Prefer fakes over mocks | A `FakeDB` that actually works is easier to maintain |
+
+## Markers
+
+Mark tests for selective running.
+
+```python
+@pytest.mark.slow
+def test_full_import_pipeline():
+    ...  # takes 30s
+
+@pytest.mark.integration
+def test_with_real_db():
+    ...
+
+# Run only fast tests:
+# pytest -m "not slow"
+
+# Run only integration:
+# pytest -m integration
+```
+
+Register markers in `pyproject.toml` to avoid warnings:
+```toml
+[tool.pytest.ini_options]
+markers = [
+    "slow: tests taking more than 1 second",
+    "integration: tests requiring external services",
+]
+```
+
+## Testing async code
+
+Use `pytest-asyncio`.
+
+```python
+import pytest
+
+@pytest.mark.asyncio
+async def test_fetch_url():
+    result = await fetch("https://example.com")
+    assert result.status == 200
+```
+
+For the async language-level patterns being tested, see `references/async.md`.
+
+## Property-based testing with Hypothesis
+
+When the input space is large (parsers, serializers, invariants), `hypothesis` generates inputs automatically and shrinks failing cases.
+
+```python
+from hypothesis import given, strategies as st
+
+@given(st.lists(st.integers()))
+def test_sort_is_idempotent(xs):
+    assert sorted(sorted(xs)) == sorted(xs)
+
+@given(st.text())
+def test_roundtrip(s):
+    assert decode(encode(s)) == s
+
+# Composite strategy
+user_strategy = st.builds(
+    User,
+    id=st.uuids().map(str),
+    age=st.integers(min_value=0, max_value=150),
+    email=st.emails(),
+)
+
+@given(user_strategy)
+def test_user_serializes(u):
+    assert User.from_json(u.to_json()) == u
+```
+
+Use it where example-based tests are weak: round-trips, invariants, mathematical properties, parsers.
+
+## Testing exceptions
+
+```python
+def test_raises_on_invalid_input():
+    with pytest.raises(ValidationError, match="email required"):
+        validate_user({})
+
+def test_exception_chain():
+    with pytest.raises(ConfigError) as exc_info:
+        load_config("/nonexistent")
+    assert isinstance(exc_info.value.__cause__, FileNotFoundError)
+```
+
+## Anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| Shared mutable state across tests | Use fixtures with function scope |
+| `if __name__ == "__main__": pytest.main()` in tests | Run via `pytest` CLI |
+| Print statements for debugging | Use `caplog` fixture or `-s` flag |
+| Testing private methods | Test via public API; if you can't, refactor |
+| One big `test_everything()` | Split: one behavior per test |
+| Skipping tests without comment | `@pytest.mark.skip("reason")` always with reason |
+
+## Test organization
+
+```
+project/
+├── src/myapp/
+│   ├── services/
+│   │   └── user_service.py
+│   └── models/
+│       └── user.py
+└── tests/
+    ├── conftest.py              # shared fixtures
+    ├── unit/
+    │   ├── test_user_service.py
+    │   └── test_user_model.py
+    ├── integration/
+    │   └── test_user_api.py
+    └── e2e/
+        └── test_signup_flow.py
+```
+
+## CI setup
+
+```toml
+# pyproject.toml
+[tool.pytest.ini_options]
+addopts = [
+    "--cov=myapp",
+    "--cov-report=term-missing",
+    "--cov-fail-under=80",
+    "--strict-markers",
+    "-ra",             # show summary for all non-pass outcomes
+]
+testpaths = ["tests"]
+```

package/skills/python/references/typing.md

@@ -0,0 +1,292 @@
+# Python Type Hints
+
+Modern typing for public APIs. Python 3.9+ syntax preferred.
+
+## Baseline: type all public APIs
+
+Every public function, method, class attribute gets a type hint. Private helpers can skip if the type is obvious from context.
+
+```python
+def process_user(
+    user_id: str,
+    data: dict[str, Any],
+    active: bool = True,
+) -> User | None:
+    """Update a user. Returns the updated User or None if inactive."""
+    if not active:
+        return None
+    return User(user_id, data)
+```
+
+## Modern syntax (Python 3.9+)
+
+Use built-in generics, drop `typing.List` / `typing.Dict` imports.
+
+```python
+# Python 3.9+  ✅
+def process(items: list[str]) -> dict[str, int]:
+    return {item: len(item) for item in items}
+
+# Python 3.8 and earlier — legacy only
+from typing import List, Dict
+def process(items: List[str]) -> Dict[str, int]: ...
+```
+
+## Optional / Union
+
+Python 3.10+: use `|` instead of `Union` / `Optional`.
+
+```python
+# Python 3.10+  ✅
+def find(id: str) -> User | None: ...
+def parse(raw: str | bytes) -> dict: ...
+
+# Python 3.9 and earlier
+from typing import Optional, Union
+def find(id: str) -> Optional[User]: ...
+def parse(raw: Union[str, bytes]) -> dict: ...
+```
+
+## Type aliases
+
+Name complex types. Makes signatures self-documenting.
+
+```python
+from typing import TypeAlias
+
+JSON: TypeAlias = dict[str, Any] | list[Any] | str | int | float | bool | None
+UserId: TypeAlias = str
+RequestHeaders: TypeAlias = dict[str, str]
+
+def fetch(user_id: UserId, headers: RequestHeaders) -> JSON: ...
+```
+
+## Generics
+
+For functions that work over any type while preserving relationships.
+
+### Python 3.12+: PEP 695 type parameter syntax
+
+Inline declaration, no `TypeVar` import needed.
+
+```python
+# Generic function
+def first[T](items: list[T]) -> T | None:
+    return items[0] if items else None
+
+# Bounded type parameter
+def clamp[N: (int, float)](value: N, lo: N, hi: N) -> N:
+    return max(lo, min(value, hi))
+
+# Generic class
+class Stack[T]:
+    def __init__(self) -> None:
+        self._items: list[T] = []
+    def push(self, item: T) -> None: self._items.append(item)
+    def pop(self) -> T: return self._items.pop()
+
+# Type alias (PEP 695)
+type JSON = dict[str, "JSON"] | list["JSON"] | str | int | float | bool | None
+type UserId = str
+```
+
+### Python 3.11 and earlier: `TypeVar`
+
+```python
+from typing import TypeVar
+
+T = TypeVar('T')
+
+def first(items: list[T]) -> T | None:
+    return items[0] if items else None
+
+N = TypeVar('N', bound=int | float)
+
+def clamp(value: N, lo: N, hi: N) -> N:
+    return max(lo, min(value, hi))
+```
+
+## `Self` type (Python 3.11+)
+
+Reference the enclosing class without string forward references.
+
+```python
+from typing import Self
+
+class QueryBuilder:
+    def where(self, **kwargs) -> Self:
+        self._filters.update(kwargs)
+        return self
+    def limit(self, n: int) -> Self:
+        self._limit = n
+        return self
+
+# Subclass chaining preserves the subclass type
+class UserQuery(QueryBuilder):
+    def active(self) -> Self:
+        return self.where(active=True)
+
+UserQuery().active().limit(10)  # still typed as UserQuery, not QueryBuilder
+```
+
+## `@override` decorator (Python 3.12+)
+
+Catch accidental method-name drift when the parent renames.
+
+```python
+from typing import override
+
+class Base:
+    def process(self) -> None: ...
+
+class Derived(Base):
+    @override
+    def process(self) -> None: ...   # type-checked: errors if Base.process is renamed or gone
+
+    @override
+    def procces(self) -> None: ...   # ❌ mypy/pyright error: not overriding anything
+```
+
+## `ParamSpec` — typed decorators
+
+Preserve the signature of the wrapped function.
+
+```python
+from typing import ParamSpec, TypeVar, Callable
+from functools import wraps
+
+P = ParamSpec('P')
+R = TypeVar('R')
+
+def timed(func: Callable[P, R]) -> Callable[P, R]:
+    @wraps(func)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        return func(*args, **kwargs)
+    return wrapper
+
+# Python 3.12+ syntax
+def timed[**P, R](func: Callable[P, R]) -> Callable[P, R]:
+    ...
+```
+
+## Protocols — structural typing
+
+Interface without inheritance. Works like Go interfaces or TypeScript interfaces.
+
+```python
+from typing import Protocol
+
+class Renderable(Protocol):
+    def render(self) -> str: ...
+
+# Any class with a matching .render() method satisfies Renderable —
+# no need to inherit from it.
+class Card:
+    def render(self) -> str:
+        return f"Card: {self.title}"
+
+def render_all(items: list[Renderable]) -> str:
+    return "\n".join(item.render() for item in items)
+
+# Works without any declaration:
+render_all([Card("A"), Card("B")])
+```
+
+## Literal types
+
+Constrain values to a fixed set.
+
+```python
+from typing import Literal
+
+LogLevel = Literal['debug', 'info', 'warning', 'error', 'critical']
+
+def log(msg: str, level: LogLevel = 'info') -> None: ...
+
+log("x", "info")       # ✅
+log("x", "verbose")    # ❌ type error
+```
+
+## TypedDict — structured dicts
+
+When you're stuck with dict but want type safety.
+
+```python
+from typing import TypedDict
+
+class UserDict(TypedDict):
+    id: str
+    name: str
+    email: str
+    active: bool
+
+def process(user: UserDict) -> None:
+    print(user['name'])  # type-checked as str
+```
+
+## Class attributes: `ClassVar` vs `Final`
+
+```python
+from typing import ClassVar, Final
+from dataclasses import dataclass
+
+@dataclass
+class Config:
+    url: str                              # instance attr
+    timeout: int = 30                      # instance attr with default
+    VERSION: ClassVar[str] = '1.0'         # class-level constant
+    MAX_RETRIES: Final[int] = 3            # cannot be reassigned
+```
+
+## Callable types
+
+Types for function parameters.
+
+```python
+from typing import Callable
+
+# Callable[[arg_types...], return_type]
+def apply(func: Callable[[int, int], int], a: int, b: int) -> int:
+    return func(a, b)
+
+apply(lambda x, y: x + y, 2, 3)  # 5
+```
+
+## When to skip types
+
+Private one-liners where the type is obvious:
+```python
+# Fine — _hash is clearly int from hashlib
+def _hash(s): return hashlib.sha256(s.encode()).hexdigest()
+```
+
+Test functions: types are usually redundant if the test body makes them obvious.
+
+## Runtime type checking
+
+Most type hints are **not** enforced at runtime. Use `mypy` or `pyright` in CI.
+
+```bash
+# mypy.ini
+[mypy]
+strict = true
+python_version = 3.11
+warn_return_any = true
+warn_unused_ignores = true
+```
+
+For runtime validation at API boundaries, use `pydantic` or `attrs` — not type hints.
+
+## Type ignore comments
+
+Use sparingly. Narrow the suppression to the exact issue.
+
+```python
+# ignore one specific line
+result = legacy_api()  # type: ignore[no-untyped-call]
+
+# for whole file (top of file, last resort)
+# type: ignore
+```
+
+Never bare `# type: ignore` with no specific code. Reviewers can't tell what was suppressed.