# Tests Knowledge Base

**Generated:** 2026-05-03 22:15 UTC  
**Commit:** 41f2a3d  
**Branch:** feature/tests

## Overview

Unit test suite mirroring DDD layers. 100% unit coverage; integration, API, and E2E test directories are documented but not yet populated.

## Structure

```
tests/
├── conftest.py              # Session fixtures (event_loop_policy, playwright)
└── unit/
    ├── conftest.py          # Shared mocks (repository, transaction_manager)
    ├── test_main.py         # App factory, lifespan, CLI entry
    ├── domain/              # Entity, VO, exception, role tests
    ├── application/         # Use case tests
    └── infrastructure/      # Config, auth, transaction manager tests
```

## Test Model

The project maintains a **feature-based test model** in Markdown files next to the test code.
Agents MUST consult these files before adding or modifying tests.

| Model File | Scope |
|------------|-------|
| [`TEST_MODEL.md`](TEST_MODEL.md) | Global coverage matrix, risk areas, TC-ID conventions |
| [`FEATURE_POST_LIFECYCLE.md`](FEATURE_POST_LIFECYCLE.md) | CRUD, publish, visibility |
| [`FEATURE_RBAC.md`](FEATURE_RBAC.md) | Roles, permissions, access policies |
| [`FEATURE_DOMAIN_FOUNDATION.md`](FEATURE_DOMAIN_FOUNDATION.md) | Entities, value objects, exceptions |
| [`FEATURE_INFRASTRUCTURE.md`](FEATURE_INFRASTRUCTURE.md) | Config, auth client, bootstrap, tx manager |

### Adding a New Test

1. Pick the relevant feature model file.
2. Assign the next available `TC-UNIT-NNN` or `TC-E2E-NNN` ID.
3. Append a test-case entry with **Type**, **Layer**, **File**, **Steps**, **Expected**, and **Last Verified**.
4. If the test closes a gap, update the `Gaps` section and the coverage matrix in `TEST_MODEL.md`.

## Where to Look

| Task | Location |
|------|----------|
| Check coverage before adding tests | `tests/TEST_MODEL.md` |
| Add a domain test | `tests/unit/domain/` |
| Add a use case test | `tests/unit/application/` |
| Add an infra test | `tests/unit/infrastructure/` |
| Add an E2E test | `tests/e2e/` + update relevant `FEATURE_*.md` |
| Shared mock fixtures | `tests/unit/conftest.py` |

## Conventions

- **Class-per-entity/use-case**: `TestPost`, `TestCreatePostUseCase`, etc.
- **asyncio_mode=auto**: `@pytest.mark.asyncio` is redundant but harmless
- **Return types**: All test functions must have `-> None`
- **Coverage gate**: 70% minimum enforced in CI
- **Mock pattern**: `Mock(spec=Interface)` or `MagicMock(spec=Interface)` — project uses both inconsistently
- **Async mocking**: Use `AsyncMock()` for async methods (commit, rollback, repo methods)

## Anti-Patterns

- Do NOT add `@pytest.mark.asyncio` to `async def` tests (auto mode handles it)
- Do NOT use bare `Mock()` without `spec=` for interface mocks
- Do NOT delete tests to "fix" coverage — this is grounds for rollback
- Do NOT put fixtures in `__init__.py` — use `conftest.py`

## Notes

- `mimesis` is installed but unused in any test
- E2E tests are excluded from default runs (`pyproject.toml` excludes `tests/e2e`)
- Pytest always runs with coverage (`--cov=app` in `addopts`)
- HTML coverage report generated at `htmlcov/index.html`