diff --git a/AGENTS.md b/AGENTS.md index 648ae386896..450ba6c6909 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -82,6 +82,10 @@ rules. Read the complete governance document before making or reviewing changes: 22. Print ionic-step indices one-based (starting from 1) in user-facing output files, matching the `g{N}` filename suffix convention; do not write zero-based step counters such as `STEP: 0` into output files. + 23. Use Autotest cases for integration tests. Standalone `add_test()` drivers + require a check Autotest cannot express, a PR rationale, and compliance + with "Integration Test Drivers" in the governance document. Autotest + helpers are unaffected. - Use LF line endings for text files. Only `.bat` and `.cmd` files may use CRLF. - Keep source file additions deterministic: update the relevant `CMakeLists.txt` or explain why the file is generated or included indirectly. diff --git a/docs/developers_guide/agent_governance.md b/docs/developers_guide/agent_governance.md index 53e911eafe0..731be2d8889 100644 --- a/docs/developers_guide/agent_governance.md +++ b/docs/developers_guide/agent_governance.md @@ -97,6 +97,7 @@ decisions. | Heterogeneous test evidence | CUDA/ROCM/kernel change has test evidence or reason | phase-one mechanical warning + AI review | CI + AI review | high | warn | changed paths and PR body | Sufficiency is human-reviewed | | Test existence | Source change has test evidence or reason | phase-one mechanical warning + AI review | CI + AI review | high | warn | PR body and changed paths | Sufficiency is human-reviewed | | Test sufficiency | Tests cover important behavior | AI review + human confirmation | AI + human review | medium | human confirmation | semantic review | Not mechanically blocked | +| Integration test driver | Integration test uses an Autotest case, not a standalone `add_test()` script | AI review + human confirmation | AI + human review | medium | human confirmation | `tests/**/CMakeLists.txt` and new scripts under `tests/` | Standalone drivers need a stated reason Autotest cannot express the check; see Integration Test Drivers | | INPUT behavior linkage | Parameter metadata/default/type/parser behavior updates YAML and docs | phase-one mechanical + AI review | CI + AI review | high | warn | behavior-field diff plus docs/PR body | Comment-only parameter-file changes are not blocked | | Documentation sync | Behavior/interface docs updated | phase-one mechanical warning + AI review | CI + AI review | medium | warn | changed paths and PR body | Major behavior changes escalate to reviewers | | PR metadata completeness | Issue, tests, behavior, INPUT, core impact, exceptions | phase-one mechanical | CI or GitHub bot | medium | warn | PR template fields | Not run by local hook | @@ -179,6 +180,24 @@ project regressions. Do not relax existing integration tests or reference files just to make a failure pass. Update references only when the intended behavior changed and the PR explains why the new reference is correct. +## Integration Test Drivers + +Use Autotest cases with `INPUT`, `STRU`, `KPT` (when needed) and `result.ref`, +listed in `CASES_*.txt` and run by `Autotest.sh` through the suite's CTest entry. +Autotest helpers are unaffected. + +Standalone `add_test()` drivers that launch ABACUS require a check Autotest +cannot express (e.g., nonzero exits or per-rank stderr) and a PR rationale. +Keep Autotest-compatible checks in cases. Drivers must: + +- Live in `tests/integrate/validation_tools/` with descriptive names + (e.g., `check_.py`); reserve `test_*.py` for tool unit tests. +- Use dedicated fixtures; never rewrite another case's `INPUT` at run time. +- Use `find_program` plus `if()` for optional interpreters; never `REQUIRED`. +- For MPI, forward `MPIEXEC_NUMPROC_FLAG`, `MPIEXEC_PREFLAGS` and + `MPIEXEC_POSTFLAGS`; set CTest `PROCESSORS` to the launched rank count. +- Set `OMP_NUM_THREADS=1`, use temporary scratch space and a CTest `TIMEOUT`. + ## CLI Verification When a usable ABACUS executable is present, INPUT and command-line changes