This is an automated email from the ASF dual-hosted git repository.

slachiewicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-site.git

commit a2a595b2a54a4f4716672c64a9b3059a05ff4ac3
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Sat Oct 31 19:20:06 2026 +0000

    Add a guide to testing archetypes
---
 content/markdown/guides/index.md.vm                |   1 +
 .../introduction/introduction-to-archetypes.md     |   2 +-
 .../guides/mini/guide-creating-archetypes.md       |   2 +-
 .../guides/mini/guide-testing-archetypes.md        | 128 +++++++++++++++++++++
 content/site.xml                                   |   1 +
 5 files changed, 132 insertions(+), 2 deletions(-)

diff --git a/content/markdown/guides/index.md.vm 
b/content/markdown/guides/index.md.vm
index efbda816..9a120dec 100644
--- a/content/markdown/guides/index.md.vm
+++ b/content/markdown/guides/index.md.vm
@@ -40,6 +40,7 @@ User Centre
 - [Repositories](./introduction/introduction-to-repositories.html)
 - [What is an Archetype](./introduction/introduction-to-archetypes.html)
 - [Creating Archetypes](./mini/guide-creating-archetypes.html)
+- [Testing Archetypes](./mini/guide-testing-archetypes.html)
 - [The Dependency 
Mechanism](./introduction/introduction-to-dependency-mechanism.html)
 - [ Optional Dependencies and Dependency 
Exclusions](./introduction/introduction-to-optional-and-excludes-dependencies.html)
 - [Glossary](../glossary.html)
diff --git a/content/markdown/guides/introduction/introduction-to-archetypes.md 
b/content/markdown/guides/introduction/introduction-to-archetypes.md
index 180d3317..42318441 100644
--- a/content/markdown/guides/introduction/introduction-to-archetypes.md
+++ b/content/markdown/guides/introduction/introduction-to-archetypes.md
@@ -43,5 +43,5 @@ For the list of archetypes that Maven provides, see [Maven 
Archetype Bundles](ht
 
 ## What makes up an Archetype?
 
-Archetypes are packaged up in a JAR and they consist of the archetype metadata 
which describes the contents of archetype, and a set of 
[Velocity](https://velocity.apache.org/) templates which make up the prototype 
project. If you would like to know how to make your own archetypes, please 
refer to our [Guide to creating 
archetypes](../mini/guide-creating-archetypes.html).
+Archetypes are packaged up in a JAR and they consist of the archetype metadata 
which describes the contents of archetype, and a set of 
[Velocity](https://velocity.apache.org/) templates which make up the prototype 
project. If you would like to know how to make your own archetypes, please 
refer to our [Guide to creating 
archetypes](../mini/guide-creating-archetypes.html), and to test them, the 
[Guide to testing archetypes](../mini/guide-testing-archetypes.html).
 
diff --git a/content/markdown/guides/mini/guide-creating-archetypes.md 
b/content/markdown/guides/mini/guide-creating-archetypes.md
index decd7054..da0f6b87 100644
--- a/content/markdown/guides/mini/guide-creating-archetypes.md
+++ b/content/markdown/guides/mini/guide-creating-archetypes.md
@@ -160,7 +160,7 @@ The `junit-bom` import in `dependencyManagement` sets the 
version of every JUnit
 
 ## 4. Test the archetype
 
-Before you install the archetype, add at least one integration test. Each test 
is a directory in `src/test/resources/projects/` of the archetype project, 
containing an `archetype.properties` file with the values for the generation 
and a `goal.txt` file with the Maven goals to run in the generated project. It 
can also contain a `reference/` directory with the expected project, and a 
`verify.groovy` script. The `archetype:integration-test` goal, which the 
`maven-archetype` packaging runs d [...]
+Before you install the archetype, add at least one integration test. Each test 
is a directory in `src/test/resources/projects/` of the archetype project, 
containing an `archetype.properties` file with the values for the generation 
and a `goal.txt` file with the Maven goals to run in the generated project. It 
can also contain a `reference/` directory with the expected project, and a 
`verify.groovy` script. The `archetype:integration-test` goal, which the 
`maven-archetype` packaging runs d [...]
 
 ## 5. Install the archetype and run the archetype plugin
 
diff --git a/content/markdown/guides/mini/guide-testing-archetypes.md 
b/content/markdown/guides/mini/guide-testing-archetypes.md
new file mode 100644
index 00000000..483b51ca
--- /dev/null
+++ b/content/markdown/guides/mini/guide-testing-archetypes.md
@@ -0,0 +1,128 @@
+<!--
+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.
+-->
+
+# Guide to Testing Archetypes
+
+The `archetype:integration-test` goal of the [Archetype 
Plugin](/archetype/maven-archetype-plugin/) checks that an archetype still 
generates the project you expect. It generates one project per test from the 
archetype you just built, optionally compares the result with a reference copy, 
runs Maven goals in the generated project, and runs a verification script. The 
[`maven-archetype` packaging](/archetype/archetype-packaging/) binds the goal 
to the `integration-test` phase, so `mvn verify [...]
+
+When you create an archetype with `archetype:create-from-project`, the plugin 
adds a first test named `basic` for you. To write an archetype by hand, see the 
[Guide to Creating Archetypes](./guide-creating-archetypes.html).
+
+## Lay out a test
+
+Each test is a directory under `src/test/resources/projects/` of the archetype 
project. The directory name is only the name of the test:
+
+```text
+src/test/resources/projects/basic
+├── archetype.properties
+├── goal.txt
+├── reference
+│   ├── .mvn
+│   │   ├── jvm.config
+│   │   └── maven.config
+│   ├── pom.xml
+│   └── src
+│       ├── main
+│       │   └── java
+│       │       └── it
+│       │           └── pkg
+│       │               └── App.java
+│       └── test
+│           └── java
+│               └── it
+│                   └── pkg
+│                       └── AppTest.java
+└── verify.groovy
+```
+
+The goal finds tests by looking for `goal.txt` files, so every test needs one. 
The following table lists the files of a test.
+
+| File | Required | Purpose |
+| --- | --- | --- |
+| `archetype.properties` | yes | The values for the generation, such as 
`groupId`, `artifactId`, `version` and `package`, plus every property that the 
archetype requires. |
+| `goal.txt` | yes | The Maven goals to run in the generated project, 
separated by commas, for example `verify`. The file can be empty to skip the 
build. |
+| `reference/` | no | The project that the generation must produce. |
+| `verify.groovy` | no | A Groovy script that runs after the build and checks 
the result. |
+
+The generated `archetype.properties` of the `basic` test looks like this:
+
+```properties
+artifactId=basic
+groupId=archetype.it
+package=it.pkg
+version=0.1-SNAPSHOT
+```
+
+If a required property is missing, the build fails with `Missing required 
properties in archetype.properties` and the names of the missing properties.
+
+## Compare with a reference project
+
+If a test has a `reference/` directory, the goal compares it with the 
generated project before it runs any goals. The comparison is strict:
+
+- Every file and directory of the generated project needs a counterpart in 
`reference/`, and the other way round.
+- The contents must be byte-for-byte equal. By default the line endings count 
too. Set the `ignoreEOLStyle` parameter of the goal to `true` (property 
`archetype.test.ignoreEOLStyle`) to ignore them.
+
+To create the reference, generate the project once without a reference, copy 
the result from `target/test-classes/projects/<name>/project/<artifactId>` into 
`reference/`, and delete the `build.log` file and the `target` directory that 
the build of the generated project leaves there. Review the copy by hand before 
you commit it.
+
+If the trees differ, the build fails and lists the differences. In the 
following example, the `src/test` directory is missing from the reference:
+
+```text
+[ERROR] Remains [src/test/java/it/pkg/AppTest.java, src/test, src/test/java, 
src/test/java/it, src/test/java/it/pkg]
+[ERROR] Failed to execute goal 
org.apache.maven.plugins:maven-archetype-plugin:3.4.1:integration-test 
(default-integration-test) on project project-archetype:
+[ERROR] Archetype IT 'basic' failed: Reference and generated project differs 
(missing: 0, unexpected: 5)
+```
+
+## Verify the result with a script
+
+The goal runs `verify.groovy` after the build of the generated project, or 
directly after the generation if `goal.txt` is empty. The script sees the 
variable `context`, and `context.projectDir` is the generated project. The test 
fails if the script throws an exception or returns a value other than `true` or 
`null`. For example:
+
+```groovy
+def pom = new File(context.projectDir, 'pom.xml')
+assert pom.text.contains('<artifactId>basic</artifactId>')
+assert new File(context.projectDir, 'target/classes/it/pkg/App.class').exists()
+```
+
+A failed assertion fails the build:
+
+```text
+[ERROR] Archetype IT 'basic' failed: post build script failure failure: 
Assertion failed:
+[ERROR] assert pom.text.contains('<artifactId>basicX</artifactId>')
+```
+
+## Run the tests
+
+Run the tests with the lifecycle of the archetype project:
+
+```shell
+$ mvn verify
+[INFO] --- archetype:3.4.1:integration-test (default-integration-test) @ 
project-archetype ---
+[INFO] Processing Archetype IT project: basic
+[INFO] Using following parameters for creating project from Archetype: 
project-archetype:1.0
+[INFO] Project created from Archetype in dir: 
/home/user/project-archetype/target/test-classes/projects/basic/project/basic
+[INFO] Comparing generated project with reference content: 
/home/user/project-archetype/target/test-classes/projects/basic/reference
+[INFO] Invoking post-archetype-generation goals: verify
+[INFO] Post-archetype-generation invoker exit code: 0
+[INFO] BUILD SUCCESS
+```
+
+The build log of the generated project is in 
`target/test-classes/projects/<name>/project/<artifactId>/build.log`. To skip 
the tests, set the property `archetype.test.skip` to `true`.
+
+
+## Test an archetype that needs a parent project
+
+To generate the project below another project, add an 
`archetype.pom.properties` file to the parent directory of the test, with the 
`groupId`, `artifactId` and `version` of the archetype to generate the parent 
from, and an `archetype.properties` file next to it with the properties for 
that parent. The [`archetype:integration-test` goal 
documentation](/archetype/maven-archetype-plugin/integration-test-mojo.html) 
describes the layout.
diff --git a/content/site.xml b/content/site.xml
index 92857db1..a7f42aa2 100644
--- a/content/site.xml
+++ b/content/site.xml
@@ -101,6 +101,7 @@ under the License.
           </item>
           <item name="Archetypes" 
href="/guides/introduction/introduction-to-archetypes.html" collapse="true">
             <item name="Creating Archetypes" 
href="/guides/mini/guide-creating-archetypes.html"/>
+            <item name="Testing Archetypes" 
href="/guides/mini/guide-testing-archetypes.html"/>
           </item>
           <item name="Repositories" 
href="/guides/introduction/introduction-to-repositories.html" collapse="true">
             <item name="Install to Local" 
href="/guides/mini/guide-3rd-party-jars-local.html"/>

Reply via email to