This is an automated email from the ASF dual-hosted git repository.
paulk-asert pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/groovy.git
The following commit(s) were added to refs/heads/master by this push:
new 6f24829c90 minor refactor: mention spec vs mainline tests in skills
file
6f24829c90 is described below
commit 6f24829c9038c9539426fc998420f481cde68ec9
Author: Paul King <[email protected]>
AuthorDate: Tue May 19 15:31:24 2026 +1000
minor refactor: mention spec vs mainline tests in skills file
---
.agents/skills/groovy-tests/SKILL.md | 9 +++++++++
.github/copilot-instructions.md | 16 ++++++++++++++++
AGENTS.md | 8 ++++++++
CONTRIBUTING.md | 10 ++++++++++
4 files changed, 43 insertions(+)
diff --git a/.agents/skills/groovy-tests/SKILL.md
b/.agents/skills/groovy-tests/SKILL.md
index cf15953084..031a3db99e 100644
--- a/.agents/skills/groovy-tests/SKILL.md
+++ b/.agents/skills/groovy-tests/SKILL.md
@@ -135,6 +135,15 @@ tests:
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 2147f285a7..d635c729f4 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -38,3 +38,19 @@ or "no accompanying unit tests"** — the tests are present
and run in
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 9caacfc102..12087fc6db 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -89,6 +89,14 @@ such blocks *is* adding tests; don't add or demand a separate
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 e8fce3058f..bb24bdee92 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -303,6 +303,16 @@ The pattern in three pieces:
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
