---
apply: always
---

<!-- AUTOGENERATED: Run `node scripts/sync-ai-workflow.mjs --write`. -->

# Backend PHP Testing Rules

These rules apply to `services/nginx/app/tests` and any backend change that needs verification.

1. Add or update tests for every new feature, bug fix, API contract change, or search or authentication workflow change.
2. Run backend verification in the `php1` container. Do not use host-side PHP for the supported workflow.
3. Use `docker compose exec -T php1 sh -lc "cd /var/www/html && composer test:unit"` for unit coverage.
4. Use `docker compose exec -T php1 sh -lc "cd /var/www/html && composer test:integration"` when code depends on Redis, MySQL, or environment-backed configuration.
5. Use `docker compose exec -T php1 sh -lc "cd /var/www/html && composer test:api"` when route behavior, envelopes, or request parsing changes.
6. Keep tests deterministic: no live third-party calls, no shared Redis keys, no broad database cleanup, and no sleeps unless time behavior is the thing under test.
7. Prefer narrow fixtures, explicit cleanup, and behavior-level assertions over implementation checks.
8. When public routes, schemas, or permissions change, update `openapi.yaml` together with the tests.
9. Run the narrowest relevant suite first, then the broader suite that matches the risk before you finish the task.

Canonical workflow reference: `.ai-workflow/workflow.md`.