---
name: test-writer
description: Test design patterns, what to test, assertion strategies, mocking strategy, and common anti-patterns. Use when writing unit tests, integration tests, or end-to-end tests. Complements TDD workflow with concrete test design knowledge.
metadata:
  version: "1.0"
---

# Test Writer

## Decision Tree

```
Need to write a test → What kind?
    ├─ Testing a pure function → Unit test, no mocking needed
    ├─ Testing a class with dependencies → Unit test, mock dependencies
    ├─ Testing API endpoint → Integration test, real server + test DB
    ├─ Testing user workflow → E2E test (Playwright / platform integration test)
    └─ Testing UI appearance → Snapshot test
```

## What to Test

| Always Test | Skip |
|------------|------|
| Business logic / core algorithms | Framework internals |
| Edge cases (empty, null, boundary) | Simple getters/setters |
| Error paths and error messages | Third-party library behavior |
| State transitions | Private methods (test via public API) |
| Integration points (API, DB) | UI layout pixel-perfection |
| Security-sensitive paths (auth, validation) | Generated code |

## Naming Convention

```
test_[unit]_[scenario]_[expected result]

# Examples:
test_login_with_valid_credentials_returns_token
test_login_with_expired_password_returns_403
test_cart_add_item_when_full_raises_limit_error
```

## Assertion Best Practices

- **One logical assertion per test** - Test one behavior, not one `assert` statement
- **Assert on behavior, not implementation** - Check return values, not internal state
- **Use specific assertions** - `assertEqual(x, 5)` not `assertTrue(x == 5)`
- **Include failure messages** - `assertEqual(result, 5, "discount should be 5% for VIP")`
- **Test exact error types** - `assertRaises(ValueError)` not `assertRaises(Exception)`

## Mocking Strategy

| Mock | Don't Mock |
|------|-----------|
| External APIs / HTTP calls | The unit under test |
| Database (in unit tests) | Simple value objects |
| File system / network | Pure functions |
| Time / randomness | Internal collaborators (usually) |
| Third-party services | Everything (over-mocking = brittle tests) |

## Anti-Patterns

| Anti-Pattern | Problem | Fix |
|-------------|---------|-----|
| Testing implementation details | Breaks on refactor | Test behavior/output |
| Flaky tests ignored | Erode trust in test suite | Fix or delete immediately |
| Copy-paste test setup | Hard to maintain | Use fixtures/factories |
| No assertion (test just "runs") | Proves nothing | Always assert expected outcome |
| Testing too much in one test | Unclear what failed | One behavior per test |
| Mocking everything | Tests prove nothing | Only mock boundaries |

## Test Structure (Arrange-Act-Assert)

```
# Arrange - Set up inputs and expected outputs
user = create_user(role="admin")

# Act - Call the function under test
result = permissions.can_delete(user, resource)

# Assert - Verify the result
assert result is True
```

## Coverage Targets

- **New code**: 80%+ line coverage
- **Critical paths** (auth, payments, data): 95%+
- **Don't chase 100%**: Diminishing returns past 85% overall