@martinffx/atelier 1.4.0 → 3.0.0

package/skills/python-testing/references/pytest.md

@@ -1,524 +0,0 @@
-# pytest Configuration and Patterns
-
-## Configuration (pyproject.toml)
-
-### Basic Setup
-
-```toml
-[tool.pytest.ini_options]
-testpaths = ["tests"]
-python_files = ["test_*.py", "*_test.py"]
-python_classes = ["Test*"]
-python_functions = ["test_*"]
-addopts = [
-    "-ra",                # Show summary of all test outcomes
-    "--strict-markers",   # Fail on unknown markers
-    "--strict-config",    # Fail on invalid config
-    "-v",                 # Verbose output
-]
-```
-
-### With Coverage
-
-```toml
-[tool.pytest.ini_options]
-testpaths = ["tests"]
-addopts = [
-    "-ra",
-    "--strict-markers",
-    "--cov=src",
-    "--cov-report=term-missing",
-    "--cov-report=html",
-    "--cov-fail-under=80",
-]
-```
-
-### Markers
-
-```toml
-[tool.pytest.ini_options]
-markers = [
-    "unit: unit tests (no I/O)",
-    "integration: integration tests (with I/O)",
-    "slow: slow tests (takes >1s)",
-    "db: database tests",
-]
-```
-
-## Fixtures
-
-### Database Session
-
-```python
-import pytest
-from sqlalchemy import create_engine
-from sqlalchemy.orm import sessionmaker
-
-@pytest.fixture
-def test_db():
-    """In-memory test database"""
-    engine = create_engine("sqlite:///:memory:")
-    Base.metadata.create_all(engine)
-
-    SessionLocal = sessionmaker(bind=engine)
-    db = SessionLocal()
-
-    try:
-        yield db
-    finally:
-        db.close()
-```
-
-### Application Client
-
-```python
-import pytest
-from fastapi.testclient import TestClient
-
-@pytest.fixture
-def test_client():
-    """FastAPI test client"""
-    return TestClient(app)
-```
-
-### Auto-Use Fixtures for Setup/Teardown
-
-```python
-@pytest.fixture(autouse=True)
-def reset_db(test_db):
-    """Reset database before each test"""
-    Base.metadata.drop_all(bind=test_db.bind)
-    Base.metadata.create_all(bind=test_db.bind)
-```
-
-### Fixture Scope
-
-```python
-@pytest.fixture(scope="function")  # Default: per test
-def data():
-    ...
-
-@pytest.fixture(scope="module")    # Per test file
-def client():
-    ...
-
-@pytest.fixture(scope="session")   # For entire test run
-def config():
-    ...
-```
-
-### Parametrized Fixtures
-
-```python
-@pytest.fixture(params=[
-    {"name": "Alice", "age": 25},
-    {"name": "Bob", "age": 30},
-    {"name": "Charlie", "age": 35},
-])
-def user_data(request):
-    """Fixture provides multiple inputs"""
-    return request.param
-
-def test_user_creation(user_data):
-    """Runs 3 times with different data"""
-    user = User(**user_data)
-    assert user.name is not None
-```
-
-### Fixture Dependencies
-
-```python
-@pytest.fixture
-def test_db():
-    """Database fixture"""
-    engine = create_engine("sqlite:///:memory:")
-    Base.metadata.create_all(engine)
-    SessionLocal = sessionmaker(bind=engine)
-    return SessionLocal()
-
-@pytest.fixture
-def user_repository(test_db):
-    """Repository depends on database"""
-    return UserRepository(test_db)
-
-def test_repository_save(user_repository):
-    """Test uses repository (which uses database)"""
-    user = User(id=1, name="Alice")
-    user_repository.save(user)
-    assert user_repository.get(1) is not None
-```
-
-## Running Tests
-
-### Basic Commands
-
-```bash
-# Run all tests
-pytest
-
-# Run specific file
-pytest tests/test_entities.py
-
-# Run specific test
-pytest tests/test_entities.py::test_user_creation
-
-# Run with pattern
-pytest tests/test_*.py
-
-# Verbose output
-pytest -v
-
-# Very verbose (shows parameters)
-pytest -vv
-```
-
-### Filtering Tests
-
-```bash
-# Stop on first failure
-pytest -x
-
-# Stop after N failures
-pytest --maxfail=3
-
-# Show print statements
-pytest -s
-
-# Show local variables on failure
-pytest -l
-
-# Show durations of slowest tests
-pytest --durations=10
-```
-
-### Markers
-
-```bash
-# Run only unit tests
-pytest -m unit
-
-# Skip slow tests
-pytest -m "not slow"
-
-# Run integration tests
-pytest -m integration
-
-# Run tests matching pattern
-pytest -m "unit or integration"
-```
-
-### Coverage
-
-```bash
-# Generate coverage report
-pytest --cov=src
-
-# Show missing lines
-pytest --cov=src --cov-report=term-missing
-
-# Generate HTML report
-pytest --cov=src --cov-report=html
-# Open htmlcov/index.html in browser
-
-# Fail if below threshold
-pytest --cov=src --cov-fail-under=80
-```
-
-## Parametrize
-
-### Multiple Inputs
-
-```python
-@pytest.mark.parametrize("input,expected", [
-    (1, 2),
-    (2, 4),
-    (3, 6),
-    (4, 8),
-])
-def test_double(input, expected):
-    assert double(input) == expected
-```
-
-### Multiple Parameters
-
-```python
-@pytest.mark.parametrize("x,y,expected", [
-    (1, 2, 3),
-    (2, 3, 5),
-    (5, 5, 10),
-])
-def test_add(x, y, expected):
-    assert add(x, y) == expected
-```
-
-### Parametrize Multiple Test Values
-
-```python
-@pytest.mark.parametrize("value", [
-    "alice@example.com",
-    "bob@example.com",
-    "charlie@example.com",
-])
-def test_valid_email(value):
-    assert is_valid_email(value)
-```
-
-### Combining Parametrize
-
-```python
-@pytest.mark.parametrize("user_type", ["admin", "user", "guest"])
-@pytest.mark.parametrize("resource", ["posts", "comments", "users"])
-def test_permissions(user_type, resource):
-    """Tests all combinations (3×3 = 9 tests)"""
-    has_access = check_access(user_type, resource)
-    assert has_access is not None
-```
-
-## Markers
-
-### Built-in Markers
-
-```python
-@pytest.mark.skip
-def test_not_ready():
-    """Skip this test"""
-    ...
-
-@pytest.mark.skip(reason="Not implemented yet")
-def test_future():
-    """Skip with reason"""
-    ...
-
-@pytest.mark.skipif(sys.version_info < (3, 10), reason="Requires 3.10+")
-def test_new_syntax():
-    """Skip conditionally"""
-    ...
-
-@pytest.mark.xfail
-def test_known_bug():
-    """Mark as expected to fail"""
-    ...
-```
-
-### Custom Markers
-
-```python
-@pytest.mark.unit
-def test_entity():
-    ...
-
-@pytest.mark.integration
-def test_with_database():
-    ...
-
-@pytest.mark.slow
-def test_expensive_computation():
-    ...
-
-@pytest.mark.db
-def test_with_db():
-    ...
-```
-
-## Test Organization
-
-### Structure by Layer
-
-```
-tests/
-├── unit/
-│   ├── test_entities.py         # Entity tests
-│   ├── test_services.py         # Service tests (mocked)
-│   └── test_value_objects.py    # Value object tests
-├── integration/
-│   ├── test_repositories.py     # Repository tests (with DB)
-│   └── test_endpoints.py        # Router tests (with client)
-└── fixtures.py                  # Shared fixtures
-```
-
-### conftest.py for Shared Fixtures
-
-```python
-# tests/conftest.py
-import pytest
-from sqlalchemy import create_engine
-from sqlalchemy.orm import sessionmaker
-from fastapi.testclient import TestClient
-
-@pytest.fixture
-def test_db():
-    """Shared database fixture"""
-    engine = create_engine("sqlite:///:memory:")
-    Base.metadata.create_all(engine)
-    SessionLocal = sessionmaker(bind=engine)
-    db = SessionLocal()
-    try:
-        yield db
-    finally:
-        db.close()
-
-@pytest.fixture
-def test_client():
-    """Shared test client"""
-    return TestClient(app)
-
-# tests/test_entities.py
-def test_product_creation(test_db):
-    """Uses fixture from conftest.py"""
-    ...
-```
-
-### Naming Conventions
-
-```python
-# File names
-test_entities.py       # Tests for entities module
-test_create_product.py # Tests for specific feature
-
-# Test class (optional grouping)
-class TestProduct:
-    def test_creation(self):
-        ...
-
-    def test_validation(self):
-        ...
-
-# Test function names
-def test_product_creation():        # What is tested
-def test_product_with_discount():   # Behavior variant
-def test_product_raises_on_invalid_price():  # Error case
-```
-
-## Assertions and Context
-
-### assert with Message
-
-```python
-def test_with_message():
-    result = calculate()
-    assert result == 42, f"Expected 42 but got {result}"
-```
-
-### pytest.raises
-
-```python
-def test_raises_error():
-    with pytest.raises(ValueError):
-        invalid_operation()
-
-def test_raises_with_match():
-    with pytest.raises(ValueError, match="Invalid price"):
-        Product(price=-10)
-
-def test_raises_with_check():
-    with pytest.raises(ValueError) as exc_info:
-        invalid_operation()
-    assert "specific message" in str(exc_info.value)
-```
-
-### pytest.approx for Floats
-
-```python
-def test_float_calculation():
-    result = expensive_calculation()
-    # Avoid exact equality with floats
-    assert result == pytest.approx(3.14159, abs=0.0001)
-```
-
-### Comparing Collections
-
-```python
-def test_lists():
-    result = get_items()
-    assert result == [1, 2, 3]
-    assert 2 in result
-    assert len(result) == 3
-
-def test_dicts():
-    result = get_data()
-    assert result == {"name": "Alice", "age": 25}
-    assert result["name"] == "Alice"
-    assert "email" not in result
-```
-
-## Debugging Failed Tests
-
-### Print Debugging
-
-```bash
-# Show print statements
-pytest -s
-
-# Show print + traceback
-pytest -s -vv
-
-# Show local variables
-pytest -l
-
-# Full diff for collections
-pytest -vv --tb=short
-```
-
-### Using pdb
-
-```python
-def test_with_debugger():
-    result = complex_operation()
-    # Drop into debugger on failure
-    import pdb; pdb.set_trace()
-    assert result == expected
-```
-
-### Test Reports
-
-```bash
-# Generate JUnit XML (for CI)
-pytest --junit-xml=report.xml
-
-# Generate JSON report
-pytest --json-report --json-report-file=report.json
-
-# Generate HTML report
-pytest --html=report.html
-```
-
-## Performance Optimization
-
-### Profile Test Execution
-
-```bash
-# Show slowest tests
-pytest --durations=10
-
-# Show all tests sorted by duration
-pytest --durations=0
-```
-
-### Parallelize Tests
-
-```bash
-# Install pytest-xdist
-pip install pytest-xdist
-
-# Run tests in parallel (use N workers)
-pytest -n auto
-pytest -n 4
-```
-
-### Fixture Optimization
-
-```python
-# SLOW: Creates database for every test
-@pytest.fixture(scope="function")
-def test_db():
-    engine = create_engine("sqlite:///:memory:")
-    Base.metadata.create_all(engine)
-    ...
-
-# FAST: Creates once per session (if tests don't modify schema)
-@pytest.fixture(scope="session")
-def test_db():
-    engine = create_engine("sqlite:///:memory:")
-    Base.metadata.create_all(engine)
-    ...
-```

package/skills/spec-orchestrator/SKILL.md

@@ -1,145 +0,0 @@
----
-name: spec-orchestrator
-description: >
-  Skill routing and workflow orchestration. Routes to correct spec skill based on task type.
-  Establishes discipline and manages transitions between workflow phases. Use when starting
-  any conversation or task to determine which spec skill applies.
-user-invocable: false
----
-
-<EXTREMELY-IMPORTANT>
-If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY
-MUST invoke the skill.
-
-IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
-
-This is not negotiable. This is not optional. You cannot rationalize your way out of this.
-</EXTREMELY-IMPORTANT>
-
-# Spec Workflow
-
-You have skills. You MUST use them. Not "should." Not "when convenient." MUST.
-
-Invoke relevant skills BEFORE any response or action. Even a 1% chance a skill might apply
-means you invoke it. If an invoked skill turns out to be wrong for the situation, you don't
-need to follow it. But you must check.
-
-## The One Rule
-
-**Never write code until the human has reviewed and approved a written plan.**
-
-Every project goes through this process. A todo list, a single-function utility, a config
-change — all of them. "Simple" projects are where unexamined assumptions cause the most
-wasted work. The spec can be short, the plan can be brief, but you MUST present them
-and get approval.
-
-## Artifacts
-
-Every feature produces two artifacts in `docs/specs/YYYY-MM-DD-<feature>/`:
-
-```
-design.md    ← spec-brainstorm (requirements + research + architecture)
-plan.json    ← spec-plan (tasks, dependencies)
-```
-
-## Skill Routing
-
-```
-spec-brainstorm → Discovery + design + architecture → design.md
-spec-plan        → Implementation plan + tasks → plan.json
-spec-implement   → Execute tasks, track progress, report
-spec-finish      → Post-implementation validation
-code-subagents   → Parallel dispatch, two-stage review
-```
-
-### "Create a spec for X" / Build / Add Feature
-
-```
-spec-brainstorm → spec-plan → spec-implement → spec-finish
-```
-
-### Fix Complex Bug / Refactor
-
-```
-spec-brainstorm (research-heavy) → spec-plan (targeted) → spec-implement
-```
-
-### Quick Fix / Trivial Change
-
-If genuinely trivial (typo, single-line config, variable rename) — skip the pipeline.
-But be honest. If there's any doubt, plan it.
-
-## Hard Transitions
-
-| After completing... | The ONLY next step is... |
-|---------------------|--------------------------|
-| spec-brainstorm | spec-plan |
-| spec-plan | spec-implement |
-| spec-implement | spec-finish |
-
-Do NOT jump from requirements to code. Do NOT jump from research to implementation.
-
-## Iteration Patterns
-
-The workflow is not purely linear. Expect backflows:
-
-### Research → Research (discovery loop)
-- Brainstorm reveals new requirements → loop back to discovery phase
-- Human adds new scope mid-brainstorm → continue discovery
-
-### Plan → Research (design flaw)
-- Planning reveals design assumptions are wrong → back to brainstorm
-- Tasks can't be decomposed without more context → back to brainstorm
-
-### Implement → Plan (missing tasks)
-- Implementation reveals missing tasks → update plan.json
-- Blocked on dependency not in plan → back to plan
-
-### Implement → Research (fundamental issue)
-- Implementation reveals design is fundamentally wrong → back to brainstorm
-- "This can't work as designed" → back to brainstorm
-
-### Finish → Implement (bugs found)
-- Validation finds bugs → back to implement
-- Tests failing → back to implement
-
-### When to escalate
-If you loop 2+ times on the same issue, stop and ask the human:
-
-> "We've looped on [issue] twice. Should we reconsider the approach?"
-
-## Red Flags — You Are Rationalizing
-
-| What you're thinking | Why it's wrong |
-|----------------------|----------------|
-| "This is too simple for a plan" | Simple tasks have the most unexamined assumptions |
-| "I already know how to do this" | Knowing how ≠ having the human's approval for how |
-| "The human seems impatient" | Wasting time on wrong code is worse than planning |
-| "I'll just do a quick prototype" | Prototypes become production. Plan it. |
-| "I need to explore the code first" | That's the brainstorm phase. Write it in design.md. |
-| "Let me just fix this one thing" | One thing becomes three. Plan it. |
-| "I can plan in my head" | Plans in your head can't be reviewed or annotated |
-| "This is just a refactor" | Refactors touch more code than features. Plan it. |
-| "I'll write the plan after" | Post-hoc plans are fiction. Plan before. |
-| "I need more context first" | Skills tell you HOW to gather context. Check first. |
-| "The skill is overkill" | Simple things become complex. Use it. |
-| "I know what that skill says" | Skills evolve. Read current version. Invoke it. |
-| "This feels productive" | Undisciplined action wastes time. Skills prevent this. |
-
-## Skill Types
-
-**Process skills** (spec-brainstorm, spec-plan, spec-implement, spec-finish): Follow exactly.
-Don't adapt away discipline.
-
-**Knowledge skills** (oracle-grill-me, oracle-domain-modelling): Adapt principles to
-context. These inform decisions within the workflow.
-
-**Discipline skills** (oracle-debug): Strict methodology that must be followed
-exactly — no adaptation that bypasses root-cause investigation.
-
-Process skills come first. Knowledge skills get invoked by process skills when needed.
-
-## User Instructions
-
-"Add X" or "Fix Y" doesn't mean skip workflows. Instructions say WHAT, not HOW.
-The skills define HOW.