minor refactor: mention spec vs mainline tests in skills file
diff --git a/.agents/skills/groovy-tests/SKILL.md b/.agents/skills/groovy-tests/SKILL.md index cf15953..031a3db 100644 --- a/.agents/skills/groovy-tests/SKILL.md +++ b/.agents/skills/groovy-tests/SKILL.md
@@ -135,6 +135,15 @@ such a block; add/extend the inline block instead. See [Inline Javadoc tests](../../../CONTRIBUTING.md#inline-javadoc-tests). +8. **Duplicating spec-test coverage into `src/test/`.** Tests under + `src/spec/test/` are curated to read as user documentation and + run as real tests; a spec test *is* that behaviour's coverage. + Don't re-add it under `src/test/` or report a spec example as + untested. New error/edge/regression coverage belongs in the + ordinary `src/test/` tree (it need not double as docs); a *good + user-facing example* belongs in the spec test. See + [Executable AsciiDoc examples](../../../CONTRIBUTING.md#executable-asciidoc-examples). + ## Procedure When writing or modifying a test:
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 2147f28..d635c72 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md
@@ -38,3 +38,19 @@ CI. Only flag genuinely untested behaviour (no `groovyTestCase` block and nothing else exercising it). Canonical detail: see "Inline Javadoc tests" in [`../CONTRIBUTING.md`](../CONTRIBUTING.md). + +## Reviewing tests (spec tests) + +Tests under `src/spec/test/` (and `subprojects/<module>/src/spec/test/`) +are executable examples `include::`'d into the user-facing AsciiDoc +docs; they run as real tests. They are deliberately curated to read as +documentation — clear, representative examples, usually the happy path. +Error cases, edge cases, extra coverage, and regression tests for +tracked bugs typically live in the ordinary `src/test/` tree instead. + +Therefore: a spec test **is** that behaviour's coverage. Do not flag a +spec example as "untested", and **do not request that spec coverage be +duplicated** in `src/test/`. Only ask for additional `src/test/` +coverage for behaviour (error/edge cases) genuinely not exercised +anywhere. Canonical detail: see "Executable AsciiDoc examples" in +[`../CONTRIBUTING.md`](../CONTRIBUTING.md).
diff --git a/AGENTS.md b/AGENTS.md index 9caacfc..12087fc 100644 --- a/AGENTS.md +++ b/AGENTS.md
@@ -89,6 +89,14 @@ detail: "Inline Javadoc tests" in [`CONTRIBUTING.md`](CONTRIBUTING.md). +Likewise the **spec-test** convention: tests under `src/spec/test/` +are curated to read as user documentation (clear, representative +examples) and run as real tests — error/edge/coverage/regression tests +typically live in the ordinary `src/test/` tree. A spec test *is* its +coverage; don't duplicate it in `src/test/` or report it as untested. +Canonical detail: "Executable AsciiDoc examples" in +[`CONTRIBUTING.md`](CONTRIBUTING.md). + ## Coding conventions Follow what's already in the tree. Specifically:
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e8fce30..bb24bde 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md
@@ -303,6 +303,16 @@ A change to a documented example normally touches *both* files in the same PR. +**Spec tests are curated examples, not exhaustive coverage.** Tests +under `src/spec/test/` (and `subprojects/<module>/src/spec/test/`) are +deliberately chosen to read well as user documentation — clear, +representative examples, usually the happy path. Error cases, edge +cases, additional coverage, and regression tests for tracked bugs +typically (though not exclusively) live in the ordinary `src/test/` +tree instead, where they need not double as documentation. A spec test +runs as a real test and *is* that coverage: there is no need to +duplicate, in `src/test/`, what a spec test already exercises. + **Common pitfalls:** - **Mismatched tag and include.** The tag name in the AsciiDoc