groovy-tests
暂无简介
- License 许可
- Apache-2.0
- 所属仓库
- apache/groovy
- 最近更新
- 2026-11-15
- Stars
- ★ 5.5k
- Forks
- 1.9k
03 SKILL.md 正文
<!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->
name: groovy-tests
description: AI-tooling guardrails for writing and modifying tests in the Apache Groovy repository — points at the project's test conventions in CONTRIBUTING.md (JUnit 5 framework, Groovy<NNNN> regression-test naming, executable-AsciiDoc pattern, targeted runs, test-writing pitfalls), then adds the AI-specific constraints on top: no fabricated assertions, no assert false theatre, regression tests that actually fail on master before the fix, no scratch files left in the working tree, hand-back for human review. Use when writing or modifying tests under src/test/, src/spec/test/, or a subproject's src/test/.
license: Apache-2.0
compatibility: claude, codex, copilot, cursor, gemini, aider
metadata:
audience: contributors to apache/groovy
scope: ai-tooling-test-guardrails
Groovy tests
This skill is the AI-tooling layer over the project's test
conventions. The conventions themselves — JUnit 5 framework, the
Groovy<NNNN> regression-test naming, the executable-AsciiDoc
pattern, targeted Gradle runs, and the platform-portability
pitfalls — live in
CONTRIBUTING.md's "Tests" section.
This skill cites them and adds the AI-specific guardrails: no
fabricated assertions, regression tests that actually exercise the
bug, no scratch files left behind, hand-back for review.
groovy-fix-workflow— pair with when the test is part of a JIRA-tracked fix; that skill owns the AI guardrails for the surrounding fix workflow.groovy-internals— pair with when the test exercises the compiler/runtime.groovy-reproducer— pair with when the test starts as an extracted reproducer.CONTRIBUTING.md— the canonical source for every test convention this skill cites; load alongside.
When to use this skill
Use it for:
- Writing or modifying a regression test for a JIRA-tracked bug.
- Adding or modifying an executable AsciiDoc example.
- Modifying any test under
src/test/,subprojects/<module>/src/test/, orsubprojects/tests-preview/src/test/. - Choosing which Gradle test task to run for fastest feedback.
Don't use it for:
- Pure compiler/runtime changes —
groovy-internalsis the home; this skill complements it for the test side. - User-facing AsciiDoc prose that doesn't include any executable example.
- Build-script changes to
build.gradletest configuration —groovy-buildis the home.
Read first
CONTRIBUTING.md"Tests" — the canonical conventions this skill cites (framework, naming, 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 byJavadocAssertionTestSuiteand is the standard test form for the GDK — see "Inline Javadoc tests" there.ARCHITECTURE.md"Tests" — the test-layout map.COMPATIBILITY.md— what API-affecting tests need to demonstrate.
Top failure modes
These are the recurring mistakes specific to AI tooling writing tests:
-
Regression test that passes by construction. Writing the test after the fix, with assertions that mirror the fix rather than reproducing the bug. The test must fail on
masterbefore the fix is applied — see Fix workflow. Quickest proof: stash the production change, run the targeted test, watch it fail; pop, run, watch it pass. -
Hallucinated assertions. Asserting on output the code doesn't actually produce. Run the test and check the actual output before locking in
assertEquals("x", actual). -
assert false // bugto "force a failure". That tells you nothing about the underlying behaviour. The test should exercise the same path the bug report describes and let it fail naturally;assert <reporter-expected>is fine,assert falseis theatre. -
Ignoring the platform-portability pitfalls. Locale, line endings, Windows path escaping, the
junit.networkgate are all covered in Test-writing pitfalls. AI tooling tends to hard-code platform defaults; check before asserting. -
Scratch test files left in the working tree. When running reproducers or experimenting, AI tooling can leave half-written test files behind.
git statusbefore declaring done; the working tree at hand-back contains only the intentional changes. -
Reaching for Spock by reflex. New tests in this repo are JUnit 5 — see Test framework. Spock works but isn't the house style; don't import
spock.lang.Specificationin a new test class without a specific reason. -
Treating
groovyTestCase-covered behaviour as untested. A<pre class="...groovyTestCase">block in a method's Javadoc is its test (run byJavadocAssertionTestSuite) — the GDK is tested this way. Don't add a redundant*Test.groovyfor, or report "missing tests" on, behaviour already covered by such a block; add/extend the inline block instead. See Inline Javadoc tests. -
Duplicating spec-test coverage into
src/test/. Tests undersrc/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 undersrc/test/or report a spec example as untested. New error/edge/regression coverage belongs in the ordinarysrc/test/tree (it need not double as docs); a good user-facing example belongs in the spec test. See Executable AsciiDoc examples. -
Unused imports or unneeded FQNs in test source. Same source-style rule as production — see Documentation. Inline
<pre class="...groovyTestCase">blocks are published Groovydoc. A// GROOVY-comment above a regression-test method is required, not a violation — see Regression tests for JIRA fixes.
Procedure
When writing or modifying a test:
-
Identify the shape. Regression test (standalone class or method-on-existing) per Regression tests for JIRA fixes, or executable example per Executable AsciiDoc examples.
-
Follow the convention in
CONTRIBUTING.md— naming, JUnit 5 shape, tag/include matching, target tree. -
For a regression test, prove it fails on
masterfirst. See Fix workflow. -
Run targeted before module before full — see Targeted runs.
-
Verify nothing leaks. Clean working tree, no orphaned tagged regions, no half-finished scratch files.
Validation checklist
Before declaring the change ready:
- [ ] Test follows the convention in
CONTRIBUTING.md— JUnit 5 shape, naming, placement. - [ ] Regression test was confirmed to fail on
masterbefore any fix was applied (not after, not by construction). - [ ] Targeted Gradle test run is green.
- [ ] If the change touches an executable example: AsciiDoc and tagged Groovy snippet were edited in the same PR; tag names match; no orphaned tagged regions (see Executable AsciiDoc examples).
- [ ] No platform-default assumptions (locale, line endings, path separators) baked into assertions — see Test-writing pitfalls.
- [ ]
git statusshows no scratch files in the working tree. - [ ] Test source and inline Javadoc match
Documentation. A
// GROOVY-comment on a regression-test method is required, not a violation. - [ ] Commit message references
GROOVY-NNNNNwhere applicable.
References
CONTRIBUTING.md"Tests" — the canonical test conventions (framework, naming, AsciiDoc pattern, pitfalls).CONTRIBUTING.md"Documentation" — source and Groovydoc style (including inline Javadoc tests).ARCHITECTURE.md— overall test layout.COMPATIBILITY.md— what API-affecting tests need to demonstrate..agents/skills/groovy-fix-workflow/SKILL.md— AI guardrails for the surrounding fix workflow..agents/skills/groovy-internals/SKILL.md— AI guardrails for compiler/runtime changes..agents/skills/groovy-reproducer/SKILL.md— pair with when the test starts as an extracted reproducer.