Testing Quality Standards

# Testing Anti-Patterns

## Testing Implementation Details

```python
# Bad: Testing private methods
def test_internal_method():
    service = UserService()
    result = service._validate_email("test@example.com")  # Testing private method
    assert result is True

# Good: Testing public behavior
def test_user_creation_validates_email():
    service = UserService()
    with pytest.raises(ValidationError):
        service.create_user("Alice", "invalid-email")
```

## Over-Mocking

```python
# Bad: Mocking simple calculations
@patch("calculator.add")
def test_total(mock_add):
    mock_add.return_value = 5
    assert calculate_total(2, 3) == 5

# Good: Test the actual logic
def test_total():
    assert calculate_total(2, 3) == 5
```

## Missing Assertions

```python
# Bad: No assertions
def test_user_creation():
    user = create_user("Alice", "alice@example.com")
    print(f"Created user: {user}")  # No assertions

# Good: Clear assertions
def test_user_creation():
    user = create_user("Alice", "alice@example.com")
    assert user.name == "Alice"
    assert user.email == "alice@example.com"
    assert user.is_active is True
```

## Shared Mutable State

```python
# Bad: Shared mutable state between tests
shared_data = []

def test_append():
    shared_data.append(1)
    assert len(shared_data) == 1

def test_another():
    shared_data.append(2)
    assert len(shared_data) == 1  # Fails due to shared state

# Good: Use fixtures for isolation
@pytest.fixture
def data():
    return []

def test_append(data):
    data.append(1)
    assert len(data) == 1
```

## Test Order Dependencies

```python
# Bad: Tests depend on execution order
def test_step_1():
    global user
    user = create_user("Alice")

def test_step_2():
    # Depends on test_step_1 running first
    assert user.name == "Alice"

# Good: Independent tests with fixtures
@pytest.fixture
def user():
    return create_user("Alice")

def test_user_creation(user):
    assert user.name == "Alice"
```

## Dead Waits

```python
# Bad: Arbitrary sleeps
def test_async_operation():
    start_operation()
    time.sleep(5)  # Arbitrary wait
    assert operation_complete()

# Good: Wait for condition
def test_async_operation():
    start_operation()
    wait_for_condition(lambda: operation_complete(), timeout=5)
    assert operation_complete()
```


---
name: best-practices
description: Testing best practices and principles
parent_skill: leyline:testing-quality-standards
category: infrastructure
estimated_tokens: 200
reusable_by: [pensive:test-review, parseltongue:python-testing]
---

# Testing Best Practices

## Core Principles

1. **Test behavior, not implementation** - Focus on what, not how
2. **One concept per test** - Keep tests focused
3. **Arrange-Act-Assert** - Consistent structure
4. **BDD language** - Given/When/Then for clarity
5. **Fast feedback** - Tests should run quickly

## Naming and Structure

6. **Descriptive names** - `test_user_creation_with_invalid_email_raises_error`
7. **Independent tests** - No shared state between tests
8. **Use fixtures** - Avoid setup duplication

## Boundaries and Coverage

9. **Mock at boundaries** - Only mock external dependencies
10. **Measure coverage** - Aim for meaningful, not just high

## Exit Criteria

- Coverage thresholds documented and understood
- Quality metrics defined and measurable
- Anti-patterns identified and avoided
- Best practices applied consistently


# Content Assertion Levels

## Why Content Assertions Exist

Markdown files under `skills/`, `agents/`, `modules/`, and `commands/`
are execution markdown: Claude Code interprets them as behavioral
instructions, not static documentation. When these files contain broken
JSON schemas, stale