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-archetype.git
The following commit(s) were added to refs/heads/master by this push:
new e2a78787 Add a page on testing an archetype and a Maven 4 note
e2a78787 is described below
commit e2a78787981f8c7a253ee4e38b481c757af53354
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Sat Oct 31 17:58:55 2026 +0000
Add a page on testing an archetype and a Maven 4 note
---
.../src/site/markdown/advanced-usage.md | 2 +-
.../site/markdown/examples/test-an-archetype.md | 132 +++++++++++++++++++++
.../src/site/markdown/index.md.vm | 8 +-
maven-archetype-plugin/src/site/site.xml | 1 +
4 files changed, 141 insertions(+), 2 deletions(-)
diff --git a/maven-archetype-plugin/src/site/markdown/advanced-usage.md
b/maven-archetype-plugin/src/site/markdown/advanced-usage.md
index b7936c6c..c5ca39ee 100644
--- a/maven-archetype-plugin/src/site/markdown/advanced-usage.md
+++ b/maven-archetype-plugin/src/site/markdown/advanced-usage.md
@@ -91,7 +91,7 @@ package: org.example
## Testing
-The user can provide archetype test projects by placing them in
`src/it/projects` folder of their project. Upon creating archetype from the
existing project all the test projects will be executed to verify the archetype
created by this project is good. [Read more](./integration-test-mojo.html)
about testing maven archetype.
+When you create an archetype from a project, the plugin adds a first test
project named `basic` in `src/test/resources/projects`. The
`archetype:integration-test` goal, which runs during `mvn verify` or `mvn
install` of the archetype, generates a project from the archetype for each test
project and can compare it with a reference copy. See [Test an
archetype](./examples/test-an-archetype.html).
## Configuration
diff --git
a/maven-archetype-plugin/src/site/markdown/examples/test-an-archetype.md
b/maven-archetype-plugin/src/site/markdown/examples/test-an-archetype.md
new file mode 100644
index 00000000..b7f57a1c
--- /dev/null
+++ b/maven-archetype-plugin/src/site/markdown/examples/test-an-archetype.md
@@ -0,0 +1,132 @@
+---
+title: Test an archetype
+date: 2026-10-31
+---
+
+<!--
+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.
+-->
+
+# Test an archetype
+
+The `archetype:integration-test` goal 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-packaging/) binds the goal to the
`integration-test` phase, so `mvn verify` runs it after `archetype:jar`.
Running `mvn archetype:integration [...]
+
+When you create an archetype with `archetype:create-from-project`, the plugin
adds a first test named `basic` for you.
+
+## 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 [goal documentation](../integration-test-mojo.html) describes
the layout.
diff --git a/maven-archetype-plugin/src/site/markdown/index.md.vm
b/maven-archetype-plugin/src/site/markdown/index.md.vm
index 65fdb81b..479b661a 100644
--- a/maven-archetype-plugin/src/site/markdown/index.md.vm
+++ b/maven-archetype-plugin/src/site/markdown/index.md.vm
@@ -56,9 +56,14 @@ The archetype plugin has three goals for direct use:
and three goals bound to default lifecycle by ['maven-archetype'
packaging](../archetype-packaging/):
- [archetype:jar](./jar-mojo.html) (bound to the `package` phase) is used to
build the archetype jar artifact.
-- [archetype:integration-test](./integration-test-mojo.html) (bound to the
`integration-test` phase) is used to execute archetype integration tests by
generating sample projects from the just built archetype.
+- [archetype:integration-test](./integration-test-mojo.html) (bound to the
`integration-test` phase) is used to execute archetype integration tests by
generating sample projects from the just built archetype: see [Test an
archetype](./examples/test-an-archetype.html).
- [archetype:update-local-catalog](./update-local-catalog-mojo.html) (bound to
the `install` phase) is used to update the local catalog.
+Maven 4
+-------
+
+On Apache Maven 4.0.0-rc-7, `archetype:generate` and
`archetype:create-from-project` work with version 3.4.1 of this plugin, and so
does `mvn verify` on the archetype they create. Releases of Maven 4 other than
4.0.0-rc-7 have not been checked.
+
Examples
--------
@@ -68,6 +73,7 @@ The following examples show how to use the Archetype Plugin
in more advanced use
- [Generate project using an alternative
catalog](./examples/generate-alternative-catalog.html)
- [Create an archetype from a multi-module
project](./examples/create-multi-module-project.html)
- [Create an archetype with a property
file](./examples/create-with-property-file.html)
+- [Test an archetype](./examples/test-an-archetype.html)
<!-- * Handcrafting an archetype or features available to an archetype when
not created by <<<create-from-project>>> - TBD-->
<!-- * Generate a sub module from an archetype - TBD-->
<!-- * Create an archetype in interactive mode - TBD-->
diff --git a/maven-archetype-plugin/src/site/site.xml
b/maven-archetype-plugin/src/site/site.xml
index c73705a4..db5dca5c 100644
--- a/maven-archetype-plugin/src/site/site.xml
+++ b/maven-archetype-plugin/src/site/site.xml
@@ -43,6 +43,7 @@
<item name="Create an archetype with a property file"
href="/examples/create-with-property-file.html"/>
<item name="Generate project in batch mode"
href="/examples/generate-batch.html"/>
<item name="Generate project using an alternative catalog"
href="/examples/generate-alternative-catalog.html"/>
+ <item name="Test an archetype" href="/examples/test-an-archetype.html"/>
</menu>
<!--menu name="Specification">