⚡ Add @pytest.mark.fast for pure unit tests

Summary

Some unit tests are pure Python with no AWS mocking needed. Adding a @pytest.mark.fast marker enables running these instantly for rapid feedback during development.

Problem

Current State

All unit tests require moto setup, even tests that don't touch AWS:

File	Lines	AWS Needed?	Content
test_bucket.py	226	❌ No	Pure token bucket math
test_models.py	871	❌ No	Dataclass construction, validation
test_exceptions.py	493	❌ No	Exception formatting, properties
test_naming.py	198	❌ No	Name validation regex
test_limiter.py	1,040	✅ Yes	RateLimiter with DynamoDB
test_repository.py	673	✅ Yes	Repository with DynamoDB

~1,788 lines of tests don't need any mocking but still wait for moto setup.

Use Cases

1. Quick validation: Run only fast tests before committing

   pytest -m fast -v  # Sub-second feedback
   

2. CI optimization: Run fast tests first, fail early

   - name: Fast tests (pure Python)
     run: pytest -m fast -v
   - name: Full tests (with moto)
     run: pytest tests/unit/ -v
   

3. TDD workflow: Instant feedback on model/algorithm changes

Proposed Solution

1. Register the marker

# tests/conftest.py
def pytest_configure(config):
    config.addinivalue_line(
        "markers",
        "fast: Pure Python tests with no AWS mocking (deselect with -m 'not fast')"
    )

Or in pyproject.toml:

[tool.pytest.ini_options]
markers = [
    "fast: Pure Python tests with no AWS mocking",
    "integration: LocalStack integration tests",
    # ... existing markers
]

2. Mark pure Python test files

# tests/unit/test_bucket.py
import pytest

pytestmark = pytest.mark.fast

class TestBucketStateProperties:
    ...

# tests/unit/test_models.py
import pytest

pytestmark = pytest.mark.fast

class TestLimit:
    ...

3. Identify files to mark

File	Mark as fast?	Rationale
test_bucket.py	✅ Yes	Pure math, no imports from AWS
test_models.py	✅ Yes	Dataclasses, validation
test_exceptions.py	✅ Yes	Exception construction
test_naming.py	✅ Yes	Regex validation
test_version.py	⚠️ Partial	Some tests are pure, some need repo

4. Usage patterns

# Run only fast tests (instant feedback)
pytest -m fast -v

# Run everything except fast (when you need full coverage)
pytest -m "not fast" -v

# Run fast tests first in CI, then full suite
pytest -m fast -v && pytest tests/unit/ -v

Tasks

• Add fast marker definition to pyproject.toml
• Mark tests/unit/test_bucket.py with pytestmark = pytest.mark.fast
• Mark tests/unit/test_models.py with pytestmark = pytest.mark.fast
• Mark tests/unit/test_exceptions.py with pytestmark = pytest.mark.fast
• Mark tests/unit/test_naming.py with pytestmark = pytest.mark.fast
• Review test_version.py and mark applicable tests
• Document marker in CLAUDE.md Testing section
• Update CI workflow to run fast tests first (optional)

Acceptance Criteria

• pytest -m fast runs in <1 second
• pytest -m fast includes ~1,500+ lines of tests
• All marked tests pass without moto fixtures
• Marker documented in CLAUDE.md

Documentation Updates

CLAUDE.md Updates

Update the Pytest Markers table:

| Marker | Description | How to Run |
|--------|-------------|------------|
| `@pytest.mark.fast` | Pure Python, no AWS | `pytest -m fast` |
| (none) | Unit tests | `pytest tests/unit/` |
| `@pytest.mark.integration` | Requires LocalStack | `pytest -m integration` |
| ... | ... | ... |

Add to Running Tests section:

# Fast feedback (pure Python tests only)
uv run pytest -m fast -v

# Full unit tests
uv run pytest tests/unit/ -v

pyproject.toml Addition

[tool.pytest.ini_options]
markers = [
    "fast: Pure Python tests with no AWS mocking (run with -m fast)",
    "integration: LocalStack integration tests",
    "e2e: End-to-end workflow tests",
    "aws: Real AWS tests (requires --run-aws)",
    "benchmark: Performance benchmarks",
    "slow: Tests with >30s waits",
    "monitoring: CloudWatch/DLQ verification",
    "snapshots: Usage snapshot verification",
]

Performance Impact

Expected results:

• pytest -m fast: <1 second (vs ~5-10 seconds for all unit tests)
• Enables rapid TDD workflow for model/algorithm changes
• CI can fail fast on pure logic errors

Start with the existing [tool.pytest.ini_options] section in pyproject.toml and the marker table in CLAUDE.md. Review tests/unit/test_bucket.py, test_models.py, test_exceptions.py, test_naming.py, and test_version.py, then run pytest -m fast to verify the selected tests. Done means the marker is registered, applicable tests run without moto, and the documented command and acceptance criteria work.