#431: Added JavaDoc for test utils. (#456)

* #431: Added JavaDoc for test utils.
* #431: Replaced deprecated MD link checker. Excluded `testutils` from coverage check.

Author: redcatbear

.github/workflows/broken_links_checker.yml

@@ -16,7 +16,7 @@ jobs:
         run: |
           mkdir -p ./target
           echo '{ "aliveStatusCodes": [429, 200] }' > ./target/broken_links_checker.json
-      - uses: gaurav-nelson/github-action-markdown-link-check@v1
+      - uses: tcort/github-action-markdown-link-check@v1
         with:
           use-quiet-mode: "yes"
           use-verbose-mode: "yes"

doc/changes/changes_4.2.0.md

@@ -4,7 +4,7 @@ Code name: Markdown code blocks
 
 ## Summary
 
-In this release we changed the behavior of the Markdown importer, so that if we are inside a code block, no OFT specification items are found. This is a corner case, but we think that this behavior is what users would expect (#480).
+In this release we changed the behavior of the Markdown importer so that if we are inside a code block, no OFT specification items are found. This is a corner case, but we think that this behavior is what users would expect (#480).
 
 We also added a whole section about understanding and fixing broken links between specification items to the user guide.
 
@@ -23,11 +23,11 @@ Finally, we updated test dependencies and Maven plugins.
 
 * #427: Removed old `CHANGELOG.md` file and merged missing parts into release history.
 * #431: Documented "unwanted coverage" in user guide.
-* #449: Fix parsing past end of "needs" paragraph.
+* #449: Fix parsing past the end of a "needs" paragraph.
 * #440: Added Tag importer support for TOML files.
-* #442: Added support for javascript file extensions `.cjs`, `.mjs` and `.ejs`
+* #442: Added support for JavaScript file extensions `.cjs`, `.mjs` and `.ejs`
 
 ## Refactoring
 
-* #452: Migrated Deployment to new Central Repository mechanism
+* #452: Migrated Deployment to the new "Central Repository" mechanism
 * #454: Fixed deployment to Maven Central

testutil/pom.xml

@@ -13,6 +13,8 @@
     </parent>
     <properties>
         <project.build.outputTimestamp>${reproducible.build.timestamp}</project.build.outputTimestamp>
+        <!-- This is a test module. We don't need code coverage here. -->
+        <sonar.coverage.exclusions>**/*</sonar.coverage.exclusions>
     </properties>
     <dependencies>
         <dependency>

testutil/src/main/java/org/itsallcode/openfasttrace/testutil/CompareAssertions.java

@@ -17,13 +17,49 @@ private CompareAssertions()
         // Not instantiable
     }
 
+    /**
+     * Test that a comparator is consistent with equals and follows the {@link Comparator} contract.
+     * 
+     * @param <T>
+     *            type of objects that may be compared by the comparator
+     * @param comparator
+     *            comparator to test
+     * @param o
+     *            reference object
+     * @param smaller
+     *            an object that is smaller than the reference object
+     * @param equal
+     *            an object that is equal to the reference object
+     * @param greater
+     *            an object that is greater than the reference object
+     * @param nullValueSupported
+     *            {@code true} if the comparator supports null values
+     */
     public static <T> void testComparatorConsistentWithEquals(Comparator<? super T> comparator, T o,
             T smaller, T equal, T greater, boolean nullValueSupported)
     {
         testComparator(comparator, o, smaller, equal, greater, nullValueSupported);
         testConsistencyWithEquals(comparator, o, smaller, equal, greater);
     }
 
+    /**
+     * Test that a comparator follows the {@link Comparator} contract.
+     * 
+     * @param <T>
+     *            type of objects that may be compared by the comparator
+     * @param comparator
+     *            comparator to test
+     * @param o
+     *            reference object
+     * @param smaller
+     *            an object that is smaller than the reference object
+     * @param equal
+     *            an object that is equal to the reference object
+     * @param greater
+     *            an object that is greater than the reference object
+     * @param nullValueSupported
+     *            {@code true} if the comparator supports null values
+     */
     public static <T> void testComparator(Comparator<? super T> comparator, T o, T smaller, T equal,
             T greater, boolean nullValueSupported)
     {
@@ -101,13 +137,41 @@ private static <T> void testConsistencyWithEquals(Comparator<? super T> comparat
         assertEquals(o.equals(greater), comparator.compare(o, greater) == 0);
     }
 
+    /**
+     * Test that a comparable is consistent with equals and follows the {@link Comparable} contract.
+     * 
+     * @param <T>
+     *            type of objects that may be compared
+     * @param o
+     *            reference object
+     * @param smaller
+     *            an object that is smaller than the reference object
+     * @param equal
+     *            an object that is equal to the reference object
+     * @param greater
+     *            an object that is greater than the reference object
+     */
     public static <T extends Comparable<? super T>> void testComparableConsistentWithEquals(T o,
             T smaller, T equal, T greater)
     {
         testComparatorConsistentWithEquals(Comparator.naturalOrder(), o, smaller, equal, greater,
                 false);
     }
 
+    /**
+     * Test that a comparable follows the {@link Comparable} contract.
+     * 
+     * @param <T>
+     *            type of objects that may be compared
+     * @param o
+     *            reference object
+     * @param smaller
+     *            an object that is smaller than the reference object
+     * @param equal
+     *            an object that is equal to the reference object
+     * @param greater
+     *            an object that is greater than the reference object
+     */
     public static <T extends Comparable<? super T>> void testComparable(T o, T smaller, T equal,
             T greater)
     {

testutil/src/main/java/org/itsallcode/openfasttrace/testutil/OsCheck.java

@@ -4,16 +4,25 @@
 
 /**
  * Helper class to check the operating system this Java VM runs in.
- *
+ * <p>
  * please keep the notes below as a pseudo-license:
- *
+ * </p>
+ * <p>
  * http://stackoverflow.com/questions/228477/how-do-i-programmatically-determine-operating-system-in-java
- * compare to
- * http://svn.terracotta.org/svn/tc/dso/tags/2.6.4/code/base/common/src/com/tc/util/runtime/Os.java
- * http://www.docjar.com/html/api/org/apache/commons/lang/SystemUtils.java.html
+ * </p>
+ * <p>
+ * compare to:
+ * </p>
+ * <ul>
+ * <li>http://svn.terracotta.org/svn/tc/dso/tags/2.6.4/code/base/common/src/com/tc/util/runtime/Os.java</li>
+ * <li>http://www.docjar.com/html/api/org/apache/commons/lang/SystemUtils.java.html</li>
+ * </ul>
  */
 public class OsCheck
 {
+    /**
+     * Create a new instance of the operating system check.
+     */
     public OsCheck()
     {
         // Default constructor to fix compiler warning "missing-explicit-ctor"
@@ -41,15 +50,15 @@ public OSType getOperatingSystemType()
     private static OSType detectOperatingSystemType()
     {
         final String os = System.getProperty("os.name", "generic").toLowerCase(Locale.ENGLISH);
-        if ((os.indexOf("mac") >= 0) || (os.indexOf("darwin") >= 0))
+        if (os.contains("mac") || os.contains("darwin"))
         {
             return OSType.MACOS;
         }
-        else if (os.indexOf("win") >= 0)
+        else if (os.contains("win"))
         {
             return OSType.WINDOWS;
         }
-        else if (os.indexOf("linux") >= 0)
+        else if (os.contains("linux"))
         {
             return OSType.LINUX;
         }

testutil/src/main/java/org/itsallcode/openfasttrace/testutil/OsDetector.java

@@ -5,6 +5,10 @@
 
 import org.itsallcode.openfasttrace.testutil.OsCheck.OSType;
 
+/**
+ * Helper class to detect the operating system. Contains assumption methods for
+ * JUnit.
+ */
 public class OsDetector
 {
     private static final OsCheck OS_CHECK = new OsCheck();
@@ -14,21 +18,41 @@ private OsDetector()
         // not instantiable
     }
 
+    /**
+     * Assumes that the current operating system is Windows. If the application
+     * is not running on Windows, the assumption will fail, and the test will be
+     * aborted.
+     */
     public static void assumeRunningOnWindows()
     {
         assumeTrue(OsDetector::runningOnWindows, "not running on windows");
     }
 
+    /**
+     * Assumes that the current operating system is Unix-like OS. If the
+     * application is not running on a Unix-like OS, the assumption will fail,
+     * and the test will be aborted.
+     */
     public static void assumeRunningOnUnix()
     {
         assumeFalse(OsDetector::runningOnWindows, "not running on unix");
     }
 
+    /**
+     * Assumes that the current operating system is Linux. If the application
+     * is not running on Linux, the assumption will fail, and the test will be
+     * aborted.
+     */
     public static void assumeRunningOnLinux()
     {
         assumeTrue(OsDetector::runningOnLinux, "not running on linux");
     }
 
+    /**
+     * Assumes that the current operating system is macOS. If the application
+     * is not running on macOS, the assumption will fail, and the test will be
+     * aborted.
+     */
     public static void assumeRunningOnMacOs()
     {
         assumeTrue(OsDetector::runningOnMac, "not running on macOS");

testutil/src/main/java/org/itsallcode/openfasttrace/testutil/TestAssumptions.java

@@ -6,7 +6,7 @@
 import org.opentest4j.TestAbortedException;
 
 /**
- * Assumptions for unit and integration tests, see {@link TestAbortedException}.
+ * Assumptions for unit and integration tests.
  */
 public class TestAssumptions
 {
@@ -16,12 +16,11 @@ private TestAssumptions()
     }
 
     /**
-     * This ensures that the current JDK supports using the
-     * {@link SecurityManager}. Starting with Java 19 the security manager is
-     * not supported any more.
+     * This ensures that the current JDK supports using Java's security manager.
+     * Starting with Java 19, the security manager is not supported anymore.
      * 
      * @throws TestAbortedException
-     *             if the JVM does not support {@link SecurityManager}.
+     *             if the JVM does not support Java's security manager.
      */
     public static void assumeSecurityManagerSupported() throws TestAbortedException
     {

testutil/src/main/java/org/itsallcode/openfasttrace/testutil/cli/FakeDirectoryService.java

@@ -2,15 +2,36 @@
 
 import org.itsallcode.openfasttrace.api.cli.DirectoryService;
 
+/**
+ * A fake implementation of {@link DirectoryService} that returns a predefined
+ * directory path.
+ * <p>
+ * Normally, the directory service provides the current directory path. This
+ * fake implementation can be used in tests to inject a predefined directory
+ * path.
+ * </p>
+ */
 public class FakeDirectoryService implements DirectoryService
 {
     private final String fakeCurrentDir;
 
+    /**
+     * Create a new {@link FakeDirectoryService} that returns a predefined
+     * directory path.
+     * 
+     * @param fakeCurrentDir
+     *            the directory path to be returned by {@link #getCurrent()}
+     */
     public FakeDirectoryService(final String fakeCurrentDir)
     {
         this.fakeCurrentDir = fakeCurrentDir;
     }
 
+    /**
+     * Get the predefined current directory path.
+     * 
+     * @return the predefined directory path
+     */
     @Override
     public String getCurrent()
     {

testutil/src/main/java/org/itsallcode/openfasttrace/testutil/core/SampleArtifactTypes.java

@@ -1,18 +1,29 @@
 package org.itsallcode.openfasttrace.testutil.core;
 
+/**
+ * Constants for sample artifact types used in tests.
+ */
 public class SampleArtifactTypes
 {
     private SampleArtifactTypes()
     {
         // Not instantiable
     }
 
+    /** Architecture artifact type. */
     public static final String ARCH = "arch";
+    /** Design artifact type. */
     public static final String DSN = "dsn";
+    /** Implementation artifact type. */
     public static final String IMPL = "impl";
+    /** Integration test artifact type. */
     public static final String ITEST = "itest";
+    /** Operator manual artifact type. */
     public static final String OMAN = "oman";
+    /** Requirement artifact type. */
     public static final String REQ = "req";
+    /** Unit test artifact type. */
     public static final String UTEST = "utest";
+    /** User manual artifact type. */
     public static final String UMAN = "uman";
 }