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">

Reply via email to