diff --git a/AGENTS.md b/AGENTS.md index 4392dd558f..f417ccf4a7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -276,12 +276,34 @@ This is a test suite - internal APIs have NO backward compatibility requirements - `##### Special notes for reviewer:` — must be present (may be empty) - `##### jira-ticket:` — must be present (may be empty) +### Utilities Unit Test Requirements + +Changes under `utilities/` require matching unit test coverage unless an exception below applies. If you add a function, add its tests. If you change behavior, update the assertions. Do not treat a passing `utilities-unittests` as proof of coverage — it only runs existing tests. Missing test coverage for new or modified utility code is a defect. + +**Add or update unit tests in the same commit/PR when ANY of these apply:** + +- A **coverage-enforced** utilities module changed (any `utilities/*.py` file **not** listed in `[tool.coverage.run] omit` in `pyproject.toml`) +- A module that already has `utilities/unittests/test_.py` and the change adds or modifies **testable behavior** (new public function, changed logic, bug fix, new error path) +- A bug fix in utilities code where a mocked unit test can lock the regression without a cluster + +Add or update tests in `utilities/unittests/test_.py`. New public functions need dedicated test methods. For changes to existing behavior, extend the matching test rather than adding a redundant one. Follow patterns in [`utilities/unittests/README.md`](utilities/unittests/README.md) and existing `test_*.py` files. Do not put utility helpers in `conftest.py` under `utilities/unittests/`. + +**Unit tests are NOT required before commit when:** + +- Only **coverage-omitted** large modules changed (`virt.py`, `infra.py`, `network.py`, `storage.py`) and the change is thin wiring (parameter pass-through, logging, default value) already covered by integration tests +- The change is docs-only, import-only, or a rename with no behavior change + +When unit tests are not added, state why in the PR (`##### Special notes for reviewer:`) — e.g. "coverage-omitted `virt.py` helper; behavior covered by `test_migrate_snapshot_hotplugged_vm`". + ## Essential Commands ### Before Committing Verification (MANDATORY) Before committing, these checks MUST pass: +1. **Utilities unit test assessment** — per [Utilities Unit Test Requirements](#utilities-unit-test-requirements) above: add tests when required, or document why not +2. **Commands below** — all must pass + ```bash # Required before every commit uv run pre-commit run --all-files # Linting and formatting @@ -299,6 +321,7 @@ uv run tox -e utilities-unittests ## Related Documentation - [`docs/CODE_ORGANIZATION.md`](docs/CODE_ORGANIZATION.md) — Constants, utilities, and fixtures layout and import rules +- [`utilities/unittests/README.md`](utilities/unittests/README.md) — Utilities unit test patterns and coverage status - [`docs/QUARANTINE_GUIDELINES.md`](docs/QUARANTINE_GUIDELINES.md) — Test quarantine and de-quarantine procedures - [`docs/SOFTWARE_TEST_DESCRIPTION.md`](docs/SOFTWARE_TEST_DESCRIPTION.md) — STD docstring format and requirements - [`docs/CODING_AND_STYLE_GUIDE.md`](docs/CODING_AND_STYLE_GUIDE.md) — Detailed coding and style conventions