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 9e3dd7c521 skills doco tweaks to help stop copilot false positives
when inline javadoc tests exist
9e3dd7c521 is described below
commit 9e3dd7c521023ea34c17783dc9f36cd94e861b8b
Author: Paul King <[email protected]>
AuthorDate: Tue May 19 09:42:36 2026 +1000
skills doco tweaks to help stop copilot false positives when inline javadoc
tests exist
---
.agents/skills/groovy-tests/SKILL.md | 14 +++++++++++++-
.github/copilot-instructions.md | 18 ++++++++++++++++++
AGENTS.md | 10 ++++++++++
CONTRIBUTING.md | 19 +++++++++++++++++++
4 files changed, 60 insertions(+), 1 deletion(-)
diff --git a/.agents/skills/groovy-tests/SKILL.md
b/.agents/skills/groovy-tests/SKILL.md
index c717655293..cf15953084 100644
--- a/.agents/skills/groovy-tests/SKILL.md
+++ b/.agents/skills/groovy-tests/SKILL.md
@@ -74,7 +74,11 @@ bug, no scratch files left behind, hand-back for review.
- [`CONTRIBUTING.md`](../../../CONTRIBUTING.md) "Tests" — the
canonical conventions this skill cites (framework, naming,
- AsciiDoc pattern, targeted runs, pitfalls).
+ AsciiDoc pattern, targeted runs, pitfalls). Includes the
+ **inline Javadoc test** convention: a
+ `<pre class="...groovyTestCase">` block in a doc comment is run
+ as a real JUnit test by `JavadocAssertionTestSuite` and is the
+ standard test form for the GDK — see "Inline Javadoc tests" there.
- [`ARCHITECTURE.md`](../../../ARCHITECTURE.md) "Tests" — the
test-layout map.
- [`COMPATIBILITY.md`](../../../COMPATIBILITY.md) — what
@@ -123,6 +127,14 @@ tests:
`spock.lang.Specification` in a new test class without a
specific reason.
+7. **Treating `groovyTestCase`-covered behaviour as untested.**
+ A `<pre class="...groovyTestCase">` block in a method's
+ Javadoc *is* its test (run by `JavadocAssertionTestSuite`) —
+ the GDK is tested this way. Don't add a redundant `*Test.groovy`
+ for, or report "missing tests" on, behaviour already covered by
+ such a block; add/extend the inline block instead. See
+ [Inline Javadoc tests](../../../CONTRIBUTING.md#inline-javadoc-tests).
+
## Procedure
When writing or modifying a test:
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 050936e033..2147f285a7 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -20,3 +20,21 @@
See [`../AGENTS.md`](../AGENTS.md) for project-specific guidance for AI
coding assistants contributing to Apache Groovy, including ASF licensing
and provenance requirements.
+
+## Reviewing tests (inline Javadoc tests)
+
+Groovy tests many methods inline: a `<pre class="...groovyTestCase">`
+block inside a Javadoc/GroovyDoc comment is **extracted and executed as
+a real JUnit test** by `groovy.test.JavadocAssertionTestSuite`
+(`src/test/groovy/MainJavadocAssertionTest.groovy` for `src/main`;
+subprojects have their own `*JavadocAssertionTest`). This is the
+standard test form for the GDK (`DefaultGroovyMethods`,
+`ArrayGroovyMethods`, and similar) — the worked `assert` examples in a
+method's Javadoc *are* its test suite.
+
+Therefore, when a change adds or contains `groovyTestCase` Javadoc
+blocks covering the new behaviour, **do not flag it as "missing tests"
+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).
diff --git a/AGENTS.md b/AGENTS.md
index a5146643c9..9caacfc102 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -79,6 +79,16 @@ The short form:
JDK 17+ is required. Use the Gradle wrapper (`./gradlew` / `gradlew.bat`);
do not invoke a system `gradle`.
+Note the **inline Javadoc test** convention: a
+`<pre class="...groovyTestCase">` block in a Javadoc/GroovyDoc comment
+is extracted and run as a real JUnit test by
+`groovy.test.JavadocAssertionTestSuite`. It is the standard test form
+for the GDK (`DefaultGroovyMethods`, `ArrayGroovyMethods`, …) — adding
+such blocks *is* adding tests; don't add or demand a separate
+`*Test.groovy` for behaviour already covered by them. Canonical
+detail: "Inline Javadoc tests" in
+[`CONTRIBUTING.md`](CONTRIBUTING.md).
+
## Coding conventions
Follow what's already in the tree. Specifically:
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 926d64a381..e8fce3058f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -155,6 +155,25 @@ Static helpers worth knowing:
- `gls.CompilableTestSupport` — base class used by spec tests when a
test needs to assert a snippet compiles.
+### Inline Javadoc tests
+
+Groovy has a first-class testing form that is easy to miss: a
+`<pre class="...groovyTestCase">` block inside a Javadoc/GroovyDoc
+comment is **executed as a real test**. `groovy.test.JavadocAssertionTestSuite`
+/ `JavadocAssertionTestBuilder` scan source comments, extract each such
+block, and run its `assert` statements as JUnit tests
+(`src/test/groovy/MainJavadocAssertionTest.groovy` covers `src/main`;
+subprojects have their own `*JavadocAssertionTest`). This is the
+standard way the GDK (`DefaultGroovyMethods`, `ArrayGroovyMethods`,
+etc.) is tested — the worked examples in a method's Javadoc *are* its
+test suite, doubling as documentation.
+
+Consequences when adding or reviewing a GDK-style method: a change that
+adds `groovyTestCase` blocks covering the new behaviour **is** adding
+tests — there need not be a separate `*Test.groovy`. Conversely, an
+`assert` in such a block that doesn't hold will fail the build, so keep
+the examples runnable and correct.
+
### Regression tests for JIRA fixes
Every bug fix that has a JIRA needs a test that fails on `master`
