// Houndarr's pytest patterns. Loads when reading or editing tests/ files. Covers the fixture dependency graph, the FK seeding pattern for cooldowns/search_log tests, the local _login() and CSRF helpers in route tests, and the auth-state reset in test_settings.
Houndarr's source layout and architectural patterns at file granularity. Loads when reading or editing src/houndarr/. Covers the per-file purpose for auth/, clients/, engine/, routes/, services/; the wire-models vs domain-models split; the *arr API spec snapshots under docs/api/; and pointers to the more specific database / engine skills for narrower scopes.
Houndarr's SQLite schema and migration discipline. Loads when reading or editing src/houndarr/database.py. Covers the schema table reference, the SCHEMA_VERSION bump checklist, and the version-locking rule for migration constants that prevents later renames from retroactively breaking earlier rebuild migrations.
Houndarr's CHANGELOG.md style guide and entry rules. Loads when reading or editing CHANGELOG.md or VERSION. Covers the noun-led present-tense voice, the 80-160 character length target, vocabulary the operator can act on, banned phrasings, what does not belong in a changelog, separator rules, and the bullet-justification protocol that prevents drafting from PR titles or memory.
Houndarr's CI workflow reference and branch protection. Loads when reading or editing .github/workflows/. Covers the 11 required status checks (exact names matter for branch protection), the additional non-required workflows, the paths-ignore + ci-skip pattern that keeps docs-only PRs green, and the rule against changing required check job names.
Houndarr-specific Python conventions on top of the global python skill. Loads when reading or editing .py files in this repo. Covers the noqa/nosec suppression table, the AppSettings-as-plain-dataclass decision, the frozen-dataclass-with-slots invariant for domain models, the per-module logger pattern, and the background-task error-handling shape.
Verify probabilistic, distributional, or random behaviour empirically before changing search-engine code. Loads when reading or editing src/houndarr/engine/. Use when a user, code review, or another AI surfaces a claim about bias, ordering, page selection, randomness, or "we are searching the same things over and over".
| name | houndarr-testing |
| description | Houndarr's pytest patterns. Loads when reading or editing tests/ files. Covers the fixture dependency graph, the FK seeding pattern for cooldowns/search_log tests, the local _login() and CSRF helpers in route tests, and the auth-state reset in test_settings. |
| paths | ["tests/**"] |
asyncio_mode = "auto",
asyncio_default_fixture_loop_scope = "function",
addopts = "-q --tb=short" (set in pyproject.toml).@pytest.mark.asyncio() (with parens), return -> None.respx for httpx calls; use @respx.mock decorator.TestClient (sync) or AsyncClient via ASGITransport.tmp_data_dir (temp directory, no deps)
├── db (init SQLite, depends on tmp_data_dir)
└── test_settings (AppSettings + auth state reset, depends on tmp_data_dir)
├── app (TestClient, depends on test_settings)
└── async_client (AsyncClient, depends on test_settings)
db and test_settings are siblings; both depend on tmp_data_dir
independently. Tests that need a database AND the app must request both
db and app (or use fixtures that depend on db).
The test_settings fixture resets _auth._serializer,
_auth._setup_complete, and _auth._login_attempts so auth state does
not bleed between tests.
Tests touching cooldowns or search_log must seed the instances table
first via the seeded_instances fixture (defined locally in
tests/test_engine/test_search_loop.py,
tests/test_engine/test_golden_search_log.py,
tests/test_engine/test_supervisor.py, and
tests/test_services/test_cooldown.py):
@pytest_asyncio.fixture()
async def seeded_instances(db: None) -> AsyncGenerator[None, None]:
async with get_db() as conn:
await conn.executemany(
"INSERT INTO instances (id, name, type, url, encrypted_api_key)"
" VALUES (?, ?, ?, ?, ?)",
[(1, "Sonarr Test", "sonarr", "http://sonarr:8989", _ENC_KEY),
(2, "Radarr Test", "radarr", "http://radarr:7878", _ENC_KEY)],
)
await conn.commit()
yield
Engine tests set encrypted_api_key to a valid Fernet-encrypted value
(_ENC_KEY). The simpler 4-column form (without encrypted_api_key)
is used in test_cooldown.py where only FK constraints matter.
A _login() helper is defined locally in each route test file that needs
it (test_logs.py, test_settings.py, test_status.py):
def _login(client: TestClient) -> None:
client.post("/setup", data={"username": "admin", "password": "ValidPass1!", ...})
client.post("/login", data={"username": "admin", "password": "ValidPass1!"})
Mutating authenticated routes require a valid CSRF token. Use the helpers
from tests/conftest.py:
from tests.conftest import csrf_headers, get_csrf_token
resp = client.post("/settings/instances", data=form, headers=csrf_headers(client))
resp = client.delete("/settings/instances/1", headers=csrf_headers(client))
Current CSRF exemptions: POST /logout, /login, /setup.
@pytest.mark.integration: 12 async engine-cycle cases in tests/test_e2e/
plus 15 Playwright flows in tests/e2e_browser/ (browser tree excluded
from default collection via norecursedirs; test_e2e/ is collected and
filterable).@pytest.mark.pinning: characterisation tests pinning current behaviour
before a refactor batch. Unit-scope; runs in the default suite. Add one
whenever a refactor needs a behavioural lock.just test, just test-quick, just test-integration, and just pin run
with pytest -n auto by default (pytest-xdist). Override with
PYTEST_WORKERS=0 for serial triage, or PYTEST_WORKERS=4 to constrain.
just test-browser chromium runs the Playwright e2e flows serially
(shared stack on fixed ports).