You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by sl...@apache.org on 2026/08/10 01:20:31 UTC
(maven-plugin-testing) branch maven-plugin-testing-3.x updated (59cb83a -> fa173cf)
This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a change to branch maven-plugin-testing-3.x
in repository https://gitbox.apache.org/repos/asf/maven-plugin-testing.git
from 59cb83a Bump apache/maven-gh-actions-shared/.github/workflows/release-drafter.yml from 4 to 5 (#276)
new 7f34f97 Rename the FAQ ahead of converting it
new fa173cf Convert the FAQ from FML to Markdown
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
maven-plugin-testing-harness/src/site/fml/faq.fml | 68 ----------------------
.../src/site/markdown/faq.md | 62 ++++++++++++++++++++
2 files changed, 62 insertions(+), 68 deletions(-)
delete mode 100644 maven-plugin-testing-harness/src/site/fml/faq.fml
create mode 100644 maven-plugin-testing-harness/src/site/markdown/faq.md
(maven-plugin-testing) 02/02: Convert the FAQ from FML to Markdown
Posted by sl...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a commit to branch maven-plugin-testing-3.x
in repository https://gitbox.apache.org/repos/asf/maven-plugin-testing.git
commit fa173cfb904e31484fb4e896bd3e85b4ffb3c12f
Author: Sylwester Lachiewicz <sl...@apache.org>
AuthorDate: Mon Aug 10 02:38:59 2026 +0200
Convert the FAQ from FML to Markdown
This FAQ exists only on this branch: master was frozen and its FML
deleted, so maven-plugin-testing-harness/src/site/fml/faq.fml here is
the only source for the published page.
doxia-converter cannot target FML usefully - the questions come out as
link-reference syntax rather than headings, the [top] back-links become
links to a nonexistent 'top' page, and the contents links lose their #
anchors. The page is written out by hand instead.
Explicit anchors keep the existing deep links working. FML routes every
<faq id> through DoxiaUtils.encodeId, and the rendered anchor is not the
question text: both entries here differ from what a heading alone would
produce. The published anchors have no trailing .3F because the ids omit
the question mark, and the second is What_kinds_of_unit_tests_are_supported
- plural - while the question reads "What kind of unit tests are
supported?". Neither could have been reproduced by relying on the id
Doxia derives from the heading, so both are written out explicitly.
They are written as <a id> rather than <a name>. maven-site-plugin
3.21.0 drops the name attribute from inline HTML anchors while 3.22.0
keeps it; this branch resolves to 3.22.0, so name would have worked here,
but id is the primary path in Xhtml5BaseParser, is the correct HTML5
form, and keeps the page safe if it is ever built with an older
toolchain.
The metadata is the unfenced MultiMarkdown block used by every other
markdown page on this branch, and carries only the title, because the
FML declared only a title. Adding author or date would have introduced
meta elements the published page does not currently have.
Verified by building the site before and after and comparing the set of
anchors the generated faq.html actually serves. All 4 anchors present
before are still present after (7 after, the extra 3 being the ids Doxia
derives from the new headings):
What_is_a_Mojo_Testing_Harness
What_kinds_of_unit_tests_are_supported
bodyColumn
top
The <head> is byte-identical, which also confirms the metadata was
parsed rather than rendered into the page. site.xml needs no edit - both
source paths render to faq.html.
FML generates a [top] back-link after each answer; those are dropped
rather than hand-written. The question renders as an h3 heading rather
than a definition term. Those are the only rendering losses; the
definition list inside the second answer is kept as real <dl> markup.
Generated-by: Claude Opus 5 (1M context)
---
.../src/site/markdown/faq.md | 122 ++++++++++-----------
1 file changed, 58 insertions(+), 64 deletions(-)
diff --git a/maven-plugin-testing-harness/src/site/markdown/faq.md b/maven-plugin-testing-harness/src/site/markdown/faq.md
index d07aa76..bafc7b2 100644
--- a/maven-plugin-testing-harness/src/site/markdown/faq.md
+++ b/maven-plugin-testing-harness/src/site/markdown/faq.md
@@ -1,68 +1,62 @@
-<?xml version="1.0" encoding="UTF-8"?>
+title: Frequently Asked Questions
-<!--
-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
+<!-- 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. -->
- http://www.apache.org/licenses/LICENSE-2.0
+<a id="top"></a>
-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.
--->
+# Frequently Asked Questions
-<faqs id="FAQ" title="Frequently Asked Questions">
- <part id="General">
- <faq id="What is a Mojo Testing Harness">
- <question>What is a Mojo Testing Harness?</question>
- <answer>
- <p>
- A unit test attempts to verify a mojo as an isolated unit, by mocking out the rest of the Maven environment.
- A mojo unit test does not attempt to run your plugin in the context of a real Maven build.
- Unit tests are designed to be fast.
- </p>
- <p>
- This testing library is <b>NOT</b> designed for integration or functional testing:
- <a href="/plugins/maven-invoker-plugin/"><code>maven-invoker-plugin</code></a> is the way to go if you need it,
- which gives you a complete Maven environment at the cost of more resources and time consumption.
- </p>
- </answer>
- </faq>
- <faq id="What kinds of unit tests are supported">
- <question>What kind of unit tests are supported?</question>
- <answer>
- <p>
- <dl>
- <dt>JUnit 5 Extension - <i>@MojoTest</i> annotation</dt>
- <dd>The preferred way to test Mojos is to use the JUnit 5 extension provided by the
- <i>maven-plugin-testing-harness</i>. You can annotate your test class with <code>@MojoTest</code>
- to have the extension set up the necessary Maven components for you. You can then inject your Mojo
- and any required Maven components directly into your test class.
- See <a href="./apidocs/org/apache/maven/api/plugin/testing/package-summary.html">javadocs</a> for examples.
- </dd>
- <dt>TestCase from JUnit - deprecated</dt>
- <dd>You could use the <a href="http://junit.org/">JUnit framework</a> to test your plugin in
- the same way you'd write any other JUnit test cases, i.e. by writing a test class which extends
- <i>TestCase</i>.</dd>
- <dt>TestCase from Plexus - deprecated</dt>
- <dd>Mojos are written to take specific advantage of the <i>Plexus container</i>.
- If you need Plexus container services, you could write your class which extends <i>PlexusTestCase</i>,
- instead of <i>TestCase</i>.</dd>
- <dt>TestCase from Testing Harness - deprecated</dt>
- <dd>If you need to inject Maven objects into your mojo, you could use the <i>maven-plugin-testing-harness</i>.
- The <i>maven-plugin-testing-harness</i> is explicitly intended to test the
- <i>org.apache.maven.reporting.AbstractMavenReport#execute()</i> implementation.</dd>
- </dl>
- </p>
- </answer>
- </faq>
- </part>
-</faqs>
+1. [What is a Mojo Testing Harness?](#What_is_a_Mojo_Testing_Harness)
+2. [What kind of unit tests are supported?](#What_kinds_of_unit_tests_are_supported)
+
+<a id="What_is_a_Mojo_Testing_Harness"></a>
+
+### What is a Mojo Testing Harness?
+
+A unit test attempts to verify a mojo as an isolated unit, by mocking out the rest of the Maven environment.
+A mojo unit test does not attempt to run your plugin in the context of a real Maven build.
+Unit tests are designed to be fast.
+
+This testing library is **NOT** designed for integration or functional testing:
+[`maven-invoker-plugin`](/plugins/maven-invoker-plugin/) is the way to go if you need it,
+which gives you a complete Maven environment at the cost of more resources and time consumption.
+
+<a id="What_kinds_of_unit_tests_are_supported"></a>
+
+### What kind of unit tests are supported?
+
+<dl>
+<dt>JUnit 5 Extension - <i>@MojoTest</i> annotation</dt>
+<dd>The preferred way to test Mojos is to use the JUnit 5 extension provided by the
+<i>maven-plugin-testing-harness</i>. You can annotate your test class with <code>@MojoTest</code>
+to have the extension set up the necessary Maven components for you. You can then inject your Mojo
+and any required Maven components directly into your test class.
+See <a href="./apidocs/org/apache/maven/api/plugin/testing/package-summary.html">javadocs</a> for examples.</dd>
+<dt>TestCase from JUnit - deprecated</dt>
+<dd>You could use the <a href="http://junit.org/">JUnit framework</a> to test your plugin in
+the same way you'd write any other JUnit test cases, i.e. by writing a test class which extends
+<i>TestCase</i>.</dd>
+<dt>TestCase from Plexus - deprecated</dt>
+<dd>Mojos are written to take specific advantage of the <i>Plexus container</i>.
+If you need Plexus container services, you could write your class which extends <i>PlexusTestCase</i>,
+instead of <i>TestCase</i>.</dd>
+<dt>TestCase from Testing Harness - deprecated</dt>
+<dd>If you need to inject Maven objects into your mojo, you could use the <i>maven-plugin-testing-harness</i>.
+The <i>maven-plugin-testing-harness</i> is explicitly intended to test the
+<i>org.apache.maven.reporting.AbstractMavenReport#execute()</i> implementation.</dd>
+</dl>
(maven-plugin-testing) 01/02: Rename the FAQ ahead of converting it
Posted by sl...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a commit to branch maven-plugin-testing-3.x
in repository https://gitbox.apache.org/repos/asf/maven-plugin-testing.git
commit 7f34f9791b506606baf17f643cb4852616f6ae9d
Author: Sylwester Lachiewicz <sl...@apache.org>
AuthorDate: Mon Aug 10 02:37:41 2026 +0200
Rename the FAQ ahead of converting it
Git records a rename plus a rewrite in one commit as a delete and an
add, which stops 'git log --follow'. Splitting the rename out keeps the
history. Please merge or rebase rather than squash.
Generated-by: Claude Opus 5 (1M context)
---
maven-plugin-testing-harness/src/site/{fml/faq.fml => markdown/faq.md} | 0
1 file changed, 0 insertions(+), 0 deletions(-)
diff --git a/maven-plugin-testing-harness/src/site/fml/faq.fml b/maven-plugin-testing-harness/src/site/markdown/faq.md
similarity index 100%
rename from maven-plugin-testing-harness/src/site/fml/faq.fml
rename to maven-plugin-testing-harness/src/site/markdown/faq.md