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