python-skills 1.0.0__py3-none-any.whl

skills/testing/async_tests.md

@@ -0,0 +1,249 @@
+---
+name: testing_async_tests
+purpose: Testing async code with pytest-asyncio
+category: testing
+triggers:
+  - async
+  - pytest-asyncio
+  - asyncio
+  - async test
+  - async fixture
+  - async mock
+dependencies:
+  - generation/async_concurrency.md
+  - testing/organization.md
+  - testing/fixtures_mocks.md
+  - testing/edge_cases.md
+priority: supporting
+estimated_tokens: 2300
+---
+# Testing: Async Tests
+
+**Purpose**: Testing async code with pytest-asyncio.
+
+**When to use**: Any async functions, services, or integrations.
+
+---
+
+## Core Rules
+
+### Setup
+```ini
+# pytest.ini or pyproject.toml
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+```
+
+### Basic Async Test
+```python
+import pytest
+import pytest_asyncio
+
+@pytest.mark.asyncio
+async def test_async_function():
+    result = await async_function()
+    assert result == "expected"
+```
+
+### Async Fixtures
+```python
+# conftest.py
+import pytest_asyncio
+
+@pytest_asyncio.fixture
+async def async_client() -> AsyncClient:
+    client = AsyncClient()
+    yield client
+    await client.aclose()
+
+@pytest_asyncio.fixture
+async def db_pool() -> asyncpg.Pool:
+    pool = await asyncpg.create_pool("postgresql://test:test@localhost/test")
+    yield pool
+    await pool.close()
+```
+
+### Async Mocking
+```python
+from unittest.mock import AsyncMock
+
+@pytest.fixture
+def mock_async_service():
+    service = AsyncMock()
+    service.fetch.return_value = {"data": "test"}
+    service.fetch.side_effect = [
+        {"data": "first"},
+        {"data": "second"},
+        Exception("error"),
+    ]
+    return service
+
+@pytest.mark.asyncio
+async def test_async_mock(mock_async_service):
+    result = await mock_async_service.fetch()
+    assert result == {"data": "first"}
+    mock_async_service.fetch.assert_awaited_once()
+```
+
+### Testing Async Generators
+```python
+@pytest.mark.asyncio
+async def test_async_generator():
+    results = []
+    async for item in async_generator():
+        results.append(item)
+    assert results == [1, 2, 3]
+
+# Or collect
+@pytest.mark.asyncio
+async def test_async_generator_collect():
+    items = [item async for item in async_generator()]
+    assert items == [1, 2, 3]
+```
+
+### Testing Timeouts
+```python
+import asyncio
+
+@pytest.mark.asyncio
+async def test_timeout():
+    async def slow():
+        await asyncio.sleep(10)
+        return "done"
+    
+    with pytest.raises(asyncio.TimeoutError):
+        await asyncio.wait_for(slow(), timeout=0.1)
+```
+
+### Testing Concurrency
+```python
+@pytest.mark.asyncio
+async def test_concurrent_requests():
+    async def fetch(url):
+        await asyncio.sleep(0.1)
+        return url
+    
+    urls = [f"http://example.com/{i}" for i in range(10)]
+    results = await asyncio.gather(*[fetch(u) for u in urls])
+    assert len(results) == 10
+
+# With semaphore
+@pytest.mark.asyncio
+async def test_rate_limited():
+    sem = asyncio.Semaphore(2)
+    
+    async def limited_fetch(url):
+        async with sem:
+            await asyncio.sleep(0.1)
+            return url
+    
+    # Should take ~0.5s (10 tasks / 2 concurrent * 0.1s)
+    import time
+    start = time.monotonic()
+    await asyncio.gather(*[limited_fetch(f"url{i}") for i in range(10)])
+    elapsed = time.monotonic() - start
+    assert 0.4 < elapsed < 0.7
+```
+
+### Testing Cancellation
+```python
+@pytest.mark.asyncio
+async def test_cancellation():
+    async def long_running():
+        try:
+            await asyncio.sleep(10)
+        except asyncio.CancelledError:
+            # Cleanup
+            raise
+    
+    task = asyncio.create_task(long_running())
+    await asyncio.sleep(0.01)
+    task.cancel()
+    
+    with pytest.raises(asyncio.CancelledError):
+        await task
+```
+
+### TaskGroup (Python 3.11+)
+```python
+@pytest.mark.asyncio
+async def test_task_group():
+    async with asyncio.TaskGroup() as tg:
+        task1 = tg.create_task(fetch("url1"))
+        task2 = tg.create_task(fetch("url2"))
+    
+    # All completed or exception raised
+    assert task1.result() == "url1"
+    assert task2.result() == "url2"
+```
+
+---
+
+## Decision Rules
+
+| Need | Pattern |
+|------|---------|
+| Async function | `@pytest.mark.asyncio` |
+| Async fixture | `@pytest_asyncio.fixture` |
+| External async service | `AsyncMock` |
+| Timeout behavior | `asyncio.wait_for` |
+| Cancellation | `task.cancel()` + `CancelledError` |
+| Concurrent behavior | `asyncio.gather` / `TaskGroup` |
+
+---
+
+## Preferred Patterns
+
+```python
+# Test with real async dependencies (integration)
+@pytest.mark.asyncio
+async def test_database_integration(db_pool):
+    async with db_pool.acquire() as conn:
+        await conn.execute("INSERT INTO test (value) VALUES ($1)", "test")
+        row = await conn.fetchrow("SELECT value FROM test WHERE value = $1", "test")
+        assert row["value"] == "test"
+
+# Test retry logic
+@pytest.mark.asyncio
+async def test_retry_on_failure():
+    call_count = 0
+    
+    async def flaky():
+        nonlocal call_count
+        call_count += 1
+        if call_count < 3:
+            raise ConnectionError("fail")
+        return "success"
+    
+    result = await retry_async(flaky, attempts=3, base_delay=0.01)
+    assert result == "success"
+    assert call_count == 3
+```
+
+---
+
+## Avoid
+
+- Sync tests for async code
+- `asyncio.run()` in tests (use pytest-asyncio)
+- Blocking sleeps (`time.sleep`) in async tests
+- Not awaiting mocks (`assert_awaited` vs `assert_called`)
+- Shared event loop state between tests
+
+---
+
+## Validation Considerations
+
+- `pytest-asyncio` handles event loop per test
+- No "Event loop is closed" errors
+- Timeout tests actually timeout (not hang)
+- Cancellation cleanup verified
+
+---
+
+## Related Skills
+
+- `generation/async_concurrency.md`
+- `testing/organization.md`
+- `testing/fixtures_mocks.md`
+- `testing/edge_cases.md`

skills/testing/coverage.md

@@ -0,0 +1,168 @@
+# Testing: Coverage
+
+**Purpose**: Meaningful test coverage measurement and targets.
+
+**When to use**: Configuring coverage, interpreting reports, setting thresholds.
+
+---
+
+## Core Rules
+
+### Coverage Types
+| Type | Meaning |
+|------|---------|
+| **Line** | Executable lines executed |
+| **Branch** | Decision branches taken (if/else, loops) |
+| **Function** | Functions called |
+| **Statement** | Similar to line |
+
+### Configuration
+```toml
+# pyproject.toml
+[tool.coverage.run]
+source = ["src"]
+omit = [
+    "tests/*",
+    "*/__main__.py",
+    "*/migrations/*",
+    "*/conftest.py",
+]
+branch = true  # Branch coverage (important!)
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+]
+precision = 2
+show_missing = true
+
+[tool.coverage.html]
+directory = "htmlcov"
+```
+
+### Running Coverage
+```bash
+# Basic
+pytest --cov=mypackage --cov-report=term-missing
+
+# With branch coverage
+pytest --cov=mypackage --cov-branch --cov-report=term-missing
+
+# HTML report
+pytest --cov=mypackage --cov-report=html
+
+# XML for CI
+pytest --cov=mypackage --cov-report=xml
+```
+
+### Interpreting Coverage
+```text
+Name                    Stmts   Miss  Branch BrMiss  Cover   Missing
+----------------------------------------------------------------------
+src/mypackage/__init__      5      0      0      0   100%
+src/mypackage/models.py    50      2     10      2    92%   45-46
+src/mypackage/service.py   120     15     30      8    85%   78-85, 92-95
+src/mypackage/utils.py     30      0      4      0   100%
+----------------------------------------------------------------------
+TOTAL                     205     17     44     10    90%
+```
+
+- **Line coverage**: 90% (188/205)
+- **Branch coverage**: 77% (34/44) — more important!
+- **Missing**: Shows exact lines/branches not covered
+
+### Coverage Targets
+| Project Type | Line | Branch |
+|--------------|------|--------|
+| New project | 90%+ | 85%+ |
+| Mature library | 95%+ | 90%+ |
+| Application | 80%+ | 75%+ |
+| Legacy | Improve incrementally | |
+
+### What Coverage Does NOT Measure
+- **Logic correctness** — 100% coverage ≠ bug-free
+- **Edge cases** — May cover line but not all values
+- **Integration** — Unit coverage ≠ system works
+- **Security** — Coverage doesn't check vulnerabilities
+
+---
+
+## Decision Rules
+
+| Situation | Coverage Goal |
+|-----------|---------------|
+| New code (PR) | 100% line, 100% branch |
+| Critical paths (auth, payments) | 100% branch |
+| Legacy code | Incremental improvement |
+| Generated code | Exclude (`pragma: no cover`) |
+| Prototypes | No requirement |
+
+---
+
+## Preferred Patterns
+
+```python
+# Exclude from coverage (rare, justify)
+def __repr__(self) -> str:  # pragma: no cover
+    return f"<{self.__class__.__name__}(id={self.id})>"
+
+# Hard to test error paths
+def connect(self):  # pragma: no cover
+    try:
+        self._connect()
+    except OSError as e:
+        if e.errno == errno.ENETUNREACH:
+            raise NetworkUnreachable() from e
+        raise
+
+# Branch coverage important here
+def process(value: int) -> str:
+    if value > 0:          # Branch 1
+        return "positive"
+    elif value < 0:        # Branch 2
+        return "negative"
+    else:                  # Branch 3
+        return "zero"
+
+# Test all 3 branches
+@pytest.mark.parametrize("value,expected", [
+    (1, "positive"),
+    (-1, "negative"),
+    (0, "zero"),
+])
+def test_process(value, expected):
+    assert process(value) == expected
+```
+
+---
+
+## Avoid
+
+- Coverage as only quality metric
+- 100% coverage mandate (leads to bad tests)
+- Excluding code without justification
+- Not measuring branch coverage
+- Testing getters/setters just for coverage
+
+---
+
+## Validation Considerations
+
+- CI fails if coverage drops below threshold
+- `pytest --cov-fail-under=80 --cov-branch --cov-fail-under-branch=75`
+- Track coverage trends over time
+- Focus on branch coverage for critical logic
+
+---
+
+## Related Skills
+
+- `testing/organization.md`
+- `testing/edge_cases.md`
+- `testing/regression_tests.md`
+- `quality/maintainability.md`

skills/testing/edge_cases.md

@@ -0,0 +1,197 @@
+# Testing: Edge Cases
+
+**Purpose**: Systematic edge case coverage for robust code.
+
+**When to use**: Writing tests for any function with external input or complex logic.
+
+---
+
+## Core Rules
+
+### Edge Case Categories
+
+| Category | Examples |
+|----------|----------|
+| **Empty/Zero** | `""`, `[]`, `{}`, `0`, `0.0`, `None` |
+| **Boundary** | Min, max, min-1, max+1, off-by-one |
+| **Special values** | `NaN`, `Inf`, `-0.0`, `True`/`False` as int |
+| **Unicode** | Emoji, RTL, combining chars, null bytes |
+| **Large** | Huge strings, deep nesting, many items |
+| **Concurrent** | Race conditions, double-submit |
+| **Failure** | Network error, timeout, disk full, permission denied |
+| **Malformed** | Invalid encoding, truncated data, wrong type |
+
+### Parameterized Edge Cases
+```python
+import pytest
+
+# String edges
+STRING_EDGES = [
+    ("", "empty"),
+    (" ", "whitespace"),
+    ("\t\n\r", "control-chars"),
+    ("a" * 10000, "long"),
+    ("🎉🎊", "emoji"),
+    ("\u200b", "zero-width"),
+    ("\x00", "null-byte"),
+    ("../../../etc/passwd", "traversal"),
+]
+
+@pytest.mark.parametrize("value,case_id", STRING_EDGES, ids=lambda x: x[1])
+def test_string_input(value: str, case_id: str):
+    result = process_string(value)
+    assert isinstance(result, str)
+
+# Numeric edges
+NUMERIC_EDGES = [
+    (0, "zero"),
+    (-1, "negative"),
+    (1, "positive"),
+    (2**63 - 1, "max-int64"),
+    (-(2**63), "min-int64"),
+    (float("inf"), "infinity"),
+    (float("-inf"), "neg-infinity"),
+    (float("nan"), "nan"),
+    (1.5, "float"),
+]
+
+@pytest.mark.parametrize("value,case_id", NUMERIC_EDGES, ids=lambda x: x[1])
+def test_numeric_input(value, case_id):
+    if isinstance(value, float) and (value != value or value in (float("inf"), float("-inf"))):
+        with pytest.raises(ValidationError):
+            process_number(value)
+    else:
+        result = process_number(value)
+        assert result == expected(value)
+```
+
+### Collection Edges
+```python
+COLLECTION_EDGES = [
+    ([], "empty"),
+    ([1], "single"),
+    ([1, 2], "two"),
+    (list(range(10000)), "large"),
+    ([None, "", 0, False], "falsy-values"),
+    ([{"nested": {"deep": "value"}}], "nested"),
+]
+
+@pytest.mark.parametrize("items,case_id", COLLECTION_EDGES, ids=lambda x: x[1])
+def test_collection_processing(items, case_id):
+    result = process_items(items)
+    assert len(result) == len(items)
+```
+
+### None/Optional Edges
+```python
+def test_optional_handling():
+    # Explicit None
+    assert process_optional(None) == default_value()
+    
+    # Missing key vs None value
+    assert process_dict({}) == default_value()
+    assert process_dict({"key": None}) == default_value()
+    assert process_dict({"key": "value"}) == "value"
+```
+
+### Concurrency Edges
+```python
+import threading
+import time
+
+def test_thread_safety(counter):
+    def increment():
+        for _ in range(1000):
+            counter.increment()
+    
+    threads = [threading.Thread(target=increment) for _ in range(10)]
+    for t in threads: t.start()
+    for t in threads: t.join()
+    
+    assert counter.value == 10000  # No race condition
+```
+
+### Time Edges
+```python
+from freezegun import freeze_time
+
+@freeze_time("2024-01-15 12:00:00")
+def test_time_dependent():
+    assert get_current_timestamp() == "2024-01-15T12:00:00Z"
+
+# Leap year, DST, timezone
+@freeze_time("2024-02-29 23:59:59")  # Leap day
+def test_leap_year():
+    ...
+
+@freeze_time("2024-03-10 02:30:00", tz_offset=-5)  # DST transition
+def test_dst():
+    ...
+```
+
+---
+
+## Decision Rules
+
+| Function Input | Edge Cases to Test |
+|----------------|-------------------|
+| String | Empty, whitespace, unicode, long, injection |
+| Number | 0, negative, min/max, float special |
+| List/Dict | Empty, single, large, nested, None elements |
+| Optional | None, missing, empty string |
+| Date/Time | Boundaries, DST, leap, timezone |
+| File | Empty, large, missing, permission, symlink |
+| Network | Timeout, 5xx, 4xx, malformed response |
+
+---
+
+## Preferred Patterns
+
+```python
+# Property-based testing (hypothesis)
+from hypothesis import given, strategies as st
+
+@given(st.text())
+def test_string_property(s: str):
+    # Should never crash on any string
+    result = safe_process(s)
+    assert isinstance(result, str)
+
+@given(st.integers())
+def test_int_property(n: int):
+    result = process_int(n)
+    assert result >= 0
+
+@given(st.lists(st.integers()))
+def test_list_property(items: list[int]):
+    result = process_list(items)
+    assert len(result) <= len(items)
+```
+
+---
+
+## Avoid
+
+- Only testing "happy path"
+- Assuming input is always valid
+- Missing boundary values (off-by-one)
+- Not testing error handling paths
+- Ignoring Unicode/timezone/concurrency
+
+---
+
+## Validation Considerations
+
+- `pytest --cov` shows uncovered branches
+- `hypothesis` finds unexpected edge cases
+- Mutation testing (`mutmut`) verifies test quality
+- Fuzzing for parsers/decoders
+
+---
+
+## Related Skills
+
+- `testing/organization.md`
+- `testing/parameterized.md`
+- `security/input_validation.md`
+- `generation/error_handling.md`