| name | run-tests |
| description | Run integration or unit tests scoped to a domain, file, or category. Faster feedback than `just test`. Reports failures and points to /debug-failing-test. |
| argument-hint | <domain | path | category> [test-name-pattern] |
Run Tests Scoped to a Domain
Run a focused subset of the test suite. Use after editing handlers, controllers, or events to get feedback in seconds instead of running the full suite.
Arguments
$0 — domain name, relative path, or category. See resolution table below.$1 (optional) — test-name pattern passed to pytest -k. Example: signup_returns_user_data.
Path resolution
| Argument | Resolves to |
|---|
users | tests/integration/api/v1/users/ |
auth | tests/integration/api/v1/auth/ |
auth/login | tests/integration/api/v1/auth/test_login.py |
roles | tests/integration/api/v1/roles/ |
events/auth | tests/integration/events/v1/auth/ |
events/auth/user_verification_requested | tests/integration/events/v1/auth/test_user_verification_requested.py |
unit | tests/unit/ |
adapters | tests/integration/adapters/ |
all | tests/integration/ |
If the argument starts with tests/, treat it as an explicit path and pass through unchanged.
If the resolved path doesn't exist, list available domains and stop:
!ls tests/integration/api/v1/ 2>/dev/null && echo "--- events ---" && ls tests/integration/events/v1/ 2>/dev/null
Pre-flight
Integration tests need Docker (testcontainers spawn postgres + redis):
!docker info >/dev/null 2>&1 && echo "docker: ok" || echo "docker: NOT RUNNING — start Docker Desktop before integration tests"
If Docker is down and the target is integration, stop and tell the user. Unit and adapter tests can sometimes run without Docker; defer to pytest's own error.
Execution
uv run pytest <resolved-path> -xvs --tb=short [-k <pattern>]
Flags:
-x stop on first failure (fail fast for tighter feedback)-v verbose test names-s don't capture stdout (so prints during debugging are visible)--tb=short compact tracebacks
Why bypass nox: nox re-runs uv sync --group=dev --frozen every invocation. For iterative debugging that's slow. The dev group is normally already in sync — if pytest is missing, suggest uv sync --group=dev.
On success
Report a one-liner:
✓ N tests passed in {scope} ({duration})
On failure
- Show the failing test name and a 3-5 line error excerpt.
- Suggest:
run /debug-failing-test {failing-test-path} for guided diagnosis.
- Do NOT auto-fix — diagnosis and remediation belong to
/debug-failing-test.
When NOT to use
- For full pre-merge confidence — use
just test (whole integration suite, all Python versions per nox).
- For migrations testing — those run in the
postgres_url session fixture; the full suite covers them.
Common scopes
/run-tests users # all user endpoints
/run-tests auth/login # one file
/run-tests auth login_wrong_password # one test pattern in auth/
/run-tests events/auth # all auth event handlers
/run-tests unit # pure logic tests, no Docker
